Found in the VM test: npm ci -w packages/contracts -w apps/agent skipped the monorepo root's devDependencies (tsup, typescript), so the agent couldn't be built. --include-workspace-root brings them in. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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