9.8. Container & Channel API Reference¶

This page documents all REST API endpoints added in the NanoClaw release for container execution and multi-channel messaging. All endpoints are prefixed with /api/v1 and require authentication when enabled.

Authentication¶

curl -H "X-API-Key: your-api-key" http://localhost:55765/api/v1/container/runtime

Container Runtime¶

Get Runtime Status¶

GET /api/v1/container/runtime

Returns the detected container runtime backend.

Response:

{
  "available": true,
  "backend": "apple_container",
  "version": "0.2.0",
  "networking": {
    "hostGateway": "192.168.64.1",
    "extraRunArgs": []
  },
  "message": "Apple Container runtime detected"
}

Backend values: "apple_container" | "docker" | null

Container Image¶

Build Agent Image¶

POST /api/v1/container/image/build

Builds the aigo-agent-runner container image asynchronously.

Request Body:

{
  "imageTag": "aigo-agent-runner:latest"
}

Response:

{
  "success": true,
  "imageTag": "aigo-agent-runner:latest",
  "message": "Build completed successfully",
  "output": "..."
}

Check Image Status¶

GET /api/v1/container/image/status

Query Parameters: imageTag (optional, default: aigo-agent-runner:latest)

Response:

{
  "exists": true,
  "imageTag": "aigo-agent-runner:latest",
  "message": "Image is ready"
}

Mount Security¶

Validate Mount¶

POST /api/v1/container/mount/validate

Request Body:

{
  "hostPath": "/Users/alice/projects/myapp",
  "containerPath": "/workspace/extra/myapp",
  "readOnly": true
}

Response:

{
  "allowed": true,
  "canonicalHostPath": "/Users/alice/projects/myapp",
  "message": "Mount validated successfully"
}

Get Mount Allowlist¶

GET /api/v1/container/mount/allowlist

Response:

{
  "allowedRoots": ["/Users/alice/projects"],
  "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws", ".azure", ".gcloud", ".docker", ".kube"]
}

Set Mount Allowlist¶

PUT /api/v1/container/mount/allowlist

Request Body:

{
  "allowedRoots": ["/Users/alice/projects", "/Users/alice/data"],
  "blockedPatterns": [".ssh", ".gnupg", ".env", ".aws"]
}

Credential Proxy¶

Get Proxy Status¶

GET /api/v1/container/credential-proxy/status

Response:

{
  "running": true,
  "port": 3001,
  "mappingCount": 2
}

Start Proxy¶

POST /api/v1/container/credential-proxy/start

Stop Proxy¶

POST /api/v1/container/credential-proxy/stop

Add Credential Mapping¶

POST /api/v1/container/credential-proxy/mappings

Request Body:

{
  "name": "Anthropic API",
  "upstreamUrl": "https://api.anthropic.com",
  "credentialType": "api_key",
  "credential": "sk-ant-..."
}

Response:

{
  "id": "mapping-uuid-...",
  "name": "Anthropic API",
  "placeholder": "CREDENTIAL_PROXY_PLACEHOLDER"
}

Remove Credential Mapping¶

DELETE /api/v1/container/credential-proxy/mappings/{id}

Set Proxy Port¶

PUT /api/v1/container/credential-proxy/port

Request Body:

{"port": 3001}

IPC¶

Create IPC Directories¶

POST /api/v1/container/ipc/directories

Request Body:

{
  "group": "telegram-support",
  "sessionId": "session-abc123"
}

Send Follow-Up Message¶

POST /api/v1/container/ipc/follow-up

Writes a follow-up message to the container's IPC input directory.

Request Body:

{
  "group": "telegram-support",
  "sessionId": "session-abc123",
  "content": "Focus on the authentication module first"
}

Send Close Signal¶

POST /api/v1/container/ipc/close

Writes the _close sentinel to request graceful container shutdown.

Request Body:

{
  "group": "telegram-support",
  "sessionId": "session-abc123"
}

Container Queue¶

List Container Groups¶

GET /api/v1/container/queue/groups

Response:

["telegram-support", "dev-team", "monitoring"]

Get Queue Counts¶

GET /api/v1/container/queue/counts

Response:

{
  "queued": 3,
  "running": 2,
  "total": 5
}

Get Group State¶

GET /api/v1/container/queue/groups/{group}

Get/Set Max Concurrent Containers¶

GET  /api/v1/container/queue/max-concurrent
PUT  /api/v1/container/queue/max-concurrent

PUT Request Body:

{"maxConcurrent": 4}

Group Namespaces¶

List Namespaces¶

GET /api/v1/container/namespaces

Create Namespace¶

POST /api/v1/container/namespaces

Request Body:

{
  "name": "telegram-support",
  "description": "Customer support channel"
}

Get Namespace¶

GET /api/v1/container/namespaces/{name}

Update Namespace¶

PUT /api/v1/container/namespaces/{name}

Delete Namespace¶

DELETE /api/v1/container/namespaces/{name}

Get/Set Group Instructions¶

GET /api/v1/container/namespaces/{name}/instructions
PUT /api/v1/container/namespaces/{name}/instructions

PUT Request Body:

{"instructions": "You are a support agent for Acme Corp..."}

Get/Set Global Instructions¶

GET /api/v1/container/namespaces/global/instructions
PUT /api/v1/container/namespaces/global/instructions

Get Merged Instructions¶

POST /api/v1/container/namespaces/merge-instructions

Request Body:

{"groupName": "telegram-support"}

Response:

{
  "merged": "# Global Instructions\nAlways respond in the same language...\n\n# Group Instructions\nYou are a support agent..."
}

Task Schedules¶

List Schedules¶

GET /api/v1/container/schedules

Create Schedule¶

POST /api/v1/container/schedules

Request Body:

{
  "name": "Daily Report",
  "group": "reporting",
  "prompt": "Generate today's summary report",
  "schedule": {
    "type": "cron",
    "value": "0 9 * * 1-5"
  },
  "containerConfig": {
    "image": "aigo-agent-runner:latest",
    "timeoutSecs": 600,
    "env": []
  },
  "contextMode": "isolated",
  "enabled": true
}

Schedule type values:

cron — value is a cron expression string (e.g., "0 9 * * 1-5")
interval — value is milliseconds as a number (e.g., 300000)
once — value is an ISO 8601 datetime string (e.g., "2026-04-01T02:00:00Z")

Get Schedule¶

GET /api/v1/container/schedules/{id}

Update Schedule¶

PUT /api/v1/container/schedules/{id}

Delete Schedule¶

DELETE /api/v1/container/schedules/{id}

List Schedule Logs¶

GET /api/v1/container/schedules/{id}/logs

Query Parameters:

limit (default: 20, max: 500)
offset (default: 0)

Audit & Monitoring¶

Get Audit Log¶

GET /api/v1/container/audit-log

Query Parameters:

limit (default: 50, max: 500)
group — filter by group name
severity — filter by severity (info, warning, violation, error)

Get Run History¶

GET /api/v1/container/run-history

Query Parameters:

limit (default: 50, max: 500)
group — filter by group name

Get Metrics¶

GET /api/v1/container/metrics

Returns current container metrics including running count, queue depth, and security event counts.

Get Analytics¶

GET /api/v1/container/analytics

Returns aggregated historical analytics (runs per day, success rate, average duration).

Channels¶

List Channels¶

GET /api/v1/channels

Response:

{
  "channels": [
    {"name": "telegram", "connected": true, "statusMessage": "Connected"},
    {"name": "slack", "connected": false, "statusMessage": "Not configured"}
  ]
}

Get Channel Status¶

GET /api/v1/channels/{name}

Send Message¶

POST /api/v1/channels/messages

Request Body:

{
  "chatJid": "tg:123456789",
  "content": "Hello from Backend.AI GO!"
}

List Chats¶

GET /api/v1/channels/chats

Query Parameters:

channel — filter by channel name
limit (default: 100)

Get Chat Messages¶

GET /api/v1/channels/chats/{jid}/messages

Query Parameters:

limit (default: 100, max: 1000)
before — Unix timestamp, return messages before this time

Telegram Channel¶

Connect¶

POST /api/v1/channels/telegram/connect

Request Body:

{"token": "1234567890:ABCdef..."}

Disconnect¶

POST /api/v1/channels/telegram/disconnect

Validate Token¶

POST /api/v1/channels/telegram/validate

Request Body:

{"token": "1234567890:ABCdef..."}

Slack Channel¶

Connect¶

POST /api/v1/channels/slack/connect

Request Body:

{
  "botToken": "xoxb-...",
  "appToken": "xapp-..."
}

Disconnect¶

POST /api/v1/channels/slack/disconnect

Validate Tokens¶

POST /api/v1/channels/slack/validate

Request Body:

{
  "botToken": "xoxb-...",
  "appToken": "xapp-..."
}

Discord Channel¶

Connect¶

POST /api/v1/channels/discord/connect

Request Body:

{"token": "your-discord-bot-token"}

Disconnect¶

POST /api/v1/channels/discord/disconnect

Validate Token¶

POST /api/v1/channels/discord/validate

Request Body:

{"token": "your-discord-bot-token"}

WhatsApp Channel¶

Connect¶

POST /api/v1/channels/whatsapp/connect

Request Body:

{
  "phoneNumberId": "123456789",
  "accessToken": "your-access-token",
  "webhookVerifyToken": "your-verify-token"
}

Disconnect¶

POST /api/v1/channels/whatsapp/disconnect

Validate Configuration¶

POST /api/v1/channels/whatsapp/validate

Webhook Verification (WhatsApp Cloud API)¶

GET /api/v1/channels/whatsapp/webhook

WhatsApp sends a GET request with hub.mode=subscribe, hub.verify_token, and hub.challenge. The endpoint returns the challenge if the verify token matches.

Webhook Receive¶

POST /api/v1/channels/whatsapp/webhook

WhatsApp sends incoming message events here. This endpoint is called by WhatsApp's servers, not by you directly.

Sender Allowlist¶

Get Allowlist¶

GET /api/v1/channels/sender-allowlist

Response:

{
  "enabled": true,
  "entries": [
    {"chatJid": "tg:123456789", "label": "Alice"},
    {"chatJid": "slack:U01ABCDEF", "label": "Bob"}
  ]
}

Set Allowlist¶

PUT /api/v1/channels/sender-allowlist

Request Body:

{
  "enabled": true,
  "entries": [
    {"chatJid": "tg:123456789", "label": "Alice"}
  ]
}