Files
crosscode-platform/apps/agent
joshuaandClaude Opus 5.5 1eeaf4d94f Agent 1.0.0: polls the Hub for signed jobs, runs crosscode, sends reports and stats
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>
2026-11-17 12:58:08 +02:00
..

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 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

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