---
title: "Security and trust"
description: "The control token, the workspace password, why secrets never enter a workspace, egress interception and lockdown."
---

> Documentation Index
> Fetch the complete documentation index at: https://cf-opencode-site.mdick85.workers.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Security and trust

The Worker URL is on the internet. Two secrets protect it.

## Control token

The control token protects the control API at `/v1`. `init` makes it and stores it in two places:

- `~/.cf-opencode/control-token`, mode 600.
- The Worker secret `CONTROL_TOKEN`.

The CLI sends it as a bearer token. It never travels as a command argument. A rerun of `init` keeps it. `init --adopt` replaces the control token of an existing Worker.

Anyone with the control token can manage every workspace and derive every workspace password. Treat it like a password.

## Workspace password

Each workspace has its own password. It protects `/oc/<workspace>`, `/shell/<workspace>`, `/ssh/<workspace>`, `/browse/<workspace>` and `/preview/<workspace>`.

The CLI derives the password from the control token and the workspace ID with HMAC-SHA256. Because it is derived, every machine with the control token gets the same password. The Worker can compute it too. Nobody stores it on the Worker.

The CLI writes it to `~/.cf-opencode/workspaces/<workspace>.password`, mode 600. OpenCode reads it from `OPENCODE_SERVER_PASSWORD`. The username is always `opencode`. The password is not in any URL. The CLI never prints it.

A visitor to the Worker URL without the control token gets one bare `401` with the body `{"error":"Unauthorized"}` for every path. It names no product, secret or route.

The Worker checks the password first, in constant time. Because the password is derived, this check needs no state. No password or a wrong one gets the same 401, reaches no Durable Object, and does not say whether the workspace exists. Then the workspace's Durable Object checks the password again before it wakes anything. A wrong password wakes nothing.

There is no lockout. The password is 256 bits, so nobody can guess it, and a lockout on a workspace name would let anyone lock you out.

`/shell`, `/ssh` and `/browse` refuse a request that a web page sends, from another site or from the Worker's own origin (a preview page is on that origin). The CLI, `ssh` and CDP clients still work. A browser session is served only to the workspace that opened it.

## Previews

A preview shows a dev server that the agent runs. Treat its pages as code you did not write.

- `cf-opencode preview` forwards the port over SSH to `localhost` on your machine. Nothing is public.
- `--web` serves the port at `/preview/<workspace>/<port>/` on the Worker. A browser signs in with a one-time link (2 minutes) and gets a cookie for that workspace and port only (8 hours). The cookie and the link are HMACs under a key derived from the control token. The Worker checks them, and the workspace password, before it calls any Durable Object, so a request without one costs one Worker request.
- `--public` makes `/public/<workspace>/<token>/`. Only the control token makes or removes one, so the agent cannot. The token carries its own HMAC, so the Worker refuses a forged token before it calls a Durable Object.
- Every preview is on the Worker's origin. A page in one preview can read another preview that the same browser is signed in to. It cannot open `/shell`, `/ssh` or `/browse`. It can call `/oc` only if your browser has a workspace password cached for the Worker, which happens only when you type one into a browser prompt. Do not do that, and open a preview of code you do not trust in a separate browser profile.
- The Worker drops `Service-Worker-Allowed` and `Clear-Site-Data` from preview responses, so a preview cannot put a service worker over the whole origin or sign the browser out of other previews.

## Handed-off tasks, MCP and A2A

- Task text goes to the workspace in the environment of a script, never in a command line.
- Branch names, commit subjects, file names, titles and summaries come from the workspace. The agent can write anything there. The Worker cuts each to a fixed size. The CLI replaces terminal control characters in them with `?` before it prints them.
- `cf-opencode mcp` runs the task tools for the agent on your machine. A prompt-injected agent can call them like you: it can start a task in any workspace of this machine, and `directory` can name any git checkout on the machine, where the CLI then runs `git`. `git` reads that checkout's `.git/config`, which can run commands. Use the MCP server only with an agent that you would let run `cf-opencode run`.
- The A2A endpoint is off by default (`a2a`). When it is on, `/a2a` needs the control token, and the Agent Card is public. The card names no workspace, repository or user. A blocking `SendMessage` waits 5 minutes at most.

## Notify URL

`cf-opencode notify-url` stores the URL as the Worker secret `NOTIFY_URL`, because a webhook URL often holds its own secret. `/v1/status` and `doctor` say only whether it is set. It must be `https`, with no user or password, to a public host name. The Worker does not follow a redirect from it.

Each `POST` carries `x-cf-opencode-timestamp` (Unix seconds) and `x-cf-opencode-signature: sha256=<HMAC of "<timestamp>.<body>">`, with the key from `cf-opencode notify-key`. The time is signed with the body. A receiver must refuse a timestamp more than 5 minutes old, so a copy of a delivery cannot be sent again later. A workspace can send at most 20 notes in one hour; the count is kept outside the workspace.

The agent can send any text to the URL with `cf-opencode-notify`, up to 20 notes an hour. Treat a note as text from the agent, not from you.

## The agent account

The agent runs as `user`, which has passwordless `sudo`. A prompt-injected agent is root in its container. It can change anything on the disk, and its changes are in the next snapshot. The agent also has the workspace password, in `OPENCODE_SERVER_PASSWORD`.

This is on purpose, so the agent can install what a project needs. A rule such as "sudo for `apt-get` only" would not be a boundary: package scripts run as root.

These things protect you:

- No key, token or notify URL enters the workspace. See the next section.
- The GitHub token reaches only the repositories you give it.
- `lockdown` turns general internet off.
- A workspace is disposable. `cf-opencode delete` drops its disk, and the next `connect` clones again.

Review what the agent pushes, and do not put secrets on the workspace disk.

## Secrets never enter the container

A provider key or the GitHub token is a Worker secret. The workspace holds only a placeholder, `cf-opencode-egress`.

The platform intercepts requests from the container to these hosts. The Worker removes the container's own credential headers and adds the real credential:

| Host | Worker secret |
| --- | --- |
| `api.anthropic.com` | `ANTHROPIC_API_KEY` |
| `api.openai.com` | `OPENAI_API_KEY` |
| `github.com` | `GITHUB_TOKEN` |
| `api.github.com` | `GITHUB_TOKEN` |

A route whose secret is not set is refused. The Worker does not forward the placeholder. The Worker does not follow a redirect with the real credential on it: the redirect goes back to the container.

The disk, the environment and every snapshot hold only the placeholder. A snapshot cannot leak a key.

The GitHub token is added to every request from the workspace to `github.com` and `api.github.com`. Its reach is the reach of the workspace. Give it only the repositories you need. See [GitHub and private repositories](https://cf-opencode-site.mdick85.workers.dev/docs/guides/github/).

## Internet access

A workspace has general internet access, so it can clone repositories and install packages. Provider hosts stay intercepted. This internet access does not let a key leak, because no key is in the container.

## Lockdown

Set `lockdown` to `true` in `~/.cf-opencode/config.json`, then run `cf-opencode upgrade`, to turn general internet off. Only provider hosts whose secret is set stay reachable. `lockdown` is `false` by default. See [Configuration](https://cf-opencode-site.mdick85.workers.dev/docs/reference/configuration/).

Interception of provider hosts is on either way. You cannot configure it.

With lockdown on, `cf-opencode-fetch` is refused: it loads any URL through the Worker's Browser Run binding, which is general internet. Models, `cf-opencode-search` and `cf-opencode-notify` still work. A search query leaves the account for the search provider, and a note goes to your notify URL, so a workspace can still put data in them.

## What a workspace can spend

Models, `cf-opencode-search`, `cf-opencode-fetch` and `cf-opencode-browse` need no credential in the workspace, so the agent can use them as much as it wants. They bill to your account: Workers AI, AI Gateway credits and Browser Run hours. cf-opencode sets no budget for each workspace. Use the AI Gateway's rate limits and the credit balance to cap it.

## Logs

The container redacts `opencode serve` logs before they leave it. `cf-opencode logs` shows the redacted log.

## What you must protect

- `~/.cf-opencode/control-token` and `~/.cf-opencode/workspaces/*.password`.
- Your Cloudflare API token, if you use one. It comes from `CLOUDFLARE_API_TOKEN` or `--token-file`, never from an argument.
- The workspace disk. It holds your code, and it is in every snapshot.

Source: https://cf-opencode-site.mdick85.workers.dev/docs/concepts/security/index.mdx
