# In-Game TrapOS, AI, MCP Guide

Follow this order while playing.

## 1. Install TrapOS

On the ComputerCraft computer:

```sh
wget run https://os.trapcloud.fr/install
```

If the computer asks to reboot, reboot it.

## 2. Start OpenCode On Host

On your real machine:

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

If exposing beyond your machine, use a password:

```sh
OPENCODE_SERVER_PASSWORD=secret opencode serve --hostname 0.0.0.0 --port 4242
```

## 3. Connect `ai.lua`

On the ComputerCraft computer, use your public host:

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

If you set a password:

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

Optional model settings:

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

Optional agent setting for the in-game ComputerCraft assistant:

```sh
set opencc.agent atm10-expert
```

Test it:

```sh
ai ping
ai "say hello from TrapOS"
```

Expected ping: `pong`.

## 4. Start The Cloud Gateway On Host

The MCP tools now ride on the `trapos-server` gateway (the same WS connection used for
cloud health). From this repository on your real machine:

```sh
just serve
```

This serves two listeners:

```text
Gateway (in-game computers connect here): ws://<public-host>:4444/gateway
MCP endpoint (OpenCode connects here):    http://127.0.0.1:4445
```

The MCP endpoint stays bound to `127.0.0.1` on purpose: `exec-lua` / `write-file` are
as powerful as the linked computer, so only local processes (your OpenCode) reach them.
`TRAPOS_SERVER_PASSWORD` (and `OPENCODE_SERVER_PASSWORD`) must be set in `.env`: the
gateway connection requires this shared secret, and the server refuses to start if either
is empty (run `just install` to generate them). An empty password would expose the gateway
unauthenticated, so it is never allowed.

## 5. Link The Computer To The Gateway

On the ComputerCraft computer, point it at the gateway and reboot:

```sh
set cloud.url ws://<public-host>:4444
set cloud.password secret   # must match TRAPOS_SERVER_PASSWORD on the host
reboot
```

The `daemons/cloud` daemon connects automatically at boot, and `daemons/mcp-computer-server`
starts serving `exec-lua` / `write-file` over that one connection. Check the link with:

```sh
cloud health
```

## 6. Connect OpenCode To MCP

Add the gateway's MCP endpoint as an MCP HTTP server in your OpenCode MCP config:

```text
http://127.0.0.1:4445
```

Then ask OpenCode to use the MCP tool `probe-computers`. It lists each connected
computer's `traposId` (the `"<id>:<label>"` string), for example `ok from 7:base`.

`exec-lua` and `write-file` address a computer by that `traposId`. `exec-lua` runs Lua
on the target and returns captured output to OpenCode:

```lua
print('captured in MCP output')
```

To write to the visible ComputerCraft screen, use terminal APIs directly:

```lua
term.clear()
term.setCursorPos(1, 1)
term.write('visible on screen')
```

`exec-lua` is powerful and unsafe by design: it can do anything the linked computer can
do, including file, peripheral, turtle, and reboot operations. The trust boundary is the
authenticated gateway connection (`cloud.url` + `TRAPOS_SERVER_PASSWORD`) plus the local-only
MCP bind — only connect a computer to a gateway you control.

`write-file` writes content to a path on the target computer and overwrites any existing
file. It follows normal ComputerCraft filesystem behavior, so missing parent directories
fail instead of being created automatically.

## Quick Fixes

- `ai` says missing `opencc.server_url`: run the `set opencc.server_url ...` command again.
- `ai` cannot reach server: check `opencode serve`, public host, port `4242`, and ComputerCraft HTTP rules.
- `cloud health` fails: enable ComputerCraft HTTP/WebSocket support and check `cloud.url` (port `4444`).
- MCP sees no computers: confirm `cloud.url` is set and the computer was rebooted so `daemons/cloud` is running.
- `exec-lua` / `write-file` return `unknown_type`: that computer is not running `daemons/mcp-computer-server` (set `cloud.url` and reboot).
- `exec-lua` or `write-file` is missing after updating: restart OpenCode so it reloads the MCP tool list.

More detail: [`opencode_server_guide.md`](opencode_server_guide.md), [`public-ports.md`](public-ports.md).