# @unwita-insights/super-agent-daemon

Run the **Super Agent** remote backend on your own Linux server — the
self-hosted alternative to the managed Fly.io option. The Super Agent desktop
app connects to this daemon over SSH + WebSocket and drives multi-agent
workflows on your machine.

This is the same daemon the managed option runs, delivered as an npm package so
it lives on your box as a **normal process** — read its logs with `journalctl` /
`tail`, no container to exec into.

## Requirements

- **Linux x86-64** (this package is `os: linux`, `cpu: x64`).
- **Node.js ≥ 20** (you already have it if you're running `npm`).
- **`gh`** (GitHub CLI) on `PATH` — used for auth + cloning. Install:
  <https://github.com/cli/cli#installation>.
- An **SSH server** the app can reach (the daemon uses your host's own `sshd`).

## Install

```sh
npm install -g @unwita-insights/super-agent-daemon
```

That single command also pulls `@anthropic-ai/claude-code` and
`@agentclientprotocol/claude-agent-acp` and puts their `claude` / acp runners on
your `PATH` — the daemon needs them and finds them there automatically.

## Run

```sh
super-agent-daemon daemon start    # forks a detached process (nohup built-in)
super-agent-daemon daemon logs     # tail ~/.super-agent/daemon.log
super-agent-daemon daemon status   # running? prints the PID
super-agent-daemon daemon stop     # stop it
```

`daemon start` self-detaches (survives logout), captures stdout+stderr to
`~/.super-agent/daemon.log`, and records the PID — no `nohup` needed. Running
the bare `super-agent-daemon` with **no subcommand launches the desktop UI**, so
the `daemon` subcommand is required on a server.

The daemon listens on `[::]:9000` by default (override with `SUPER_AGENT_BIND`).
You do **not** need to open port 9000 in your firewall: the app reaches the
daemon over an **SSH tunnel**, so the WebSocket rides inside your existing SSH
connection and only **port 22 (SSH)** has to be reachable from the laptop. The
daemon port stays on the server's loopback — never exposed to the network.

### Run it as a service (recommended)

For a long-lived deployment, a systemd unit gives you restart-on-crash and
`journalctl` logs:

```ini
# /etc/systemd/system/super-agent.service   (run as your dedicated user)
[Unit]
Description=Super Agent daemon
After=network.target

[Service]
User=superagent
# Use `daemon run` (foreground) under systemd — it supervises the process.
# Find the real path with: which super-agent-daemon
ExecStart=/usr/local/bin/super-agent-daemon daemon run
Restart=on-failure
Environment=SUPER_AGENT_BIND=[::]:9000

[Install]
WantedBy=multi-user.target
```

```sh
sudo systemctl enable --now super-agent
journalctl -u super-agent -f
```

## User isolation

Isolation is handled by the OS, not the daemon: create a **dedicated Unix user
per Super Agent user** and run the daemon as that user. Each user's repos,
Claude credentials (`~/.claude`), and `gh` auth (`~/.config/gh`) are then walled
off by normal file permissions.

```sh
sudo useradd -m -s /bin/bash superagent-alice
sudo -iu superagent-alice
npm install -g @unwita-insights/super-agent-daemon
```

## Updating

```sh
npm update -g @unwita-insights/super-agent-daemon
```

Then restart the daemon (or `systemctl restart super-agent`).

---

Part of [Super Agent](https://github.com/unwita-insights/super-agent). For how
the desktop app wires this up, see `docs/REMOTE_OWN_SERVER.md` in the repo.
