ProvidersAgentsFeaturesDocsDownload GitHubDownload
Argos home

Daemon handbook

Run Argos as a headless control plane.

Install the standalone daemon, serve a paired browser workspace, stream events over WebSocket, and keep a server-side agent runtime updated without opening the desktop app.

Install daemonView releases
argos-daemon

$ argos-daemon --web --pair

[daemon] Listening on http://127.0.0.1:9527

[daemon] Health: http://127.0.0.1:9527/health

[daemon] Routes: POST /api/v1/route

[daemon] Events: ws://127.0.0.1:9527/api/v1/events

01

Install the daemon

Pick the install path that matches how you manage the host. Each installer resolves the matching GitHub Release asset, verifies the checksum, and places the binary in your user install directory.

macOS / Linux

Homebrew

Best for machines already managed with Homebrew.

bash
brew install dvaJi/tap/argos-daemon

macOS / Linux

Shell installer

Installs to ~/.argos/bin unless ARGOS_INSTALL_DIR is set.

bash
curl -fsSL https://raw.githubusercontent.com/dvaJi/argos/main/distro/install/install.sh | sh

Windows

PowerShell installer

Installs to %USERPROFILE%\.argos\bin unless ARGOS_INSTALL_DIR is set.

powershell
irm https://raw.githubusercontent.com/dvaJi/argos/main/distro/install/install.ps1 | iex

Pin a release when reproducibility matters

Use ARGOS_VERSION=v0.1.0 before the shell installer or$env:ARGOS_VERSION="v0.1.0" before the PowerShell installer.

02

Start local, then pair a browser

bash
argos-daemon --web --pair
bash
curl http://127.0.0.1:9527/health

The health endpoint returns status, version, and uptime. The printed URL contains a short-lived, single-use pairing token. Open it in a browser to establish a revocable session, then the browser connects to the daemon over WebSocket.

Route API

POST /api/v1/route

Event stream

ws://host:port/api/v1/events

Data directory

~/.argos-daemon

03

Configure runtime settings

Flags are best for one-off runs. Environment variables are better for services, containers, and remote machines where config should live outside the process command.

CLI flags

--host <host>

Bind address. Defaults to 127.0.0.1.

--port <port>

Bind port. Defaults to 9527. Use 0 for an automatic port.

--data-dir <path>

Store daemon data in a custom directory. Defaults to ~/.argos-daemon.

--web

Serve the web UI. Defaults to ./web; override with --web-root or ARGOS_WEB_ROOT.

--web-root <path>

Directory containing built web assets. Defaults to ./web.

--pair

Generate a one-time pairing token and print the URL at startup.

--log-level <level>

Use debug, info, warn, or error. Defaults to info.

--no-update-check

Skip the startup update availability check.

Environment

ARGOS_HOST

Same as --host.

ARGOS_PORT

Same as --port.

ARGOS_DATA_DIR

Same as --data-dir.

ARGOS_DESKTOP_BOOTSTRAP

Desktop bootstrap secret (set by Electron main).

ARGOS_WEB

Same as --web (1/true).

ARGOS_WEB_ROOT

Same as --web-root.

ARGOS_LOG_LEVEL

Same as --log-level.

ARGOS_NO_UPDATE_CHECK

Same as --no-update-check.

Remote access

Non-loopback requests require an authenticated session. For browser access, restart with --web --pair and open the printed one-time URL. Desktop-launched daemons receive ARGOS_DESKTOP_BOOTSTRAP automatically.

04

Keep it current

bash
argos-daemon update
bash
sudo systemctl restart argos-daemon

The update command downloads, verifies, and atomically swaps the installed binary. The daemon also checks GitHub Releases on startup and logs when a newer version is available.

Disable update checks

Use this on locked-down hosts or environments that block GitHub API calls.

--no-update-check

ARGOS_NO_UPDATE_CHECK=1

05

Deploy it on a VPS

Linux servers can use the reference unit at distro/systemd/argos-daemon.service. Copy it, adjust the user, binary path, data directory, and environment, then enable the service. Keep the daemon bound to 127.0.0.1; a reverse proxy on the same host should terminate HTTPS and forward HTTP plus WebSocket traffic to it.

bash
sudo install -m 0755 argos-daemon /usr/local/bin/argos-daemon
sudo install -m 0644 distro/systemd/argos-daemon.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now argos-daemon

01

Install the binary

Use the installer that matches the host. The daemon ships as one standalone executable per platform.

02

Start local first

The default bind address is 127.0.0.1 on port 9527. Confirm health before wiring clients.

03

Pair for remote access

Run argos-daemon --web --pair to print a one-time pairing URL for browser clients.

04

Promote to a service

For Linux servers, run it under systemd and put an HTTPS reverse proxy in front of the loopback daemon.

Do not publish the daemon port directly

The daemon speaks plain HTTP and WebSocket. Put it behind a TLS-capable reverse proxy or a private network such as Tailscale, preserve WebSocket upgrades, and expose the proxy rather than port 9527. Argos is a single-user daemon, not a multi-tenant hosted service.

06

Debug the obvious things first

Run `argos-daemon --version` to confirm the installed binary.

Run `argos-daemon --help` to inspect supported flags.

Check `/health` before debugging route or event clients.

Use `ARGOS_LOG_LEVEL=debug` for more detailed logs.

ReleasesIssuesSource

What the browser does not replace

The web workspace covers chat, sessions, providers, MCP, skills, memory, scheduled tasks, sync, and server-side agent runtimes. It does not replace Electron features that need a local operating system.

Use the desktop app for native windows, the embedded browser panel, overlays, and screen capture.

Use the desktop app for file and directory dialogs, opening or revealing local files, and image clipboard actions.

System fonts, app restart and update controls, tray integration, and desktop notifications are not browser features.

Treat web mode as a useful single-user server workspace, not a promise of full desktop parity.