> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# oc agent

> Manage agents, channels, and packages

## `oc agent create <id>`

Create a new agent. [HTTP API →](/api-reference/agents/create)

<ParamField query="--core" type="string" required>
  Managed core to use (e.g. `hermes`, `openclaw`). Required — a core-less agent has no runtime and can't connect channels or install packages. To create a raw agent with your own snapshot, use the [REST API](/api-reference/agents/create) directly.
</ParamField>

<ParamField query="--secret" type="string">
  Secret `KEY=VALUE` (repeatable). Secrets are stored encrypted and injected at sandbox creation.
</ParamField>

<ParamField query="--no-wait" type="boolean">
  Return immediately after the agent record is created, without polling for sandbox readiness. The `async` JSON field indicates the caller should re-check with `oc agent get`.
</ParamField>

```bash theme={null}
oc agent create my-hermes --core hermes
oc agent create my-hermes --core hermes --secret OPENAI_API_KEY=sk-...
```

***

## `oc agent list`

List all agents. **Alias:** `oc agent ls`

[HTTP API →](/api-reference/agents/list)

Output columns: `ID`, `CORE`, `CHANNELS`, `PACKAGES`, `CREATED`

```bash theme={null}
oc agent ls
oc agent ls --json
```

***

## `oc agent get <id>`

Show detailed information for an agent, including instance status. [HTTP API →](/api-reference/agents/get)

Output: ID, Name, Core, Channels, Packages, Created, Instance (ID + status).

```bash theme={null}
oc agent get my-hermes
```

***

## `oc agent delete <id>`

Delete an agent. Cascades to instances and sessions — the sandbox is destroyed. [HTTP API →](/api-reference/agents/delete)

<ParamField query="--yes" type="boolean">
  Skip the confirmation prompt. Required when stdin is not a TTY (e.g. running from a script) — the command otherwise refuses rather than destroying state silently on a typo.
</ParamField>

```bash theme={null}
oc agent delete my-hermes           # interactive: prompts "Delete agent my-hermes? [y/N]"
oc agent delete my-hermes --yes     # script-safe: no prompt
```

***

## `oc agent connect <id> <channel>`

Connect a messaging channel to an agent. [HTTP API →](/api-reference/agents/connect-channel)

<ParamField query="--bot-token" type="string">
  Telegram bot token (Telegram channel only). If omitted and stdin is a TTY, the CLI prompts interactively. If omitted and stdin is not a TTY (scripts, CI, agent callers), the command exits with an error — pass the flag explicitly.
</ParamField>

```bash theme={null}
oc agent connect my-hermes telegram                        # interactive prompt
oc agent connect my-hermes telegram --bot-token 123:ABC    # script-safe
```

***

## `oc agent disconnect <id> <channel>`

Disconnect a channel from an agent. Removes webhook registration and config. [HTTP API →](/api-reference/agents/disconnect-channel)

<ParamField query="--yes" type="boolean">
  Skip the confirmation prompt. Required when stdin is not a TTY.
</ParamField>

```bash theme={null}
oc agent disconnect my-hermes telegram
oc agent disconnect my-hermes telegram --yes
```

***

## `oc agent channels <id>`

List channels connected to an agent. [HTTP API →](/api-reference/agents/list-channels)

```bash theme={null}
oc agent channels my-hermes
```

***

## `oc agent install <id> <package>`

Install a package on an agent. [HTTP API →](/api-reference/agents/install-package)

```bash theme={null}
oc agent install my-hermes gbrain
```

***

## `oc agent uninstall <id> <package>`

Uninstall a package from an agent. Data is preserved by default. [HTTP API →](/api-reference/agents/uninstall-package)

<ParamField query="--yes" type="boolean">
  Skip the confirmation prompt. Required when stdin is not a TTY.
</ParamField>

```bash theme={null}
oc agent uninstall my-hermes gbrain
oc agent uninstall my-hermes gbrain --yes
```

***

## `oc agent packages <id>`

List packages installed on an agent. [HTTP API →](/api-reference/agents/list-packages)

```bash theme={null}
oc agent packages my-hermes
```

***

## Exit codes

`oc agent` commands use a class-based exit code scheme so scripts and agent callers can branch on failure type without parsing stderr.

| Code | Class         | Meaning                                                    |
| ---- | ------------- | ---------------------------------------------------------- |
| 0    | Success       | Command completed successfully                             |
| 1    | General error | Unclassified failure, bad args/flags, aborted confirmation |
| 3    | Upstream 4xx  | Not found, unauthorized, org mismatch, bad request         |
| 4    | Conflict      | Already exists, invalid state transition                   |
| 5    | Transient     | Timeout, retry-safe — try again                            |

Codes 3–5 are emitted by `create`, `install`, and `get` when the failure carries a known error code. Other subcommands exit 0 on success and 1 on any failure.