--- name: "amuleapi" section: "1" platform: "linux" package: "amule" version: "1:3.2.0-1" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/amuleapi" --- # amuleapi(1) the aMule REST API + Server-Sent Events daemon ## NAME amuleapi - the aMule REST API + Server-Sent Events daemon ## SYNOPSIS \[**-h** ***\***\] \[**-p** ***\***\] ## DESCRIPTION serves a JSON REST API and a live event stream for a running [**amuled**(1)](/amuled/1.md), so other programs can control aMule over HTTP. It connects to amuled the same way [**amulecmd**(1)](/amulecmd/1.md) does, and listens on its own port, so it can run at the same time as [**amuleweb**(1)](/amuleweb/1.md). The wire contract for the REST API is documented at *docs/api/REFERENCE.md*; the SSE event catalog lives at *docs/api/EVENTS.md*. See *docs/QUICKSTART-AMULEAPI.md* for first-run setup notes. ## OPTIONS - **\[ -h** *\*, **--host**=*\* **\]** EC host to connect to (default: 127.0.0.1). - **\[ -p** *\*, **--port**=*\* **\]** EC port on the amuled instance (default: 4712). - **\[ --bind**=*\* **\]** HTTP bind address (default: 127.0.0.1, overrides amuleapi.conf \[Server\]/BindAddress). - **\[ --http-port**=*\* **\]** HTTP listen port (default: 4713, overrides amuleapi.conf \[Server\]/Port). - **\[ --config-dir**=*\* **\]** Path to the amuleapi config dir. Defaults to the same per-platform aMule data directory that **amuled** uses (~/.aMule/ on Linux, ~/Library/Application Support/aMule/ on macOS, %APPDATA%\\aMule\\ on Windows). Creates the dir with mode 0700 if absent. - Do not encrypt the link to [**amuled**(1)](/amuled/1.md). Encryption is on by default whenever the remote aMule supports it. Turning it off lets anyone watching the connection read and alter everything after the login. Same as **Encryption=0** in *amuleapi.conf*. - Always compress the link to [**amuled**(1)](/amuled/1.md). By default amuleapi skips compression when amuled's address is on the local network. Use this when that address is a VPN tunnel over a slow Internet link. - Set the admin password from stdin, then exit. Terminal input is hidden and confirmed; redirected stdin supplies one UTF-8 line without confirmation. An empty admin password is rejected. EOF and input errors leave credentials unchanged. No HTTP server or EC connection is started. - As above for the guest password. An explicitly empty line disables guest access; EOF does not. Choose exactly one password setter per invocation. - Read the existing EC password from stdin (hidden on a terminal, without confirmation), write its MD5 digest to \[EC\]/PasswordMD5 in amuleapi.conf, remove the plaintext \[EC\]/Password key, and exit. Other settings are preserved; INI formatting and comments may change. Empty input is rejected. - **\[ --set-admin-pass**=*\* **\]** Set the admin password to *\*, storing it salted and stretched in *amuleapi-passwords* (mode 0600), then exit. Does not start the HTTP server or connect to amuled. A stored password cannot be read back, only replaced. Prefer the stdin form: literal passwords can be exposed through process arguments and shell history. - **\[ --set-guest-pass**=*\* **\]** Set the guest password to *\*, storing it the same way, then exit. An empty *\* clears the guest password, which is how guest access is turned off. - **\[ --foreground \]** Stay in the foreground (default). aMule does not ship init-system units; if you need a system service wrapper, write a downstream unit that wraps the foreground command. - **\[ --log-file**=*\* **\]** Write a copy of the console output to *\*. On by default at *\/amuleapi.log*, so there is always a log to attach to a bug report; use this to put it somewhere else. It is capped at 10 MiB and rotated to *\.1*, so it cannot grow without bound. Each line starts with the local date and time, on the console as well as in the file. - **\[ --no-log-file \]** Disable the log file entirely and print to the console only, still timestamped. - **\[ --version \]** Print version information and exit. - **\[ --help \]** Print a short usage description. ## FILES - *~/.aMule/amuleapi.conf* Settings file: HTTP address and port, the connection to amuled, login rate limits and event-stream sizing. The QUICKSTART document shipped with the source has the full reference. - For standalone use, set the EC password with **--set-ec-pass-stdin**, or copy its MD5 digest from \[EC\]/Password in remote.conf to \[EC\]/PasswordMD5 here. Plaintext \[EC\]/Password is also supported. Set only one: amuleapi refuses to start if both are nonempty or PasswordMD5 is not 32 hexadecimal characters. The digest logs in to amuled just like the password, so keep this file private. - *~/.aMule/amuleapi-jwt-secret* Key used to sign login tokens. Created on first launch. Deleting it signs out everyone. - *~/.aMule/amuleapi-passwords* The admin and guest passwords, stored so they cannot be read back, only replaced. This is the only place they are kept. Set them with **--set-admin-pass-stdin** / **--set-guest-pass-stdin**, from the REST API, or from the Remote Controls preferences in [**amule**(1)](/amule/1.md). A change applies at the next login and signs out anyone already logged in. - *~/.aMule/amuleapi-ec-token* Short-lived login token, written by [**amule**(1)](/amule/1.md) / [**amuled**(1)](/amuled/1.md) when they start amuleapi themselves. Created fresh each time, read once and deleted straight away, so an auto-started amuleapi needs no EC password of its own. Started by hand, amuleapi finds no token and uses **\[EC\]/PasswordMD5** (or plaintext **\[EC\]/Password**) from *amuleapi.conf* instead. There is no **--password** option: a password given on the command line is visible through [**ps**(1)](/ps/1.md) for the lifetime of the process, and can persist in shell history, service unit files and wrapper scripts. ## REPORTING BUGS Please report bugs either on our forum (*https://github.com/amule-org/amule/discussions*), or in our bugtracker (*https://github.com/amule-org/amule/issues*). ## COPYRIGHT aMule and all of its related utilities are distributed under the GNU General Public License. ## SEE ALSO ## AUTHOR This manpage was written for the aMule project.