Agentina

Your first task

You have a heartbeating agent. Now what? This page walks you through dispatching a real piece of work and watching the agent execute it. Plan on ~15 minutes.

Before you start

  • An agent installed and showing as active in /portal/agents.
  • Operator-level access to /admin on the Control Plane, OR a working channel to your operator.
  • The agent ID of the install you want to test against. Find it in agentina status output as agent_id.

1. Dispatch a job

Open /admin/agents, click your agent, and use the Dispatch job action (or call the API directly):

bash
curl -fsSL -X POST https://cp.agentina.io/v1/admin/jobs/dispatch \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "<paste agent id>",
    "kind": "echo",
    "payload": { "message": "hello from operator" },
    "ttl_seconds": 600
  }'

The Control Plane signs the payload (EdDSA, same key as license signing), inserts a row in signed_jobs, and queues it for the next heartbeat.

kind: "echo" is the safest first job — the agent only echoes the payload back, no commands run, no files touched. It exercises the entire sign → deliver → verify → ack loop without any side effects.

2. Watch the agent pick it up

On the host running the agent:

bash
sudo journalctl -u agentina -f

You'll see (within 60 seconds of dispatch):

text
heartbeat: active → active
job received: id=018e… kind=echo
job verified: signature ok, signing_kid=prod-ed25519-2026
job executed: outcome=completed
heartbeat: active → active  # next tick acks the job

3. Verify in the admin UI

Refresh /admin/jobs. The row for your job should transition pending → delivered → completed.

If you click into the row, you'll see:

  • The full signed JWS that was sent.
  • The agent's reported outcome + execution time.
  • The audit trail entry showing who dispatched it.

4. What if something looks wrong

Job stuck on pending

The agent didn't heartbeat. Check sudo systemctl status agentina on the host. If the service is up but no heartbeats are landing, follow heartbeat troubleshooting.

Job stuck on delivered

The agent received it but didn't ack. Two likely causes:

  • Signature failed. The agent's embedded pubkey doesn't match the kid in the JWS header. Check agentina status for the trusted kid set; rotate or refresh the agent build if needed.
  • Policy denied. The job's declared scope tripped a baseline policy rule. Look for a policy.deny line in the agent's logs — it names the rule.

Job came back denied

The local policy refused. Common reasons:

  • A command in the payload contains shell metacharacters (;, |, `).
  • A path traverses (..) or targets /proc//sys//dev.
  • The command isn't in the job's declared scope.allowed_commands.

Re-dispatch with a tighter scope. See what the agent runs for the policy contract.

5. Where to go next