apps/agent (docs/AGENT-1.0-PLAN.md §3-4, §10): listens on nothing; checks every job (pinned Hub key, server, time window, replays for 90 days, type per mode, strict arguments) before running crosscode with an argument array; opens the sealed config into a root-only file only for the job; redacts log lines; keeps unsent reports in an outbox; encrypts exports before upload; check-ports on the central server (read-only); self-update with automatic revert. One bundled dist/cli.js, a systemd unit and the install script that joins a server with a one-time token. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2.7 KiB
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):
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 <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/<version> (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
crosscodescript 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
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