The workspace image is small on purpose. It is Debian bookworm-slim with a few tools. The base image digest, the tini version, the OpenCode version, Node and mise are pinned. A snapshot restores only onto the image it came from.
Installed
| Item | Notes |
|---|---|
| OpenCode 2.2.7 | The linux x64 release asset that the official installer downloads, checked against a pinned SHA-256. A different file fails the build. opencode on the PATH adds the model config, then runs the real binary. |
git |
|
gh |
The GitHub CLI. It reads GH_TOKEN, which holds a placeholder. |
| Node 22 | node, npm, npx and corepack, from the nodejs.org release, checked against a pinned SHA-256. |
mise |
For a project that pins another version of Node or another tool. It installs nothing by itself: run mise trust && mise install in the project. It reads mise.toml, .tool-versions, .nvmrc and .node-version. Its shims are first on the PATH, so the pinned version is the one that runs. |
python3 |
With the websocket module, for the Chrome DevTools Protocol of a browser session. The module sends the Worker’s own origin, which the Worker needs. |
curl |
|
ripgrep |
The command rg. |
jq |
|
unzip |
|
less |
|
tmux |
cf-opencode shell uses it. |
openssh-server |
sshd runs per connection with sshd -i. It never listens. |
sudo |
user has passwordless sudo. |
tini |
PID 1. |
bash, procps, ca-certificates, libnss-myhostname |
Base tools. |
Commands for the agent
The image has these commands. The agent uses them. You can run them in cf-opencode shell too.
| Command | Usage | What it does |
|---|---|---|
cf-opencode-search |
cf-opencode-search [-n 1..10] [--provider exa|linkup|ceramic] [--json] <query> |
Searches the web. See Web search and browsing. |
cf-opencode-fetch |
cf-opencode-fetch [--links|--html|--screenshot <file>|--pdf <file>] [--max-chars <n>] <url> |
Reads a page through a real browser. It also reads a dev server of this workspace. See Web search and browsing. |
cf-opencode-browse |
cf-opencode-browse [--preview <port>]... |
Opens a remote browser session and prints its websocket address. See Web search and browsing. |
cf-opencode-preview |
cf-opencode-preview <port> |
Prints the preview URL of a dev server, and checks that the port listens on 0.0.0.0. See Preview a dev server. |
cf-opencode-notify |
cf-opencode-notify "<text>" |
Sends a note to the notify URL. See Hand off a task. |
cf-opencode-job |
cf-opencode-job start [--name <name>] [--max-minutes <n>] -- <command...> |
Runs a long command apart from the agent’s turn. See Long jobs. |
cf-opencode-store |
cf-opencode-store put <file> [name], get [-f] <name> [path], list [prefix], rm <name> |
Saves and reads files in the store, when store is on. A file that the agent saves is named <workspace>/<name>. See Share files through the store. |
opencode on the PATH is a small wrapper. It adds the model config, then runs the real OpenCode binary.
Long jobs
cf-opencode-job runs a command apart from the agent’s turn, so the agent can end its turn. See Long jobs for how a task uses it.
| Command | What it does |
|---|---|
start [--name <name>] [--max-minutes <n>] [--json] -- <command...> |
Starts the job and returns at once. It prints the job ID and the log path. The default name is the program name and its first plain argument. |
list [--json] |
Lists the jobs, newest first, with their state. |
status <id> [--json] |
Shows one job: state, exit code, command, log path, and the message to the session. |
logs <id> [-f] [-n <lines>] |
Prints the end of the log (100 lines). -f follows the log until the job ends. |
wait <id> [--timeout <seconds>] |
Waits until the job ends, and exits with the job’s exit code. The default timeout is 300 seconds. A timeout exits with 124. Keep the timeout under the time limit of your tool call. |
stop <id> |
Stops the job: SIGTERM to its process group, then SIGKILL after 10 seconds. |
A job has one of these states: running, done (exit code 0), failed, timeout (it reached --max-minutes) and stopped (by stop, or by a pause).
--max-minutesis 1 to 1440. The default is 120.- A running job counts as use for the idle pause, up to its maximum run time.
maxAwakeHoursstill pauses the workspace. - When the job’s command ends, what is left in its process group ends too.
- OpenCode gives the job the session ID of the agent that started it. When OpenCode gives none and one session is active, the job is tied to that session. When the job ends, that session gets one message with the exit code and the end of the log. The message waits until the session is idle. A job that the agent watched to its end with
wait,statusorlogs -fgets no message. A stopped job gets no message. - Each job is a folder in
~/.cf-opencode/jobs/<id>/:job.jsonandlog. The 50 newest jobs that ended are kept. - A job that was running when the workspace paused shows
stopped (the workspace paused or stopped)after the next wake. - A failure is one line:
Failed: <cause> — fix: <action>.
Not installed
The image has no compilers. It has no language toolchain other than Node and Python 3. mise can install one in the home folder, for example mise use python@3.13.
Ask the agent to install what the project needs. The user account has passwordless sudo:
sudo apt-get update && sudo apt-get install -y build-essentialThe snapshot keeps installed packages. rebuild does not carry packages outside /home/user. See Upgrade and rebuild.
Users and paths
user(uid 1000) runs OpenCode, the shell and the SSH login.- The home folder is
/home/user. The default project path is/home/user/project. - The container starts as root. The entrypoint trusts the egress CA, then the Worker starts
opencode serveasuser. opencode servelistens on port 4096.
Size
The default container has 2 vCPU, 6 GiB of memory and a 20 GB disk. You can change it with instance. See Configuration.