Files
crosscode-platform/apps/agent

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