backnotprop__plannotator/apps/opencode-plugin/devcontainer.md

# Devcontainer / Docker Setup

Plannotator works in devcontainers and Docker environments with minimal configuration.

## Required Environment Variables

Add these to your `devcontainer.json`:

```json
{
  "containerEnv": {
    "PLANNOTATOR_REMOTE": "1",
    "PLANNOTATOR_PORT": "9999"
  },
  "forwardPorts": [9999]
}
```

| Variable | Purpose |
|----------|---------|
| `PLANNOTATOR_REMOTE=1` | Forces remote mode for container-friendly port/browser handling (required in containers) |
| `PLANNOTATOR_PORT=9999` | Fixed port for the UI (required for port forwarding) |

Both are required. Just setting the port isn't enough.

## Port Forwarding

Ensure port 9999 (or your chosen port) is forwarded to your host. In VS Code devcontainers, add it to `forwardPorts` as shown above.

## Usage

1. Run OpenCode in your container (`opencode` or `opencode web`)
2. Ask the agent to create a plan
3. When `submit_plan` is called, Plannotator starts on port 9999
4. Open `http://localhost:9999` in your host browser
5. Approve or deny the plan

**Note:** Browser opening depends on your container/browser setup. If nothing opens automatically, navigate to the forwarded URL manually when you see the agent call `submit_plan`.

## OpenCode Web

`opencode web` works in devcontainers. Forward port 4096 (default) for the OpenCode UI, and port 9999 for Plannotator:

```json
{
  "forwardPorts": [4096, 9999]
}
```

## Legacy Support

If your environment already has `SSH_TTY` or `SSH_CONNECTION` set (common in SSH sessions), Plannotator will detect remote mode automatically when `PLANNOTATOR_REMOTE` is unset. You can also force local mode with `PLANNOTATOR_REMOTE=false` or `0`.

## Troubleshooting

**Plugin not updating?**
```bash
rm -rf ~/.bun/install/cache/@plannotator
```

**OpenCode crashes on startup?**
```bash
rm -rf ~/.cache/opencode ~/.bun/install/cache/@opencode-ai
```

**Port not accessible?**
Check your devcontainer's port forwarding. In VS Code, check the "Ports" tab.