Files
crosscode-platform/apps/agent
joshuaandClaude Opus 5.5 f1d6234800 Agent: answer status on the central server itself
Central servers only get the agent (install.sh --central), not the crosscode script, but a
central agent accepts status jobs and ran `crosscode status` for them, which failed with
`spawn /usr/local/bin/crosscode ENOENT`. A central agent now reports its own stats (frps and
the agent version) for status; church servers still run crosscode status.

Also ignores temp/ (local screenshots).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 10:01:22 +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