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>
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
# 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):
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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
|
|
```
|