@saas-al/agent

The outbound-only management agent that runs on a saas.al deployment box. It opens no inbound port — it dials home to the control plane, pulls pending commands, and applies them. Every command must pass all of these or it is refused (fail-closed):

1. its Ed25519 signature verifies against the control plane's signing key,
2. it is addressed to this box,
3. its verb is in the fixed vocabulary — there is intentionally no shell/exec verb,
4. its sequence is strictly newer than the last applied (no replay),
5. its nonce has never been seen (no replay).

Security

This package contains no secrets. The control plane's public signing key and a one-time bootstrap token are supplied at runtime via the environment (below) — never bundled. The agent's own identity keypair is generated on the box. Publishing the source is safe: protection comes from the signatures and the fixed verb set, not from the code being secret.

Install & run

npm install -g @saas-al/agent
saasal-agent   # configured entirely by environment

| env | meaning | | --- | --- | | AGENT_CP_URL | control-plane base URL (e.g. https://app.saas.al) | | AGENT_ID | this box's stable id (its subdomain) | | AGENT_CP_PUBKEY | the control plane's raw Ed25519 signing key, base64 (to verify commands) | | AGENT_BOOTSTRAP | one-time token to register (optional) | | AGENT_PROJECT | compose project name for this box's stack | | AGENT_COMPOSE_FILE | path to the generated compose file (default /srv/app/compose.yml) | | AGENT_POLL_MS | dial-home interval (default 5000) |

Verb vocabulary

bootstrap, deploy, migrate, snapshot, rollback, health, start, stop, add_domain, remove_domain. Each maps to a fixed argv (docker/compose, nginx, certbot) — never a shell string — so there is no command-injection surface even though execution is real.