Managing Agents

This page covers the day-to-day operations of spawning, inspecting, and terminating agents.

Spawning an Agent

ash spawn path/to/manifest.yaml
# Output: Spawned agent 550e8400-e29b-41d4-a716-446655440000

agentd will:

  1. Parse and validate the manifest
  2. Create an overlayfs workspace for the agent
  3. Derive AppArmor and seccomp profiles from the manifest
  4. Set up cgroups for resource limits
  5. Apply nftables rules for network policy
  6. Spawn the agent binary with SCARAB_AGENT_ID and SCARAB_SOCKET injected
  7. Transition the agent to Init state, then Plan

Listing Agents

ash list
# or
ash ls

Output:

ID                                    NAME              STATE    TRUST       UPTIME
550e8400-e29b-41d4-a716-446655440000  my-agent          Plan     sandboxed   0:01:23
6ba7b810-9dad-11d1-80b4-00c04fd430c8  worker            Act      trusted     0:00:05

Inspecting an Agent

ash info <agent-id>

Shows:

  • Agent ID, name, version, description
  • Trust level and lifecycle state
  • Capabilities list
  • Resource limits
  • Network policy
  • Uptime and spawn timestamp

Terminating an Agent

ash kill <agent-id>

The daemon transitions the agent to Terminate, waits for it to exit gracefully, then cleans up its workspace and releases cgroup resources.

To force-terminate (SIGKILL after timeout):

# (if the agent hangs, the daemon's timeout_secs will force-kill it)

Forcing a State Transition

Administrators can override an agent's lifecycle state:

ash transition <agent-id> plan
ash transition <agent-id> act
ash transition <agent-id> observe
ash transition <agent-id> terminate

Use with care; forcing a transition without the agent's cooperation may leave the agent in an inconsistent state.

Validating a Manifest

Validation runs locally without connecting to the daemon:

ash validate manifest.yaml
# Manifest is valid
# or
# Error: missing required field 'spec.trust_level'

Monitoring Agent State

For production monitoring, watch the daemon's structured log output:

RUST_LOG=info agentd 2>&1 | grep agent_id=<uuid>

Or query the audit log periodically:

ash audit --agent <uuid> --limit 5

Daemon Status

ash status

Shows: daemon version, socket path, number of running agents, uptime, and resource usage summary.

Handling Agent Crashes

If an agent process exits unexpectedly:

  • restart_policy: on-failure will restart it (up to max_restarts times)
  • restart_policy: never (default) leaves it terminated
  • A process_exited audit entry is written with the exit code
  • Anomaly detection may fire if the crash pattern is unusual