# opencode server guide

How to run `opencode serve` and test `ai-helloworld` from ComputerCraft directly — no proxy.

See `docs/opencode_api.md` for the full API reference.

## Architecture

```
CC Turtle
  └─ ai-helloworld.lua  (libaihelloworld.lua)
       └─ POST /session/:id/message  →  opencode serve
```

## 0. Install TrapOS and the AI package

On a fresh CC computer (beta branch):

```
wget run https://raw.githubusercontent.com/guillaumearm/cc-libs/next/install-ccpm.lua --beta
ccpm update
ccpm install trapos
ccpm install tos-ai
```

## 1. Start `opencode serve`

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

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
```

## 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:
```
settings set opencc.session_id ses_abc123
```

## 3. Configure CC settings

Run in the ComputerCraft console or CraftOS-PC terminal:

```lua
settings set opencc.server_url http://<host-ip>:4096
settings save
```

With auth:
```lua
settings set opencc.password secret
settings save
```

Optional — override the Basic Auth username (default `opencode`):
```lua
settings set opencc.username myuser
settings save
```

- **CraftOS-PC (localhost):** `http://127.0.0.1:4096`
- **In-game ATM10:** use your LAN IP (e.g. `192.168.x.x`) — add it to `http.rules` in `config/computercraft-server.toml`

## 4. Run `ai-helloworld`

```
ai-helloworld              -- ping, reuses existing session
ai-helloworld --new        -- forget current session, start fresh
ai-helloworld --sessions   -- list all server sessions with their IDs
ai-helloworld --help
ai-helloworld --version
```

Expected output on a working setup: `pong` (default prompt is `reply with exactly: pong`).

## 5. CraftOS-PC (no Minecraft)

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

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 | `settings 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` |
| `session introuvable; lance: ai-helloworld --new` | Session was deleted or server restarted | Run `ai-helloworld --new` |
| `erreur message: HTTP 504` | AI took too long | Retry; consider a faster model |
| `reponse vide` | Reply had no text parts | Check opencode logs |