Runtime And Fleet

The runtime is a separate execution system, but the platform still owns the public control-plane routes that register, supervise, and configure it.

This section covers the platform-side management contracts for:

• agents
• workers
• execution environments
• fleet and live container state

Agent Routes

Register agent

POST /api/v1/agents/register

Scope: agent

Request body:

{
  "name": "runtime-specialist",
  "protocol": "rest",
  "routing_tags": [
    "typescript",
    "reviewer"
  ],
  "execution_mode": "specialist",
  "issue_api_key": true,
  "heartbeat_interval_seconds": 30,
  "tools": {
    "required": [
      "shell_exec"
    ],
    "optional": [
      "web_fetch"
    ]
  },
  "metadata": {
    "region": "local-dev"
  }
}

Agent registration fields

Field	Contract	Meaning
name	string	Display name for the registered agent.
protocol	enum	Agent protocol contract. rest is the normal runtime path; acp is for ACP-capable agents.
routing_tags	string[]	Claim filter tags that decide which tasks this agent is eligible to receive.
execution_mode	enum	Whether the agent behaves like a specialist, orchestrator, or hybrid.
issue_api_key	boolean	Whether registration should mint and return a fresh agent API key.
heartbeat_interval_seconds	integer	Expected heartbeat cadence for liveness supervision.
tools	structured object	Declared required and optional tool names for capability matching and operator visibility.
worker_id	UUID	Optional backing worker record this agent belongs to.
metadata	arbitrary JSON object	Additional caller-supplied identity or environment details.
acp	structured object	ACP capability declaration, including supported transports, session modes, and ACP-specific capability metadata.
profile	arbitrary JSON object	Extra agent profile metadata for selection or introspection.

Response:

{
  "data": {
    "id": "99999999-9999-9999-9999-999999999999",
    "name": "runtime-specialist",
    "routing_tags": [
      "typescript",
      "reviewer"
    ],
    "status": "active",
    "api_key": "issued-agent-key",
    "metadata": {
      "region": "local-dev",
      "protocol": "rest",
      "execution_mode": "specialist"
    },
    "tools": {
      "required": [
        "shell_exec"
      ],
      "optional": [
        "web_fetch"
      ]
    }
  }
}

api_key is only present when registration is allowed to issue a new agent key.

Agent registration response fields

Field	Contract	Meaning
id	server-generated	Canonical agent id.
routing_tags	server-generated string[]	Effective claim tags after normalization.
status	server-generated enum-like string	Current agent status immediately after registration.
api_key	opaque	Newly issued agent API key when issuance is enabled.
metadata	arbitrary JSON object	Sanitized stored agent metadata.
tools	structured object	Effective required and optional tool declarations.

Heartbeat

POST /api/v1/agents/:id/heartbeat

Scope: agent

Response:

{
  "data": {
    "ack": true,
    "status": "busy"
  }
}

Worker Routes

Register worker

POST /api/v1/workers/register

Scope: worker

Request body:

{
  "name": "local-codex-worker",
  "runtime_type": "codex",
  "connection_mode": "websocket",
  "routing_tags": [
    "typescript"
  ],
  "heartbeat_interval_seconds": 30,
  "host_info": {
    "hostname": "devbox"
  },
  "agents": [
    {
      "name": "local-codex-specialist",
      "routing_tags": [
        "typescript"
      ],
      "execution_mode": "specialist"
    }
  ]
}

Worker registration fields

Field	Contract	Meaning
name	string	Worker display name.
runtime_type	enum	Execution family behind the worker, such as codex, acp, or external.
connection_mode	enum	How the worker expects to receive work and signals.
routing_tags	string[]	Tags inherited into task claim filters for this worker.
host_info	arbitrary JSON object	Machine-level facts useful for operator diagnostics.
heartbeat_interval_seconds	integer	Expected heartbeat cadence for worker supervision.
metadata	arbitrary JSON object	Extra worker metadata.
agents	structured object[]	Optional specialist agents to create and attach to the worker during registration.

Response:

{
  "data": {
    "worker_id": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
    "worker_api_key": "issued-worker-key",
    "agents": [
      {
        "id": "99999999-9999-9999-9999-999999999999",
        "name": "local-codex-specialist",
        "routing_tags": [
          "typescript"
        ],
        "api_key": "issued-agent-key"
      }
    ],
    "websocket_url": "/api/v1/events",
    "heartbeat_interval_seconds": 30
  }
}

Worker registration response fields

Field	Contract	Meaning
worker_id	server-generated	Canonical worker id.
worker_api_key	opaque	Newly issued worker API key.
agents	structured object[]	Any specialist agents created and attached during registration.
websocket_url	server-generated string	Platform websocket endpoint the worker should connect to.
heartbeat_interval_seconds	server-generated integer	Effective worker heartbeat cadence after defaults are applied.

Heartbeat

POST /api/v1/workers/:id/heartbeat

Scope: worker

Request body:

{
  "status": "online",
  "current_task_id": null,
  "metrics": {
    "queue_depth": 0
  }
}

Claim next task

POST /api/v1/workers/:id/next

Scope: worker

Request body:

{
  "agent_id": "99999999-9999-9999-9999-999999999999",
  "workflow_id": "33333333-3333-3333-3333-333333333333",
  "include_context": true
}

Response is either:

• 204 No Content when no task is available
• { "data": <claimed task> } when a task was claimed

Execution Environments

Create environment

POST /api/v1/execution-environments

Scope: admin

Request body:

{
  "name": "Node 22 Tooling",
  "description": "Runtime image with Node, git, and common build tools.",
  "image": "ghcr.io/agirunner/agirunner-runtime:0.1.0",
  "cpu": "2",
  "memory": "4Gi",
  "pullPolicy": "if-not-present",
  "bootstrapCommands": [
    "node --version",
    "git --version"
  ],
  "bootstrapRequiredDomains": [
    "github.com"
  ],
  "operatorNotes": "Default environment for TS delivery tasks."
}

Response shape

Execution environment responses follow this broad shape:

{
  "data": {
    "id": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
    "name": "Node 22 Tooling",
    "source_kind": "custom",
    "catalog_key": null,
    "catalog_version": null,
    "image": "ghcr.io/agirunner/agirunner-runtime:0.1.0",
    "cpu": "2",
    "memory": "4Gi",
    "pull_policy": "if-not-present",
    "compatibility_status": "unknown",
    "support_status": null,
    "verification_contract_version": null,
    "verified_metadata": {},
    "tool_capabilities": {},
    "bootstrap_commands": [
      "node --version",
      "git --version"
    ],
    "bootstrap_required_domains": [
      "github.com"
    ],
    "agent_hint": "Execution environment: Node 22 Tooling"
  }
}

Environment fields

Field	Contract	Meaning
source_kind	enum-like string	Whether the environment was created manually or from a catalog seed.
catalog_key / catalog_version	string / integer	Catalog origin when the environment comes from a curated entry.
image	string	Container image the runtime should launch for this environment.
cpu / memory	string	Resource requests or caps expressed as strings because they flow through platform config rather than a Go type system.
pull_policy	enum	Image pull behavior.
compatibility_status	enum	Current verification verdict, such as unknown, compatible, or incompatible.
support_status	enum-like string or null	Higher-level support posture, for example whether operators have blocked or approved the environment.
verification_contract_version	string or null	Which verification contract version produced the current compatibility result.
verified_metadata	structured object	Structured verification evidence recorded by the platform.
tool_capabilities	structured object	Tool or runtime capabilities discovered or declared for this image.
bootstrap_commands	string[]	Commands the verifier or runtime can run immediately after container start.
bootstrap_required_domains	string[]	Domains the environment must be able to reach for bootstrap or verification.
agent_hint	server-generated	Preformatted hint string the platform can show to help route agents toward the environment.

Create from catalog

POST /api/v1/execution-environments/from-catalog

Scope: admin

Request body:

{
  "catalogKey": "node-22",
  "catalogVersion": 1,
  "name": "Node 22 Tooling",
  "description": "Customized from catalog starter."
}

Verify environment

POST /api/v1/execution-environments/:id/verify

Scope: admin

Response:

{
  "data": {
    "compatibility_status": "compatible",
    "compatibility_errors": [],
    "verification_contract_version": "v1",
    "verified_metadata": {},
    "tool_capabilities": {},
    "probe_output": {}
  }
}

Fleet And Containers

The platform also exposes admin-facing fleet and container routes such as:

• GET /api/v1/fleet/workers
• GET /api/v1/fleet/live-containers
• GET /api/v1/containers

These routes are primarily operator and diagnostics surfaces. Use them when you need live actual-state visibility rather than declarative task or workflow records.