> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent hosting

> Read and configure hosting for an identity, set idle shutdown, list computer templates, and inspect or retry incoming event deliveries.

Paths are relative to `https://inkbox.ai/api/v1/identities/my-agent`. Authenticate with an API key in `X-API-Key`.

## Read hosting

`GET /hosting`

Admin-scoped keys and the identity's own key can read hosting.

| Field | Meaning |
| - | - |
| `mode` | `external` or `inkbox`. |
| `state` | `disabled`, `provisioning`, `ready`, `removing`, or `error`. |
| `machine_id` | The agent's computer, or null before setup. |
| `harness`, `tier` | `hermes` or `codex`; `medium` is the fixed 1 vCPU / 4 GiB RAM size. |
| `generation`, `applied_generation` | Saved and applied configuration revisions. |
| `default_model` | Model used when a turn doesn't choose one. New agents use `gpt-6.1-terra`. |
| `instructions` | Hosted-agent instructions, separate from voice instructions. |
| `trigger_events`, `default_trigger_events` | Incoming events that start work, and the default selection. |
| `credential_binding_id` | Saved model key, or null for default model access. |
| `idle_timeout_seconds` | Idle period before the computer stops: `60` or `300` seconds. Defaults to `60`. |
| `last_error` | Setup error code, or null. |

## Configure hosting

`PUT /hosting`

Use an admin-scoped key. Pass the current `generation` as `expected_generation`. A stale value returns `409`.

```json theme={null}
{
  "expected_generation": 0,
  "enabled": true,
  "harness": "hermes",
  "tier": "medium",
  "default_model": "gpt-6.1-terra"
}
```

Omitted fields keep their current values. You can also set `instructions`, `trigger_events`, and `credential_binding_id`. Send `reset_instructions: true` to restore the default instructions. An empty `trigger_events` array turns off event-triggered work.

Setup runs in the background. Poll `GET /hosting` until `state` is `ready`. To change `harness`, remove hosting and set it up again. The hosted computer size is fixed.

To remove hosting, send `enabled: false` with the current `expected_generation`. This permanently deletes the computer and its files. The identity and its channels remain.

## Agent credential

Each hosted computer gets a system-managed key scoped to its identity. It doesn't appear on your API keys page. Removing hosting disables it.

## Deliveries

`GET /hosting/deliveries`

Returns up to 100 incoming-event deliveries, each with `id`, `event`, `state`, `attempts`, `received_at`, `last_error`, and `retryable`. Pass `next_before` as `before` for older entries. `accepted` means the agent received the event, not that it finished the work.

`POST /hosting/deliveries/{delivery_id}/retry`

Use an admin-scoped key. Returns `{"queued": true}`, or `409` if the delivery can't be retried.

## Idle shutdown

Choose **1** or **5 minutes** under **Sleep after inactivity** in the Console. The default is **1 minute**. API updates accept `idle_timeout_seconds` values of `60` or `300`. Idle shutdown can't be turned off. Running agent work keeps the computer awake.

## Templates

`GET https://inkbox.ai/api/v1/computers/templates` lists computer templates. `hosted_defaults.codex` and `hosted_defaults.hermes` are the templates new hosting uses, or null when none is available.

Use `client.computers.templates()` in Python and TypeScript, `client.computers().templates()` in Rust, or `inkbox computers templates` in the CLI.

For conversations, usage, terminals, and schedules, see the [hosted chat and workspace API](https://inkbox.ai/docs/api/identities/chat.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.