Usage Session Daemon

Session daemon

Part of the Usage reference. · ← Previous: Launch scripts · Next: Files & locations →

daemon

Run a background process that logs in to Steam once and serves every other aurelia command over a local socket, so a whole session's worth of commands shares one Steam connection instead of re-authenticating on each call.

aurelia daemon [-s <PATH>]
aurelia daemon list [--json]
aurelia daemon stop [PID] [--json]

Option	Description
-s, --socket <PATH>	Override the socket/pipe path (also settable via AURELIA_DAEMON_SOCKET).

aurelia daemon list shows running daemons with their PID and command line. aurelia daemon stop terminates the daemon(s), or just one when given a PID from the list. These run locally and never forward to (or auto-spawn) the daemon they manage. See also kill, which terminates every aurelia process. JSON shapes: { "daemons": [{ "pid", "command" }] } and { "killed", "pids" }.

Why: Aurelia is otherwise a per-invocation CLI: each command opens a fresh Steam CM connection and re-authenticates with the stored refresh token. Steam throttles repeated logons aggressively (surfacing as RateLimitExceeded, or even a transient invalid credentials lockout), which a front-end that polls Aurelia (e.g. Heroic) trips easily. The daemon collapses that to a single logon per daemon lifetime.

How it works:

• One server. Start aurelia daemon once (e.g. at Heroic startup). It restores the saved session in the background and listens on a per-user endpoint: a Unix domain socket ($XDG_RUNTIME_DIR/aurelia-<uid>.sock) on Linux/macOS, or a named pipe (\\.\pipe\aurelia-<user>) on Windows.
• Transparent forwarding. Every other aurelia <cmd> automatically connects to the daemon and runs there against the shared session, relaying stdin, stdout, stderr and the exit code, so the command behaves exactly as if run directly. If no daemon is running, an invocation auto-spawns one and then connects.
• Opt out. Set AURELIA_NO_DAEMON=1 to force a command to run standalone (its own one-off logon), bypassing the daemon entirely.
• Login/logout performed through the daemon update its shared session in place, so subsequent commands immediately use the new (or cleared) credentials.

aurelia daemon                       # start the shared-session server (run once)
aurelia daemon --socket /tmp/a.sock  # custom endpoint
aurelia info 730 --json              # auto-connects to the daemon (or spawns one)
AURELIA_NO_DAEMON=1 aurelia info 730 # bypass the daemon, run standalone

Staying healthy. The daemon keeps its session alive with Steam's connection heartbeat, and self-heals if it drops: a background liveness probe re-establishes the shared session if the connection dies, and a failed session restore is retried (after a short backoff) on a later command rather than wedging the daemon. aurelia login --reconnect forces an immediate re-establish. If no session is stored, commands needing auth return a clean not logged in error. If a session is stored but the daemon's last restore failed, they report why instead, with the classified error type (e.g. rate_limited with retry_after_seconds, or auth_required for a rejected token, see Exit codes). A throttled restore is not retried blindly. Run aurelia login (which the daemon picks up) to establish the shared session.

Session encryption. The daemon reads the session.json key from the OS keyring by itself, the same way the CLI does, so no password or environment variable has to be handed to it. See Session storage.

Fixed in v0.1.38: restoring a session rewrites session.json. The daemon used to remember the file's timestamp from before that rewrite, so it saw a "changed" session on every forwarded command and logged on again each time. Commands that touch the session twice (e.g. user <friend name>, wishlist <friend name>) could lose their connection mid-call. The daemon now records the timestamp after the restore.

kill

Terminate every running aurelia process, including the session daemon. Useful after deploying a new binary (the long-lived daemon keeps running the old code until restarted).

aurelia kill [--json]

The invoking process is excluded, so the command lives long enough to report its result. To stop only daemons, use daemon stop instead. The --json result is { "found", "killed", "pids" }.

aurelia kill