OpenCode on a Server: How to Make an AI Agent Work While You Sleep

A familiar story: you launched an AI agent in the terminal, it hung at the most interesting moment, and then you closed your laptop and the whole session vanished. Claude Code and Codex are closed and tailored to their authors' own models. OpenCode, an open-source harness, has no such limits: it works with any provider and, most importantly, it can be housed on a server.

Why This Is Possible at All

Under the hood, OpenCode uses a client-server design. The TUI talks to a local HTTP server that publishes an OpenAPI specification at the /doc endpoint. The opencode serve command starts the same server without the interface. By default it listens on 127.0.0.1:4096, and the address and port can be changed with the --hostname and --port flags. You can call it from CI, from cron or from another script, and you can also keep it warm so you don't pay for the cold start of MCP and LSP.

If the server is reachable from anywhere other than localhost, be sure to set OPENCODE_SERVER_PASSWORD. This enables HTTP basic auth, with the default username opencode. A password alone is not enough: put the server behind nginx or Caddy with HTTPS, otherwise basic auth over plain HTTP only protects against casual scanning.

Where It Comes in Handy

The simplest scenario is CI/CD and pull request review. With the GitHub app, it is enough to mention /opencode or /oc in a comment, and the agent starts in a GitHub Actions runner, reads the context and, if needed, opens a PR with a fix. Without the app, you write a step in the workflow with opencode run --standalone: there is no running TUI in CI, so the command spins up a private server for the task itself. Model output is non-deterministic, so you should not hand the agent scored evaluations, but it is perfectly suited to review.

The second scenario is overnight tasks. The opencode-scheduler plugin uses launchd on macOS and systemd on Linux, with cron as a fallback. A daily dependency audit or a git log report is put on a schedule and forgotten. The third is a shared team server: IDE plugins, a web interface or a Telegram bridge connect to a single process and see the same sessions.

Systemd or Docker

On a clean VPS, a systemd unit running opencode serve is enough. The main trap is PATH. systemd services do not inherit your shell's PATH, so not only OpenCode itself but everything the agent calls through bash goes missing: git, node, rg, make. Set Environment=PATH=... and HOME explicitly.

Docker provides filesystem isolation and repeatability. Pin a specific image version, mount the workspace as a separate volume, and configs and sessions as another. But this is insurance against an accidental rm, not against a deliberate escape.

Permissions, Providers, Security

The provider is connected via @ai-sdk/openai-compatible: any compatible endpoint will do, from local Ollama to a cloud gateway. The example in the article uses BotHub, which sponsors the material. It is better not to store the API key in the config but to add it via opencode auth login. For service tasks such as session titles, set a cheap small_model.

You must not leave the ask rule on a server: opencode serve may wait for hours for an answer that will never come. Use targeted allow rules on top of deny, or the --auto flag, which turns ask into allow but preserves deny.

Most important: SECURITY.md states plainly that OpenCode is not a sandbox and that the permission system is only UX. External MCP servers lie outside the trust boundary, and a recent case of a malicious MCP executing code via OAuth confirmed this. A separate pain point is Bun: it reads HTTP_PROXY unreliably, does not understand socks5://, and without NO_PROXY for localhost the agent can loop on its own requests.

Monitoring and Takeaway

There is a /global/health health check, logs go to journald or Docker, and the opencode-otel plugin sends traces to Jaeger, Grafana Tempo, Datadog or Langfuse. For CI, opencode run --format json is convenient. Watch token consumption: at night the agent works unattended.

The practical takeaway: setting up an agent on a server takes one evening, and the real work begins afterward. Isolation, HTTPS, strict permissions and observability are mandatory. It works best where it is built into a process: overnight audits, PR review. It is better not to give it access to production: let it prepare the PR, and you press the button.