> For the complete documentation index, see [llms.txt](https://docs.guayaba.run/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guayaba.run/documentation/api-reference/runtime.md).

# Runtime

Agent lifecycle control (start, stop, pause, reload, health)

## Get agent runtime status

> Returns current status, uptime, and last boot/stop timestamps.\
> Requires \`agent:manage\` scope (master keys always pass).<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/status":{"get":{"tags":["Runtime"],"summary":"Get agent runtime status","description":"Returns current status, uptime, and last boot/stop timestamps.\nRequires `agent:manage` scope (master keys always pass).\n","responses":{"200":{"description":"Agent status","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["created","active","running","paused","stopped","failed","removed"]},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"current_uptime":{"type":"integer","description":"Seconds since last boot (0 if not running)"},"server_timestamp":{"type":"integer","description":"Server time in epoch milliseconds"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Start an agent

> Boots the agent (or resumes from paused).\
> Requires \`agent:manage\` scope. Charges \*\*5 credits\*\*.\
> Subject to subscription guards (max running agents, allowed channels).<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/start":{"post":{"tags":["Runtime"],"summary":"Start an agent","description":"Boots the agent (or resumes from paused).\nRequires `agent:manage` scope. Charges **5 credits**.\nSubject to subscription guards (max running agents, allowed channels).\n","responses":{"200":{"description":"Agent started","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"},"previous_status":{"type":"string"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Stop an agent

> Stops the agent and accumulates uptime. Requires \`agent:manage\` scope. No credit charge.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/stop":{"post":{"tags":["Runtime"],"summary":"Stop an agent","description":"Stops the agent and accumulates uptime. Requires `agent:manage` scope. No credit charge.\n","responses":{"200":{"description":"Agent stopped"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Pause an agent

> Pauses the agent without stopping the container. Requires \`agent:manage\` scope. No credit charge.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/pause":{"post":{"tags":["Runtime"],"summary":"Pause an agent","description":"Pauses the agent without stopping the container. Requires `agent:manage` scope. No credit charge.\n","responses":{"200":{"description":"Agent paused"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Reload agent config

> Hot-reloads the agent configuration without restarting.\
> Agent must be in \`running\` state. Requires \`agent:manage\` scope.\
> Charges \*\*1 credit\*\*.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"schemas":{"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"bio":{"type":"array","items":{"type":"string"}},"knowledge":{"type":"array","items":{"type":"string"}},"channels":{"type":"array","items":{"type":"string"}},"model_provider":{"type":"string"},"status":{"type":"string","enum":["created","active","running","paused","stopped","removed","failed"]},"settings":{"type":"object","properties":{"model":{"type":"string"},"thinking":{"type":"string","enum":["off","low","medium","high"],"default":"medium"},"extra_instructions":{"type":"string","nullable":true},"trusted_proxies":{"type":"array","items":{"type":"string"}},"secrets":{"type":"object","description":"Channel secrets (key-value map)","additionalProperties":{"type":"string"}},"POST_IMMEDIATELY":{"type":"boolean"},"POST_INTERVAL_MIN":{"type":"integer"},"POST_INTERVAL_MAX":{"type":"integer"},"TWITTER_POLL_INTERVAL":{"type":"integer"},"ACTION_TIMELINE_TYPE":{"type":"string","enum":["following","foryou"]},"MAX_ACTIONS_PROCESSING":{"type":"integer"},"ACTION_INTERVAL":{"type":"integer"}}},"secrets_configured":{"type":"object","description":"Map of secret names to boolean (set or not). Values are never exposed.","additionalProperties":{"type":"boolean"}},"face_image_path":{"type":"string","nullable":true},"face_image_generation_prompt":{"type":"string","nullable":true},"auto_generation_prompt":{"type":"string","nullable":true},"auto_enhancement_prompt":{"type":"string","nullable":true},"is_featured":{"type":"boolean"},"last_boot_execution":{"type":"string","format":"date-time","nullable":true},"last_stop_execution":{"type":"string","format":"date-time","nullable":true},"uptime_total_seconds":{"type":"integer"},"user_id":{"type":"string","format":"uuid"},"framework_id":{"type":"string","format":"uuid"},"framework":{"$ref":"#/components/schemas/CatalogFramework"},"hardware_config":{"type":"object","nullable":true,"properties":{"region":{"$ref":"#/components/schemas/CatalogRegion"},"ram":{"$ref":"#/components/schemas/CatalogHardwareOption"},"disk":{"$ref":"#/components/schemas/CatalogHardwareOption"},"gpu":{"$ref":"#/components/schemas/CatalogHardwareOption"},"cpu":{"$ref":"#/components/schemas/CatalogHardwareOption"}}},"client_links":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"link":{"type":"string"}}}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"CatalogFramework":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"icon":{"type":"string","nullable":true},"available":{"type":"boolean"},"tag":{"type":"string","nullable":true}}},"CatalogRegion":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"city":{"type":"string"},"coords":{"type":"object","properties":{"lat":{"type":"number","format":"float"},"lng":{"type":"number","format":"float"}}},"available":{"type":"boolean"}}},"CatalogHardwareOption":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"label":{"type":"string"},"description":{"type":"string","nullable":true},"available":{"type":"boolean"}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InsufficientCredits":{"description":"Payment Required — Insufficient credits","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"required_credits":{"type":"integer"},"available_credits":{"type":"integer"}}}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/agents/{id}/reload":{"post":{"tags":["Runtime"],"summary":"Reload agent config","description":"Hot-reloads the agent configuration without restarting.\nAgent must be in `running` state. Requires `agent:manage` scope.\nCharges **1 credit**.\n","responses":{"200":{"description":"Config reloaded","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"object","properties":{"agent":{"$ref":"#/components/schemas/Agent"}}}}}}}},"400":{"description":"Agent is not running"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/InsufficientCredits"},"403":{"$ref":"#/components/responses/ScopeForbidden"}}}}}}
```

## Agent health check

> Returns health status for a running agent. Requires \`agent:manage\` scope.<br>

```json
{"openapi":"3.0.3","info":{"title":"Guayaba Public API v1","version":"1.0"},"tags":[{"name":"Runtime","description":"Agent lifecycle control (start, stop, pause, reload, health)"}],"servers":[{"url":"https://api.guayaba.run/api/v1","description":"Production"}],"security":[{"PublicApiKey":[]}],"components":{"securitySchemes":{"PublicApiKey":{"type":"http","scheme":"bearer","description":"API key sent as Bearer token. Two types:\n- Master key (`g_master_...`): full access to all agents and endpoints.\n- Agent key (`g_agent_...`): scoped to a single agent with specific permissions.\n"}},"responses":{"Unauthorized":{"description":"Unauthorized — Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ScopeForbidden":{"description":"Forbidden — Key lacks the required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}}}}},"paths":{"/agents/{id}/health":{"get":{"tags":["Runtime"],"summary":"Agent health check","description":"Returns health status for a running agent. Requires `agent:manage` scope.\n","responses":{"200":{"description":"Agent is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"message":{"type":"string"},"agent_status":{"type":"string"},"health":{"type":"object","properties":{"status":{"type":"string"},"launcher":{"type":"string"},"gateway":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/ScopeForbidden"},"503":{"description":"Agent container not running"}}}}}}
```
