Agent Manifests

Agent manifests are YAML files that fully declare an agent's identity, capabilities, resource limits, and lifecycle behavior. agentd reads a manifest at spawn time to set up sandboxing, derive AppArmor and seccomp profiles, and enforce capability checks.

Minimal Example

apiVersion: scarab/v1
kind: AgentManifest
metadata:
  name: hello-agent
  version: 1.0.0
spec:
  trust_level: untrusted
  capabilities:
    - tool.invoke:echo

Full Field Reference

apiVersion: scarab/v1          # Required. Always "scarab/v1".
kind: AgentManifest            # Required. Always "AgentManifest".

metadata:
  name: <string>               # Required. Unique agent name.
  version: <semver>            # Required. e.g. "1.0.0"
  description: <string>        # Optional. Human-readable description.

spec:
  trust_level: <level>         # Required. untrusted|sandboxed|trusted|privileged
  task: <string>               # Optional. Goal text. Injected as SCARAB_TASK.
  model: <model-id>            # Optional. LLM model. Injected as SCARAB_MODEL.

  resources:                   # Optional.
    memory_limit: <size>       # e.g. 512Mi, 2Gi
    cpu_shares: <int>          # cgroup cpu.shares value
    max_open_files: <int>      # file descriptor limit

  capabilities:                # Required. List of capability strings.
    - <capability>

  network:                     # Optional.
    policy: none|local|allowlist|full
    allowlist:                 # Required if policy is "allowlist"
      - <host:port>

  lifecycle:                   # Optional.
    restart_policy: never|on-failure|always
    max_restarts: <int>
    timeout_secs: <int>

  command: <path>              # Optional. Binary to spawn.
  args:                        # Optional. Arguments passed to the binary.
    - <arg>

  secret_policy:               # Optional. Pre-approval rules for credential access.
    - label: <string>
      secret_pattern: <glob>
      tool_pattern: <glob>
      host_pattern: <glob>     # Optional
      expires_at: <iso8601>    # Optional
      max_uses: <int>          # Optional
      agent_matcher:           # Optional
        type: any|by_id|by_name_glob|by_trust_level
        id: <uuid>
        pattern: <glob>
        level: <trust-level>

  # Agent Store / runtime fields (Phase 8.0)
  runtime: native|python|node  # Execution runtime
  entrypoint: <path>           # Script entrypoint (for python/node)
  packages:                    # Packages to install for the runtime
    - <package-name>

  # MCP auto-attach (Phase 8.1)
  mcp_servers:                 # MCP servers to auto-attach at spawn
    - <server-name>

  # Scheduler fields
  workspace:                   # Workspace configuration
    auto_snapshot: <bool>      # Enable automatic snapshots (default: true)
    snapshot_interval_secs: <int>

Examples

Minimal Sandboxed Agent

apiVersion: scarab/v1
kind: AgentManifest
metadata:
  name: file-organizer
  version: 1.0.0
spec:
  trust_level: sandboxed
  capabilities:
    - fs.read
    - fs.write:/home/agent/workspace/**
    - tool.invoke:fs.read
    - tool.invoke:fs.write
    - tool.invoke:fs.list
  network:
    policy: none
  lifecycle:
    restart_policy: on-failure
    max_restarts: 3
    timeout_secs: 3600

LLM Agent with Task and Model

apiVersion: scarab/v1
kind: AgentManifest
metadata:
  name: research-agent
  version: 1.0.0
  description: Researches topics using web search and LLM.
spec:
  task: "Summarize the latest news about renewable energy in 3 bullet points."
  model: "anthropic/claude-opus-4-6"
  trust_level: trusted
  capabilities:
    - tool.invoke:lm.complete
    - tool.invoke:web.search
    - tool.invoke:web.fetch
    - memory.read:*
    - memory.write:*
    - obs.append
  network:
    policy: full
  lifecycle:
    restart_policy: never
    timeout_secs: 300
  command: target/debug/example-agent

Agent Using Secrets

apiVersion: scarab/v1
kind: AgentManifest
metadata:
  name: api-caller
  version: 1.0.0
spec:
  trust_level: trusted
  capabilities:
    - tool.invoke:web.fetch
    - secret.use:my-api-key
  network:
    policy: allowlist
    allowlist:
      - "api.example.com:443"
  secret_policy:
    - label: "API access"
      secret_pattern: "my-api-key"
      tool_pattern: "web.fetch"
      host_pattern: "api.example.com"

Validation

ash validate path/to/manifest.yaml

Validation checks:

• Required fields are present
• trust_level is a valid value
• Capabilities are parseable
• Network policy is consistent
• apiVersion and kind are correct