my-opencode-simple/README.md

OpenCode Web

Dockerized OpenCode with OpenChamber as the browser/PWA frontend.

What it does

This project runs OpenChamber in the container and lets OpenChamber start and keep OpenCode available in the background.

The stack inside the container:

• OpenCode CLI — the AI coding assistant
• OpenChamber — web frontend that starts and presents OpenCode
• Node 26 — runtime
• Graphifyy — knowledge-graph skill for codebase understanding (installed via pipx)

OpenCode configuration

The opencode-config/ directory contains a full custom OpenCode agent setup, mounted at /home/node/.config/opencode inside the container.

Agents

File	Mode	Purpose
agents/build.md	primary	Default agent with full permission set for implementation work
agents/explore.md	subagent	Specialized codebase file/content search
agents/general.md	subagent	General-purpose multi-step research and execution
agents/plan.md	primary	Plan mode — architecture design and implementation plans (read-only)
agent/executor.md	subagent	Runs shell commands only, no editing or file-reading

Commands

File	Description
command/commit.md	Create git commits with auto-generated conventional commit messages
command/rapid.md	Fast iteration mode — quick fixes without extensive planning
commands/plan.md	Creates detailed implementation plans
commands/review.md	Reviews code changes (commit, branch, PR, or uncommitted)

Plugins

File	Description
plugin/fail-fast.ts	Converts denied permissions and missing shell utilities into explicit task failures so agents don't stall or retry blocked actions

Snippets

File	Aliases	Description
snippet/commit-message.md	cm	Generates a commit message from current changes
snippet/create-plan.md	plan	Creates an implementation plan from the current session

Permissions

Fine-grained tool permissions are defined in opencode.jsonc (auto-generated, gitignored). Each agent has a tailored permission set — for example, explore has broad read/search access with bash allowed, while build has write/edit access but denies bash for safety.

Fail-fast plugin

The fail-fast plugin (plugin/fail-fast.ts) hooks into OpenCode's tool lifecycle to catch three conditions:

1. Permission denied — if a permission.ask results in deny, the plugin throws a FAIL_FAST_PERMISSION_DENIED error with the permission name and next-action guidance.
2. Invalid command — if bash is called without a command, it throws FAIL_FAST_INVALID_COMMAND.
3. Missing utility — after every bash execution, the plugin checks stderr/stdout for "command not found", "not found", "ENOENT" patterns. If found, it throws FAIL_FAST_MISSING_UTILITY with the utility name.

This prevents agents from silently retrying blocked operations or looping on missing dependencies.

How to run

docker compose up -d

Open http://localhost:5200 in your browser.

To run OpenChamber on a different port, set OPENCHAMBER_PORT in .env and restart the container:

OPENCHAMBER_PORT=5300

The container uses host networking, so OpenChamber binds directly to OPENCHAMBER_PORT; there is no separate Docker port mapping to update.

To protect the UI, set UI_PASSWORD in .env.

User and group IDs can be set in .env to match the host user:

UID=1000
GID=1000

How to update

Rebuild the image to pull the latest versions of OpenCode and OpenChamber:

docker compose build --no-cache
docker compose up -d

Managing repositories

Set REPOSITORIES_PATH in .env to the host directory that contains repositories OpenCode should work on:

REPOSITORIES_PATH=./repositories

The directory is mounted at /home/repositories inside the container.

Container details

Aspect	Detail
Network	host mode — no port mapping needed
Docker access	/var/run/docker.sock mounted for in-container Docker usage
Container user	Runs as ${UID}:${GID} (default 1000:1000)
OpenChamber	Configured to allow unauthenticated LAN access (OPENCHAMBER_ALLOW_UNAUTHENTICATED_LAN=true)

Persisted data (gitignored)

Local path	Container mount point	Purpose
.config/opencode-data/	/home/node/.local/share/opencode	Agent state and tool outputs
.config/opencode-state/	/home/node/.local/state/opencode	Session and runtime state
.config/opencode-cache/	/home/node/.cache/opencode	Model cache and temporary data
.config/openchamber-config/	/home/node/.config/openchamber	OpenChamber configuration and session data

Browser and PWA notifications

OpenChamber can send browser notifications for prompt completion, questions, errors, and subtasks.

To receive notifications, open OpenChamber in your browser or installed PWA and allow notifications for the site/app when prompted. If notifications were previously blocked, reset the site notification permission in your browser settings.