Agents
An agent is a long-running process you install on a host you own. It connects outbound to the Control Plane, heartbeats every 60 seconds, and executes signed work-items dispatched to it. One install = one agent = one slot on your license.
What the agent runs
The agent itself is generic. The kind of work it does — implementing a code change, writing tests, drafting a plan, browsing a URL — is decided by the signed jobs the Control Plane sends it. Each job carries:
- A kind (e.g.
code.implement,test.run,ui.exercise). - A payload — the inputs for that work-item.
- A scope — what files / commands / hosts the job is allowed to touch.
- A signature — proof the job came from the Control Plane.
The agent verifies the signature before executing, then runs the work inside the scope the job declared. Jobs outside scope (or unsigned) are refused.
Lifecycle
- Install —
curl … | sudo bash. Verifies cosign signature; sets up the systemd unit. - Activate — redeem an
act_…token. Receives a license JWT bound to the machine's fingerprint. - Heartbeat — every 60 seconds. Carries version, fingerprint, in-flight count; receives stop/continue + any newly-signed jobs.
- Execute — verify each job's signature, evaluate against the local policy, run, report outcome on the next heartbeat.
- Update — when the Control Plane publishes a new release on this agent's channel, the heartbeat carries an
update_availablehint. The operator runsagentina upgradewhen ready. - Quarantine — set by the Control Plane when an anomaly fires (fingerprint mismatch, suspected clone, etc.). Stops accepting work; recoverable by an admin from
/admin/anomalies. - Terminal — license revoked or admin reset. Agent stops cleanly; bring it back by minting a fresh activation token and re-running the installer.
Capacity
Your license sets two numbers the Control Plane enforces:
max_agents— how many installs your account can run at once. Runagentina statusto see the cap.max_concurrent_tasks_per_agent— how many in-flight jobs a single agent will accept.
Hitting either cap is not a hard error — the Control Plane just queues new jobs for the next slot. If you need more, contact your operator or bump your plan.
The CLI surface
Once installed, everything is accessible from one binary at /opt/agentina/current/agentina. Operators usually run it as the agentina system user.
| Command | Purpose |
|---|---|
agentina activate | Redeem an activation token. Run once per install. |
agentina onboard | Browser-based wizard for first-time setup. Runs a local server on 127.0.0.1. |
agentina status | Print license claims, fingerprint, last heartbeat, version. Read-only. |
agentina run | Start the heartbeat loop in the foreground. Systemd uses this. |
agentina upgrade | Apply a new release. Verifies signature; two-level rollback on failure. |
agentina report | File a support ticket from the host. --logs attaches the last 200 log lines. |
agentina version | Print build info. |
Where state lives on disk
/var/lib/agentina/license.jwt— your signed license. 0600./var/lib/agentina/agent.json— agent id, control-plane URL, registered_at./var/lib/agentina/fingerprint.json— bound machine fingerprint./var/lib/agentina/keypair/— the agent's identity keypair. 0700./var/lib/agentina/bearer.json— short-lived session token. 0600./var/log/agentina/— heartbeat + execution logs.
/var/lib/agentina/ is detected — the agent verifies its installed bundle against a cosign-signed manifest at every boot. If you need to migrate state to a new host, the right path is re-activation, not a file copy.