# opencode server guide

How to run `opencode serve` and use `ai` from ComputerCraft directly, no proxy.

See [`opencode_api.md`](opencode_api.md) for the full API reference.

## Architecture

```
CC Computer
  └─ ai.lua  (libai.lua)
       └─ POST /session/:id/message  →  opencode serve
```

## 0. Install TrapOS and the AI package

On a fresh CC computer (beta branch):

```
wget run https://git.trapcloud.fr/guillaumearm/cc-libs/raw/branch/next/install-ccpm.lua --beta
ccpm update
ccpm install trapos
```

## 1. Start `opencode serve`

Local/dev uses opencode's default port `4096`:

```bash
opencode serve --hostname 0.0.0.0 --port 4096
```

Public production uses port `4242`; see [`public-ports.md`](public-ports.md):

```bash
opencode serve --hostname 0.0.0.0 --port 4242
```

With Basic Auth (recommended for LAN exposure):

```bash
OPENCODE_SERVER_PASSWORD=secret opencode serve \
  --hostname 0.0.0.0 \
  --port 4096
```

Default username is `opencode`. Override with `OPENCODE_SERVER_USERNAME=myuser`.

Check it's alive:

```bash
curl http://localhost:4096/global/health
```

With Basic Auth:

```bash
curl -u opencode:secret http://localhost:4096/global/health
```

## 2. (Optional) Attach the TUI

Open the interactive TUI connected to the running server. CC clients and the TUI share the same session state.

```bash
opencode attach http://127.0.0.1:4096
```

To target a specific session from CC, grab the session ID shown in the TUI and run:

```sh
set opencc.session_id ses_abc123
```

## 3. Configure CC settings

Use the CraftOS shell `set` program at the ComputerCraft console or CraftOS-PC terminal. It persists immediately — no `save` step. The Lua [settings](https://tweaked.cc/module/settings.html) API would also work from a script, but at the shell prompt use `set`.

```sh
set opencc.server_url http://<host-ip>:4096
```

For public production, use port `4242`:

```sh
set opencc.server_url http://<public-host>:4242
```

For example locally:

```sh
set opencc.server_url http://127.0.0.1:4096
```

With auth:

```sh
set opencc.password secret
```

Optional — override the Basic Auth username (default `opencode`):

```sh
set opencc.username myuser
```

Optional — select an opencode agent for requests from this computer:

```sh
set opencc.agent computercraft
```

Optional — scope `ai sessions` to a specific opencode project directory. If omitted, `ai sessions` falls back to the directory recorded on the saved `opencc.session_id` when the unscoped list is empty:

```sh
set opencc.directory /Users/garm/trap/cc-libs
```

Optional but recommended: pick the provider and model. When both are set, `ai` posts to `/session/:id/prompt_async` and polls for completion. Without them, `ai` falls back to blocking `/session/:id/message`, which can use the server default model but is more exposed to HTTP timeouts:

```sh
set opencc.provider_id anthropic
set opencc.model_id claude-opus-4-7
```

Optional timeout settings:

```sh
set opencc.timeout_seconds 60
set opencc.poll_timeout_seconds 300
set opencc.poll_interval_seconds 2
```

`opencc.session_id` is auto-managed and saved by `ai`. Set it manually only when you want CC to target an existing session, such as one opened in the attached TUI.

- **CraftOS-PC (localhost):** `http://127.0.0.1:4096`
- **In-game ATM10 local/dev:** use your LAN IP with port `4096` (e.g. `192.168.x.x:4096`) — add it to `http.rules` in `config/computercraft-server.toml`
- **Public production:** use your public host with port `4242`

## 4. Run `ai`

```
ai ping                    -- ping, reuses existing session
ai "explain what a turtle is"
ai new "start a fresh topic" -- forget current session, start fresh
ai sessions                -- list all server sessions with their IDs
ai --agent computercraft "what peripherals are attached?"
ai --verbose ping          -- show HTTP/session diagnostics
ai --help
ai --version
```

Expected `ai ping` output on a working setup: `pong`.

## 5. CraftOS-PC (no Minecraft)

```bash
just trapos --headless -- /programs/ai.lua ping
```

Set settings inside the harness before running, or inject them via the test API.

## Troubleshooting

| Error | Cause | Fix |
|---|---|---|
| `missing opencc.server_url` | Setting not set | `set opencc.server_url http://...` |
| `serveur injoignable` | Server not running or wrong URL | Start `opencode serve`, check URL/port |
| `erreur message: HTTP 401` | Wrong password | Check `opencc.password` matches `OPENCODE_SERVER_PASSWORD` |
| `missing prompt` | No prompt was passed | Run `ai <prompt>` or `ai ping` |
| `session introuvable; lance: ai new <prompt>` | Session was deleted or server restarted | Run `ai new <prompt>` |
| `erreur message: HTTP 504` | AI took too long | Retry; consider a faster model |
| `delai depasse en attendant la reponse AI` | Async polling timed out | Increase `opencc.poll_timeout_seconds` or check opencode logs |
| `reponse vide` | Reply had no text parts | Check opencode logs |