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

# Host OpenCode

> Run OpenCode, SST's open-source coding agent, on its own always-on instance. Works out of the box on the managed model, no account required.

The `agent37-opencode` [template](/docs/agents-api/templates) runs OpenCode, SST's open-source coding agent, on an Agent37 instance: an always-on computer with the same chat API, sessions, files, and URLs as every other template. The image is lean, with no browser and no desktop. OpenCode works out of the box on the **managed Agent37 model**: no login, no account, no keys. The first chat turn just runs, metered like Hermes against your wallet. Point it at your own provider key when you want a specific model.

## Create the instance

One call to the hosting API at `https://api.agent37.com`:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "agent37-opencode" }'
```

The `201` response carries the instance id and its URL, `https://{instanceId}.agent37.app`, which routes to the gateway on port `3737`. The terminal is on port `7681` and the file browser on `8080`, each at `https://{instanceId}-{port}.agent37.app`; see [Instance and preview URLs](/docs/agents-api/urls).

## Send the first message

Chat is the instance URL plus a path, with the same `sk_live_` key sent as the `X-Agent37-Key` header. `opencode` is the template's default agent, so there is no `agent` field to pass:

```bash curl theme={null}
curl https://ab12cd34ef.agent37.app/v1/responses \
  -H "X-Agent37-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "input": "Clone github.com/expressjs/express and summarize how routing works." }'
```

No account and no key are needed first: the turn runs on the managed default model, `agent37/default`. Set `"stream": true` to receive the turn as Server-Sent Events instead of one JSON body, and reuse the returned `session_id` to continue the thread. See [Send a message](/docs/agents-api/chat) and [Streaming](/docs/agents-api/streaming).

## Sessions

OpenCode manages sessions natively: the `session_id` on a response is OpenCode's own session id, and every [session](/docs/agents-api/sessions) read works against it. `GET /v1/sessions?agent=opencode` lists them, `GET /v1/sessions/{id}` reads a thread's history, `PATCH /v1/sessions/{id}` renames one, and `DELETE /v1/sessions/{id}` removes it. Sessions you start in the instance terminal appear in the list on their own. Omit `session_id` on a turn to start a thread, then reuse the id the response returns.

## Models

`GET /v1/models?agent=opencode` on the instance lists every model OpenCode can run, each as a `provider/model` id: `agent37/default` (the managed model) plus every model of any provider you have registered, for example `openai/gpt-5.2`. Pass one as `model` on a turn. Omit `model` and the turn runs on OpenCode's configured default, `agent37/default`. A bare or malformed id (one that is not a `provider/model` entry from the list) is rejected with `model_error`. See [Models](/docs/agents-api/models).

Set `reasoning_effort` per turn. It maps onto OpenCode's per-model variant, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`, clamped to what the target model advertises, and `none` omits it. See [Send a message](/docs/agents-api/chat).

Usage on `agent37/default` is managed: it meters against your Agent37 wallet like Hermes, bounded by the instance's [budget](/docs/agents-api/budgets). A turn on a model you [brought yourself](#bring-your-own-provider) bills the provider key behind it instead.

## Bring your own provider

To run OpenCode on a specific provider, set that provider's API key as [instance env](/docs/agents-api/instances#environment-variables) on the create call. OpenCode registers the provider automatically at boot, and its models then appear in `GET /v1/models?agent=opencode` as `provider/model` ids:

```bash curl theme={null}
curl -X POST https://api.agent37.com/v1/instances \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "agent37-opencode",
    "env": { "OPENAI_API_KEY": "..." }
  }'
```

The provider follows the key: `OPENAI_API_KEY` registers OpenAI, `ANTHROPIC_API_KEY` Anthropic, `GEMINI_API_KEY` Google, and `OPENROUTER_API_KEY` OpenRouter. Set more than one to register more than one. Then pass the model you want on a turn, for example `"model": "anthropic/claude-sonnet-4-5"`. Model usage bills the key you set, not your Agent37 wallet. The managed `agent37/default` model stays available alongside any provider you add, so a turn that omits `model` still runs managed.

## Connect apps

[App integrations](/docs/agents-api/integrations) work here like on every system template: drive the `/v1/integrations` endpoints to connect your users' Gmail, Slack, Notion, and hundreds of other apps, and the platform registers its Composio MCP server with OpenCode automatically.

## Custom image

To add your own tools, build on the clean base image, which ships OpenCode and the gateway with no managed integrations, the same pattern as `hermes-base`:

```dockerfile theme={null}
FROM ghcr.io/agent37-platform/opencode-base:latest
```

See [Build a custom image](/docs/agents-api/custom-image).

## Troubleshooting

| Symptom                                                                                                | Fix                                                                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A turn fails with `model_error`                                                                        | The `model` was not a `provider/model` id from `GET /v1/models?agent=opencode`. Send a listed id, or omit `model` to run on `agent37/default`.                                                                                                                                                                                                    |
| A model you set a key for is missing from `GET /v1/models?agent=opencode`                              | OpenCode registers a provider from its key at boot. Confirm the key is set as instance [env](/docs/agents-api/instances#environment-variables) under the right name (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, or `OPENROUTER_API_KEY`); a key added after create needs the instance [restarted](/docs/agents-api/instances) to take effect. |
| A first turn on a `session_id` you chose is rejected with `400 validation_error` (`param: session_id`) | OpenCode mints its own session ids: a client cannot bring an unknown `session_id` on the first turn. Omit it to start a thread, then reuse the id the response returns. Sessions you start in the terminal appear in `GET /v1/sessions?agent=opencode` on their own.                                                                              |
| A turn returns `503 agent_unavailable`                                                                 | The OpenCode binary is not present on this instance, so a turn that has to create or resolve a session cannot run. Recreate or [update](/docs/agents-api/instances#update) the instance to a template revision that ships OpenCode.                                                                                                                    |