133 lines
5.2 KiB
Markdown
133 lines
5.2 KiB
Markdown
# OpenCode Web
|
|
|
|
Dockerized [OpenCode](https://opencode.ai) with [OpenChamber](https://github.com/openchamber/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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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:
|
|
|
|
```env
|
|
UID=1000
|
|
GID=1000
|
|
```
|
|
|
|
## How to update
|
|
|
|
Rebuild the image to pull the latest versions of OpenCode and OpenChamber:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```env
|
|
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.
|