Devcontainer / Docker Setup

Plannotator works in devcontainers and Docker environments with minimal configuration.

Required Environment Variables

Add these to your devcontainer.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:

{
  "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?

rm -rf ~/.bun/install/cache/@plannotator

OpenCode crashes on startup?

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.