opencode server guide

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

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

opencode serve --hostname 0.0.0.0 --port 4096

With Basic Auth (recommended for LAN exposure):

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:

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.

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:

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 API would also work from a script, but at the shell prompt use set.

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

With auth:

set opencc.password secret

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

set opencc.username myuser

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)

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

3.1 KiB Raw Blame History