opencode-manager: a mobile-first web console for OpenCode agents

Who opencode-manager is actually for

OpenCode runs as a terminal tool. That is fine until the machine running it is not the machine you are holding. OpenCode Manager exists for that gap: it is a web interface for OpenCode agents, built mobile-first, so a session started on a desktop can be checked, prompted and stopped from a phone or tablet. The README frames it as managing and controlling multiple agents from any device, and the feature list backs that up with a responsive PWA, push notifications and a directory browser.

The second audience is teams. The repository describes a single shared OpenCode server, and the ocm CLI attaches a local OpenCode TUI to a repo hosted on the Manager through the /api/opencode-proxy endpoint. In that model the prompts run on the Manager's filesystem, not on the laptop. That is a meaningful architectural decision: it makes the server the source of truth for code and agent state, and it makes the client thin.

If you are a solo developer who never leaves the terminal, this project adds a server, a SQLite database, an auth layer and a container runtime to solve a problem you do not have.

Architecture: three packages, one shared OpenCode process

The repository is a pnpm workspace with three TypeScript packages. backend/ is a Bun and Hono API server handling Better Auth, SQLite migrations, OpenCode process management, SSE streaming, schedules and push notifications. frontend/ is a React and Vite SPA using React Router, TanStack Query, Radix UI and Tailwind, with service worker support for the PWA. shared/ holds Zod schemas, config helpers and types consumed by both sides. A MkDocs Material site under docs/ carries the guides.

The data flow matters more than the package list. The Manager spawns and supervises an OpenCode server as a child process, configured through OPENCODE_SERVER_PORT (5551 in docker-compose.yml) and OPENCODE_HOST (127.0.0.1 by default). The browser talks to the Manager backend, which talks to that managed OpenCode process; chat responses reach the UI over SSE rather than polling. The .env.example documents a guard worth noting: the managed OpenCode server refuses to start if OPENCODE_HOST is not localhost or 127.0.0.1 and no password is configured, either through OPENCODE_SERVER_PASSWORD or through Settings, OpenCode, Server Auth. Passwords stored in the database override the environment variable.

State lives in SQLite at DATABASE_PATH, mapped to /app/data/opencode.db in the compose file, while the code lives under WORKSPACE_PATH, mounted as /workspace. The compose file publishes 5003 for the app and 5100 through 5103 alongside it, and sets MAX_FILE_SIZE_MB and MAX_UPLOAD_SIZE_MB to 50.

Installing opencode-manager with Docker and creating the first admin

The README gives a five-line quick start. Clone the repository, copy the environment template, generate an auth secret, start Compose, and open the app on port 5003. The AUTH_SECRET line is required for production; the README shows openssl rand -base64 32 as the generator.

git clone https://github.com/chriswritescode-dev/opencode-manager.git
cd opencode-manager
cp .env.example .env
echo "AUTH_SECRET=$(openssl rand -base64 32)" >> .env
docker-compose up -d

After the container is up, the README says to open http://localhost:5003. On first launch you are prompted to create an admin account. If you would rather pre-seed the account, the configuration section lists ADMIN_EMAIL and ADMIN_PASSWORD as optional variables, and docker-compose.yml passes both through, along with ADMIN_PASSWORD_RESET defaulting to false.

The workspace volume is the part most people get wrong. By default Compose uses a named volume called opencode-workspace, so your repositories live inside Docker and are awkward to reach from the host. The .env.example documents OCM_WORKSPACE_HOST_PATH for binding /workspace to a host directory instead, and recommends setting PUID and PGID to the output of id -u and id -g so files stay usable from the host without root. That is the setup to choose if you intend to edit the same files outside the container.

For LAN or remote access the README shows AUTH_TRUSTED_ORIGINS taking a comma-separated list, with AUTH_SECURE_COOKIES set to true when you are behind HTTPS. Authentication is not optional here: the app ships Better Auth with OAuth providers for GitHub, Google and Discord, plus passkeys configured through PASSKEY_RP_ID, PASSKEY_RP_NAME and PASSKEY_ORIGIN.

The ocm CLI and the push/pull model

The ocm CLI ships from ocm-cli/ and is the piece that makes the shared-server design usable from a terminal. It lists ready repositories, attaches your local OpenCode TUI to one of them, and routes prompts through the Manager's /api/opencode-proxy so they execute on the Manager's filesystem against a single OpenCode server. Running ocm inside a local clone auto-detects the matching Manager repository by its origin URL.

ocm push and ocm pull move the working tree in either direction. The README states the default is a fast git bundle plus a working-tree patch, with --full selecting the legacy tarball mirror. The word legacy is doing real work in that sentence: the bundle path is the one the project now prefers, and the tarball mode is kept for compatibility. If you are scripting sync in CI, pin the behaviour you want rather than relying on the default, because the default has already changed once.

The trade-off is inherent to the design. Because prompts run server-side, your local editor and the agent are not looking at the same filesystem until you push. A long agent session that writes files on the Manager is invisible to your local tooling until you pull. That is a coherent model for a shared workspace and an annoying one for tight local iteration.

Limitations and failure modes

The most obvious limitation is that this is not OpenCode. It is a Manager wrapped around it. The Dockerfile pins OPENCODE_VERSION to 1.18.16, so the OpenCode you get is the one baked into the image. Upgrading OpenCode means rebuilding the image or waiting for a release that bumps that argument, not running a package manager command. The same applies to UV_VERSION and MICROSANDBOX_VERSION, which are also build arguments.

Resource limits are fixed in the compose environment: MAX_FILE_SIZE_MB and MAX_UPLOAD_SIZE_MB both default to 50. Large binaries and big ZIP downloads will hit that ceiling, and the README does not document a way to raise it short of editing the compose file.

The authentication configuration is easy to get subtly wrong. AUTH_SECURE_COOKIES defaults to false, which is correct for plain HTTP on localhost and wrong the moment you terminate TLS in front of the container. PASSKEY_ORIGIN defaults to http://localhost:5003, so passkeys registered against that origin will not work from a different hostname. And the OpenCode server guard means that if you set OPENCODE_HOST to 0.0.0.0 without a password, the managed process will not start at all. That is a good failure, but it is a failure, and the README does not document rollback or recovery for a half-configured deployment.

Finally, the repository does not describe a multi-tenant isolation model. The architecture is one shared OpenCode server per Manager instance. If you need each user's agent to be unable to read another user's repository, this is the wrong tool, and the documentation is silent on whether such isolation is planned.

How it compares to running OpenCode in a terminal

The honest alternative is OpenCode itself in a terminal, optionally over SSH or in tmux. That approach has no web server, no SQLite database, no auth provider and no container. It also has no phone interface, no push notifications, no schedule runner and no browser-based diff viewer.

The difference in approach is where the agent process lives. Terminal OpenCode runs on the machine in front of you, against the filesystem in front of you. OpenCode Manager runs the agent in a container against a mounted workspace and treats the browser or the ocm CLI as a client. Everything the Manager adds, Git integration, file management, MCP server configuration, skills, schedules, text-to-speech and speech-to-text, follows from centralising that process.

So the comparison is not really about features. It is about whether you want the agent's filesystem to be the server's filesystem. If yes, the Manager's Git integration, unified diffs and worktrees are genuinely useful. If no, the ocm push and pull cycle is overhead you are paying for a UI you may not need.

Maintenance, upgrades and licence

The repository is not archived, and the last push was on 2026-09-09, which is recent. Releases are frequent: v0.17.1 on 2026-08-27, v0.17.2 on 2026-08-29, and v0.17.5 on 2026-09-09, the same day as the last push. The package.json version matches at 0.17.5, and the project uses pnpm 10.28.1 as its package manager.

Upgrade cost has two layers. The application layer is a container rebuild: pull the new source and run docker-compose up -d again, since the compose file builds from the local Dockerfile rather than pulling a published image. The OpenCode layer is separate and pinned in the Dockerfile, so a new OpenCode release does not reach you until the project bumps OPENCODE_VERSION or you edit the build argument yourself.

The licence is MIT, which is permissive and places few obligations on how you deploy or modify the code. MIT does not grant trademark rights, and it does not cover the third-party services the app integrates with, such as OAuth providers, push notification services or any OpenAI-compatible audio API you configure. Those carry their own terms. This is a description of the licence text, not legal advice.

Editorial conclusion

Adopt opencode-manager if you want an OpenCode agent reachable from a phone or tablet, or if several people need to share one OpenCode workspace through a browser. Skip it if you only ever work in a terminal on one machine, since the Docker deployment adds a server, a database and an auth layer on top of a tool that already runs locally. Before committing, verify three things: that the managed OpenCode server starts with your chosen OPENCODE_HOST setting, that AUTH_TRUSTED_ORIGINS matches the exact origin you will browse from, and that PUID and PGID map to your host user so files written into /workspace stay usable outside the container.

Frequently asked questions

Official sources

1. chriswritescode-dev/opencode-manager on GitHub
2. License: MIT
3. Project website
4. README
5. Releases