Agent Runtimes API - Allternit Docs

Overview

The Agent Runtimes API manages external or local agent runtimes. A runtime record tracks a host, a status, a heartbeat, a list of CLI binaries the runtime can execute, and an optional workspace association. Jobs can be dispatched to a runtime; the gateway persists the queued job, runs it through the local agent runtime, and updates the record with the result.

This namespace is served by the Allternit API data-plane node (http://127.0.0.1:8013 on the same machine, or your paired or provisioned node). The hosted Cloud API at https://api.allternit.com does not route it; it relays only agent sessions, canvases, office and beta research/sessions. See Cloud API.

Base URL

http://127.0.0.1:8013/api

Authentication

All requests must include a valid bearer token in the Authorization header.

Runtime object

Field	Type	Description
`id`	string	Unique runtime identifier.
`name`	string	Human-readable name.
`host`	string	Runtime host address.
`agent_clis`	string \| null	JSON array of available CLI binaries.
`status`	string	Current status, e.g. `online`.
`last_heartbeat`	string \| null	ISO 8601 heartbeat timestamp.
`workspace_id`	string \| null	Associated workspace.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 update timestamp.

Job object

Field	Type	Description
`id`	string	Unique job identifier.
`runtime_id`	string	Runtime the job belongs to.
`status`	string	`queued`, `completed`, or `failed`.
`command`	string \| null	Executed command.
`args`	string \| null	JSON array of arguments.
`env`	string \| null	JSON object of environment variables.
`working_dir`	string \| null	Working directory.
`result`	string \| null	JSON result payload.
`exit_code`	integer \| null	Process exit code.
`stdout`	string \| null	Captured standard output.
`stderr`	string \| null	Captured standard error.
`duration_ms`	integer \| null	Execution duration in milliseconds.
`created_at`	string	ISO 8601 creation timestamp.
`updated_at`	string	ISO 8601 update timestamp.

Endpoints

List runtimes

GET /api/agent-runtimes

Returns all runtimes owned by the caller.

Example request

curl -H "Authorization: Bearer $TOKEN" \
  http://127.0.0.1:8013/api/agent-runtimes

Example response

{
  "runtimes": [
    {
      "id": "rt_1a2b...",
      "name": "Local Agent Runtime",
      "host": "127.0.0.1",
      "agent_clis": "[\"allternit-agent\", \"gizzi\"]",
      "status": "online",
      "last_heartbeat": "2026-08-13T14:22:00Z",
      "workspace_id": null,
      "created_at": "2026-08-01T10:00:00Z",
      "updated_at": "2026-08-13T14:22:00Z"
    }
  ]
}

Create a runtime

POST /api/agent-runtimes

Request body

Field	Type	Required	Description
`name`	string	Yes	Runtime name.
`host`	string	Yes	Runtime host.
`agentClis` / `agent_clis`	array	No	CLI binaries available on the runtime.
`workspaceId` / `workspace_id`	string	No	Workspace ID.

Example request

curl -X POST http://127.0.0.1:8013/api/agent-runtimes \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Local Agent Runtime",
    "host": "127.0.0.1",
    "agentClis": ["allternit-agent", "gizzi"]
  }'

Example response

{
  "runtime": {
    "id": "rt_1a2b...",
    "name": "Local Agent Runtime",
    "status": "online"
  }
}

Get a runtime

GET /api/agent-runtimes/:id

Example response

{
  "runtime": {
    "id": "rt_1a2b...",
    "name": "Local Agent Runtime",
    "host": "127.0.0.1",
    "agent_clis": "[\"allternit-agent\", \"gizzi\"]",
    "status": "online",
    "last_heartbeat": "2026-08-13T14:22:00Z",
    "workspace_id": null,
    "created_at": "2026-08-01T10:00:00Z",
    "updated_at": "2026-08-13T14:22:00Z"
  }
}

Update a runtime

PATCH /api/agent-runtimes/:id

At least one field must be provided.

Request body

Field	Type	Description
`name`	string	New name.
`host`	string	New host.
`status`	string	New status.
`agentClis` / `agent_clis`	array	New CLI list.

Example request

curl -X PATCH http://127.0.0.1:8013/api/agent-runtimes/rt_1a2b... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "maintenance"
  }'

Example response

{
  "id": "rt_1a2b...",
  "updated": true
}

Heartbeat a runtime

POST /api/agent-runtimes/:id/heartbeat

Updates last_heartbeat. Optionally updates status.

Request body

Field	Type	Description
`status`	string	Optional new status.

Example request

curl -X POST http://127.0.0.1:8013/api/agent-runtimes/rt_1a2b.../heartbeat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "online"}'

Example response

{
  "id": "rt_1a2b...",
  "heartbeat": "ok"
}

Delete a runtime

DELETE /api/agent-runtimes/:id

Example response

204 No Content

List runtime jobs

GET /api/agent-runtimes/:id/jobs

Returns all jobs for the runtime, newest first.

Example response

{
  "jobs": [
    {
      "id": "job_3f4a...",
      "runtime_id": "rt_1a2b...",
      "status": "completed",
      "command": "allternit-agent",
      "args": "[\"run\", \"agent_018f3a7c...\"]",
      "env": "{\"LOG_LEVEL\": \"info\"}",
      "working_dir": "/tmp",
      "result": "{\"exit_code\": 0, \"stdout\": \"...\", \"stderr\": \"\", \"duration_ms\": 420}",
      "exit_code": 0,
      "stdout": "...",
      "stderr": "",
      "duration_ms": 420,
      "created_at": "2026-08-13T14:20:00Z",
      "updated_at": "2026-08-13T14:20:01Z"
    }
  ]
}

Create a runtime job

POST /api/agent-runtimes/:id/jobs

Queues and immediately dispatches a job on the runtime. The gateway updates the job record with the outcome.

Request body

Field	Type	Required	Description
`command`	string	Yes	Executable or command.
`args`	array	No	Arguments. Defaults to `[]`.
`env`	object	No	Environment variables. Defaults to `{}`.
`working_dir`	string	No	Working directory.

Example request

curl -X POST http://127.0.0.1:8013/api/agent-runtimes/rt_1a2b.../jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "allternit-agent",
    "args": ["run", "agent_018f3a7c..."],
    "env": { "LOG_LEVEL": "info" },
    "working_dir": "/tmp"
  }'

Example response

{
  "job": {
    "id": "job_3f4a...",
    "runtime_id": "rt_1a2b...",
    "status": "completed",
    "exit_code": 0,
    "stdout": "...",
    "stderr": "",
    "duration_ms": 420
  }
}

Error codes

Status	Meaning
`200`	Success.
`201`	Created.
`204`	No content.
`400`	Bad request — no fields to update or invalid body.
`401`	Unauthorized.
`404`	Runtime not found.
`500`	Internal server error.

​Overview

​Base URL

​Authentication

​Runtime object

​Job object

​Endpoints

​List runtimes

​Example request

​Example response

​Create a runtime

​Request body

​Example request

​Example response

​Get a runtime

​Example response

​Update a runtime

​Request body

​Example request

​Example response

​Heartbeat a runtime

​Request body

​Example request

​Example response

​Delete a runtime

​Example response

​List runtime jobs

​Example response

​Create a runtime job

​Request body

​Example request

​Example response

​Error codes

​Related pages

Overview

Base URL

Authentication

Runtime object

Job object

Endpoints

List runtimes

Example request

Example response

Create a runtime

Request body

Example request

Example response

Get a runtime

Example response

Update a runtime

Request body

Example request

Example response

Heartbeat a runtime

Request body

Example request

Example response

Delete a runtime

Example response

List runtime jobs

Example response

Create a runtime job

Request body

Example request

Example response

Error codes

Related pages