# Cross Code server agent Runs on every server (docs/AGENT-1.0-PLAN.md). It polls Cross Code Hub every 30 seconds for signed jobs, runs the `crosscode` script for them, sends the results, and sends the server's stats every 60 seconds. **It listens on nothing**: no port, no URL; every request goes out to the Hub. ## Joining a server Hub → Servers → **Add server** shows a command with a one-time token (valid an hour): ```bash curl -fsSL https://c-git.crosscode.co.za/joshua/crosscode-platform/raw/branch/main/apps/agent/deploy/install.sh \ | sudo bash -s -- --hub https://hub.crosscode.co.za --token ``` Add `--central` on the central (FastPanel) server: there the agent is read-only and only runs `check-ports` and `status`. The script installs Node 24 if needed, the agent in `/opt/crosscode/agent/releases/` (with `current` pointing at it), the `crosscode` script in `/opt/crosscode/tools` (church servers), makes the server's two key pairs, joins, and starts `crosscode-agent.service`. ## On the server | What | Where | |------|-------| | Config (Hub address, server id, the Hub's pinned job key) | `/etc/crosscode/agent.json` | | Private keys (never leave the server) | `/etc/crosscode/agent-ed25519.pem`, `agent-x25519.pem` | | Seen job ids (90 days), unsent reports, exports in progress | `/var/lib/crosscode-agent/` | | A job's opened config, only while it runs | `/run/crosscode-agent/` | | Logs | `journalctl -u crosscode-agent` | ## Security - **Jobs are signed** by the Hub's job key (Ed25519, pinned when joining). The agent refuses a job that's unsigned, for another server, outside its time window, already seen, of an unknown type, or with an argument outside its schema. Refusals are reported to the Hub. - **Only the `crosscode` script runs**, with arguments built from the checked job (an array, never a shell). There's no "run this command" job. - **Config** (database admin, server settings) arrives sealed to this server's X25519 key. It's opened into a root-only file for the job and removed straight after. - **Log lines** sent with a report are filtered for passwords, tokens, keys and licence keys. - **Exports** are encrypted on the server with a new key; the key travels in the job's report so the Hub can email the download link, and the Hub doesn't store it. ## Updates An `update-agent` job builds the new release next to the running one, switches `current`, and restarts. If the new agent hasn't polled the Hub within 150 seconds, `revert.sh` switches back. ## Development ```bash npm run build -w apps/agent # dist/cli.js: one file, everything bundled npm test -w apps/agent # the no-listening-socket test runs on Linux, after a build ```