---
title: "The workspace image"
description: "What the workspace image contains, and what it does not contain."
---

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

# The workspace image

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](https://cf-opencode.system3inference.dev/docs/guides/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](https://cf-opencode.system3inference.dev/docs/guides/browsing/). |
| `cf-opencode-browse` | `cf-opencode-browse [--preview <port>]...` | Opens a remote browser session and prints its websocket address. See [Web search and browsing](https://cf-opencode.system3inference.dev/docs/guides/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](https://cf-opencode.system3inference.dev/docs/guides/preview/). |
| `cf-opencode-notify` | `cf-opencode-notify "<text>"` | Sends a note to the notify URL. See [Hand off a task](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#get-a-message-when-a-task-ends). |
| `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](#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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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](https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/#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-minutes` is 1 to 1440. The default is 120.
- A running job counts as use for the idle pause, up to its maximum run time. `maxAwakeHours` still 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`, `status` or `logs -f` gets no message. A stopped job gets no message.
- Each job is a folder in `~/.cf-opencode/jobs/<id>/`: `job.json` and `log`. 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`:

```sh
sudo apt-get update && sudo apt-get install -y build-essential
```

The snapshot keeps installed packages. `rebuild` does not carry packages outside `/home/user`. See [Upgrade and rebuild](https://cf-opencode.system3inference.dev/docs/guides/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 serve` as `user`.
- `opencode serve` listens 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](https://cf-opencode.system3inference.dev/docs/reference/configuration/).

Source: https://cf-opencode.system3inference.dev/docs/reference/image/index.mdx
