175 lines
4.9 KiB
Markdown
175 lines
4.9 KiB
Markdown
# 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 |
|