cc-libs/docs/opencode_server_guide.md

opencode server guide

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

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

opencode serve --hostname 0.0.0.0 --port 4096

Public production uses port 4242; see public-ports.md:

opencode serve --hostname 0.0.0.0 --port 4242

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

With Basic Auth:

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.

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

For public production, use port 4242:

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

For example locally:

set opencc.server_url http://127.0.0.1:4096

With auth:

set opencc.password secret

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

set opencc.username myuser

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

set opencc.agent atm10-expert

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:

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:

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

Optional timeout settings:

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 atm10-expert "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)

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