---
title: "Hand off a task"
description: "Give a task to OpenCode in a workspace with cf-opencode run, close the laptop, and read the result with cf-opencode tasks."
---

> 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.

# Hand off a task

`cf-opencode run` gives a task to OpenCode in a workspace and returns at once. The task runs in the workspace, not on your laptop. You can close the laptop. The result comes back as a pushed branch, and as a pull request when `gh` works.

A local agent, such as Claude Code or OpenCode, can use the same commands from its shell tool. The [handoff skill](#the-handoff-skill-for-agents) tells it how.

## Before you start

1. Connect the checkout once: `cf-opencode connect`. See the [quick start](https://cf-opencode.system3inference.dev/docs/quickstart/).
2. Set up GitHub, so the agent can push. See [GitHub](https://cf-opencode.system3inference.dev/docs/guides/github/).
3. Commit your changes and push the branch. The workspace clones from the Git remote. It does not see local files.

## Start a task

From the git checkout:

```sh
cf-opencode run "Add a health check route at /health with a test" --title "Health check"
```

The output gives the session ID and the next commands:

```text
Started ses_4f2a… in my-app: Health check
Status: cf-opencode tasks ses_4f2a… --workspace my-app
Wait:   cf-opencode tasks ses_4f2a… --workspace my-app --wait
Follow: cf-opencode tasks ses_4f2a… --workspace my-app --follow
Open:   cf-opencode connect my-app --session ses_4f2a…
```

`run` does these steps:

1. It checks the checkout, or with `--branch` that `origin` has the branch. See [The preflight](#the-preflight).
2. It wakes the workspace, as `cf-opencode connect --no-attach` does.
3. It records the commit that the workspace checkout is on (`HEAD`). Commits after it are the task's.
4. It starts a new OpenCode session in the workspace, with your task as the first message.
5. It prints the session ID and returns. It does not wait.

The session runs in `opencode serve` in the workspace. The workspace stays awake while the agent works. It pauses `idlePauseMinutes` after the agent stops. See [Idle pause](https://cf-opencode.system3inference.dev/docs/concepts/how-it-works/#idle-pause).

## Start from another branch

By default the task starts from the branch of your checkout, as it is on `origin`. `--branch <name>` starts it from another branch on `origin`:

```sh
cf-opencode run "Fix the flaky date test" --branch release/2.4
```

With `--branch`, the [preflight](#the-preflight) asks `origin` for the branch (`git ls-remote`). The state of your checkout does not matter then: changes that are not committed and a branch that is not pushed do not stop the task. When `origin` does not answer, the branch from your last `git fetch` decides.

## Run two tasks at once

One task at a time uses the checkout of a workspace. Two agents in one checkout change the same files. When a task in the checkout is `running` or `waiting`, a second `run` fails before it starts a session:

```text
Failed: task ses_4f2a… is running in the checkout of workspace my-app; two tasks in one checkout change the same files — fix: pass --new (a new workspace) or --worktree (a new git worktree in this workspace)
```

A `waiting` task counts, because its work is in the checkout and goes on after your answer. The fix then also gives the `--reply` command. A `stopped`, `done` or `failed` task does not count. The Worker does the check, in one queue for each workspace, so two `run` commands at the same time cannot both start.

Give the second task its own checkout:

- `--worktree` starts the task in a new git worktree in the same workspace, in `/home/user/worktrees`. The worktree starts at the branch on `origin` with a detached HEAD, and the agent makes a new branch for its work. The task's branch, commits, `unpushed` and `processes` are read in its worktree. The workspace checkout does not change. The worktree stays on the disk after the task. Remove it in the workspace with `git worktree remove <path>`.
- `--new` starts the task in a new workspace, named `<checkout>-<short id>`, for example `my-app-3f9a1c`. It clones the branch from `origin`. It pauses when idle, like any other workspace, and it does not delete itself. Remove it with `cf-opencode delete <workspace>`.

`--new` and `--worktree` cannot go together. `maxRunning` limits how many workspaces run at the same time. When `--new` needs one more, the error names that limit:

```text
Failed: --new needs one more running workspace, and 10 of 10 run already (the maxRunning limit) — fix: pause an idle workspace (cf-opencode pause <workspace>), run without --new, or raise maxRunning in ~/.cf-opencode/config.json and run cf-opencode upgrade
```

A worktree uses the CPU and memory of its workspace. Several worktree tasks in a small instance type are slow. `--new` gives each task its own container.

## Run with no permission prompts

By default, a permission request of the agent puts the task in `waiting` until a person answers it. `--auto` lets the agent run with no permission prompts:

```sh
cf-opencode run "Upgrade the test runner and fix what breaks" --auto
```

The Worker starts the session with a permission rule that allows each action, followed by the deny rules of the agents. A rule that denies an action still applies. When the Worker cannot read those rules, it answers each open permission request with "allow once" when it reads the task state, as `opencode run --auto` does. A question to you (a form) still puts the task in `waiting`. Default: off.

## Write the task

The agent did not see your local conversation. Put everything it needs in the task:

- the goal,
- the branch to start from, if it is not the current one,
- the limits, for example "do not change the public API",
- how to prove that the change works, for example "run `npm test`".

`run` adds a fixed instruction to each task. It tells the agent to:

1. start from your current branch, or the `--branch`, as it is on `origin` (in a worktree: make a new branch first),
2. commit the work if it changed files, on a new branch if it is on the default branch,
3. push the branch, also when the work is not complete,
4. open a pull request if `gh auth status` succeeds,
5. not end its turn while a process that it started still runs,
6. run a job longer than a few minutes with `cf-opencode-job`, then end its turn,
7. end with one line: `Result: <what changed>; branch <name>; pull request <URL or none>`.

A task that changes no files, for example research, does not need a commit. It ends `done` with no commits.

### Long jobs

A job that runs for a long time (a build, an import, a batch of model calls) needs care. The workspace pauses `idlePauseMinutes` after the agent's last message, and a pause stops every process. A process that the agent starts in the background does not keep the workspace awake.

The agent runs such a job with `cf-opencode-job`:

```sh
cf-opencode-job start --name import -- python3 import.py
```

```text
job-3f9a1c started: import
log: /home/user/.cf-opencode/jobs/job-3f9a1c/log
```

1. `start` returns at once. The job runs apart from the agent's turn, with its output in the log.
2. The agent ends its turn. The task stays `running`.
3. A running job counts as use, so the workspace stays awake until the job ends.
4. When the job ends, the session gets one message with the exit code and the end of the log. The agent goes on: it checks the result, commits and pushes.
5. The task is `done` when the agent ends that turn.

`run` tells the agent to do this for a job longer than a few minutes. The workspace notes say it too. A job that the agent watched to its end (`cf-opencode-job wait`, `status` or `logs -f`) gets no message: the agent already knows.

Limits:

- A job ends at its maximum run time: `--max-minutes`, default 120, at most 1440. Then the job gets `SIGTERM`, and `SIGKILL` 10 seconds later.
- `maxAwakeHours` still pauses the workspace, also while a job runs. It is the cost guard. A pause stops the job, and the task is `stopped`.
- The job is tied to the OpenCode session that started it. A job started in `cf-opencode shell` or over SSH has no session. It gets no message, and no task waits for it.

For a job of hours, write these in the task too:

- "Make the job able to continue from where it stopped", for example with a checkpoint file for each unit of work.
- "Commit and push at each checkpoint", so the work is on the remote before the job ends.

The other commands are `cf-opencode-job list`, `status <id>`, `logs <id> [-f]`, `wait <id> [--timeout <seconds>]` and `stop <id>`. See [The workspace image](https://cf-opencode.system3inference.dev/docs/reference/image/#long-jobs).

## Ask for a structured result

`--schema <file.json>` asks the agent to end its last message with one fenced `json` block that matches a JSON Schema. `run` adds the schema to the task text. An example `result.json`:

```json
{
  "type": "object",
  "properties": {
    "callers": { "type": "array", "items": { "type": "string" } },
    "safe": { "type": "boolean" }
  },
  "required": ["callers", "safe"],
  "additionalProperties": false
}
```

```sh
cf-opencode run "List the callers of parseConfig and say if a rename is safe" --schema result.json
```

When the task ends, the Worker reads the last `json` block of the last message and checks it against the schema. The result then has `structured`, the parsed value. When the block is missing or does not match, the result has `structuredError` instead. The state does not change.

The schema can use these keywords only: `type`, `properties`, `required`, `items`, `enum` and `additionalProperties: false`. `title`, `description` and `$schema` are allowed and do nothing. A schema with any other keyword fails before the workspace wakes:

```text
Failed: result.json is outside the supported JSON Schema subset ($.properties.n: keyword minimum is not supported) — fix: use only type, properties, required, items, enum, additionalProperties false (and title, description, $schema)
```

The schema is kept with the task in the Worker. `tasks` on another machine shows the same `structured` value.

## The preflight

`run` fails before it wakes anything when one of these is true:

- The branch has no upstream. Push it with `git push -u origin <branch>`.
- The branch has commits that are not pushed.
- Files have changes that are not committed, or git does not track them.

The error is one line, for example:

```text
Failed: local checkout /home/you/my-app: 1 commit on feat not pushed to origin/feat; the workspace clones from the Git remote and would not see this — fix: commit and git push on this machine, or pass --allow-dirty
```

The preflight reads the checkout on your machine, the one in the path of the message. It does not read the workspace. This is also true when you name another workspace as the target of `run`.

`--allow-dirty` starts the task anyway. It prints what the workspace will not see. A directory that is not a git checkout has no preflight.

The preflight does not fetch. It compares with the upstream as your machine last saw it.

With `--branch <name>`, the preflight is different: it asks `origin` for that branch, and does not read the state of your checkout. See [Start from another branch](#start-from-another-branch).

## Check a task

List the tasks of all your workspaces:

```sh
cf-opencode tasks
```

```text
   WORKSPACE  SESSION     STATE    AGE     TITLE
*  my-app     ses_19c0…   done     2h ago  Fix the login form
   my-app     ses_4f2a…   running  3m ago  Health check

* ended, not read yet. Reading one marks it read.
```

A task has one of these states:

| State | Meaning |
| --- | --- |
| `running` | The agent works, or a long job of the task runs. `tasks` shows `running, job` for the second. |
| `done` | The agent finished its turn. A task with no commits can be `done`. |
| `failed` | The turn stopped with an error, or did not start. |
| `waiting` | The agent asks a question or asks for a permission. |
| `stopped` | The workspace paused while the task ran. `cf-opencode connect <workspace> --session <ses_…>` continues it. |

### Results you did not read

A task that leaves `running` is marked with `*` until you read it with `cf-opencode tasks <ses_…>`. These tasks come first in the list. A list does not mark them read. `cf-opencode tasks --unseen` lists only these tasks.

### Show one task

```sh
cf-opencode tasks ses_19c0…
```

```text
Task       ses_19c0…
Workspace  my-app
State      done
Title      Fix the login form
Started    2h ago

Summary:
  The form now trims the email before it checks it. Tests pass.
  Result: trim the email; branch fix-login; pull request https://github.com/acme/my-app/pull/7

Branch     fix-login
Commits    1
  3f1c2a9 Trim the email in the login form
PR         https://github.com/acme/my-app/pull/7
Changed    src/login.ts, test/login.test.ts

Open: cf-opencode connect my-app --session ses_19c0…
```

A task with `--worktree` also shows `Worktree` with its path in the workspace. A task with commits on a pushed branch shows the `Pull:` command. See [Bring the branch to your checkout](#bring-the-branch-to-your-checkout).

`Branch`, `Commits`, `PR` and `Changed` are facts. The Worker reads them with `git` and `gh pr view` in the workspace. They do not come from the agent's message.

If the same session ID is in two workspaces, add `--workspace <id>`.

`tasks` wakes nothing. A running workspace answers with the current states. A paused workspace answers with the states that it saved when it paused.

### Work that is not safe

A task can end `done` while its work is only in the workspace. The Worker checks two facts when a task ends:

- `unpushed`: commits that no remote branch has. They are only on the workspace disk.
- `processes`: processes that the agent left running in the checkout. The next pause stops them.

`cf-opencode tasks` marks such a task with `!` after the state. `tasks <ses_…>` shows the facts and the command that tells the agent to finish:

```text
Not pushed ! 13 commits are only on the workspace disk
Processes  ! left running, a pause stops them: node build.js

The task ended with work that is not safe. Tell the agent: cf-opencode tasks ses_19c0… --reply "Wait for your process to end, then commit and push."
```

The result record has the same two fields, so a script and the notify URL get them too. The facts are from the time the task ended. A later end of the same task (after a reply) reads them again.

### The automatic reply

You do not have to send that reply yourself. When a task changes to `done` and the facts show `unpushed` or `processes`, the Worker sends the session one message. The message says what the Worker found, and tells the agent to push the branch and not to end its turn while a process that it needs runs. The agent then goes on.

- The Worker sends it one time for each task. A later turn, or your own `--reply`, does not send it again.
- The alarm sends it, so it works with the laptop closed.
- The task stays `running` until the agent ends the turn of the reply. `--wait` keeps waiting, and the notify URL gets one result: the one after the reply.
- The Worker does not send it for a task that is `failed`, `waiting` or `stopped`.
- The Worker does not wake a paused workspace for it. When the last read before a pause sees the change, the task is `done` and the record says that the reply was not sent. Send `--reply` yourself to wake the workspace.
- With `--schema`, the message asks the agent to end with the `json` block again. If the answer has no block, the record keeps the block from before the reply.

`tasks <ses_…>` shows it:

```text
Auto reply 12m ago: told the agent (2 commits not pushed)
```

The setting `autoReply` turns it off. See [Configuration](https://cf-opencode.system3inference.dev/docs/reference/configuration/).

## Wait for a task

```sh
cf-opencode tasks ses_4f2a… --wait
```

`--wait` asks the Worker every 10 seconds. It returns when the task is not `running` any more, and prints the result. The exit code tells the result:

| Exit code | Meaning |
| --- | --- |
| 0 | `done` |
| 1 | `failed` |
| 2 | `waiting` |
| 3 | The wait timed out. The task can still run. |
| 4 | `stopped` |

`--timeout <minutes>` sets how long the command waits. The default is 60. `cf-opencode run --wait` starts a task and waits for it.

An agent that watches a task should wait in short steps, for example `--wait --timeout 5` in a loop. Exit code 3 means "check again later".

A dropped connection on your machine does not end the wait. `--wait` and `--follow` print `the task goes on in the workspace; trying again` and continue. After 5 minutes with no answer they stop with exit code 3: the state is not known, and the task is not affected.

## Follow a task live

```sh
cf-opencode tasks ses_4f2a… --follow
```

`--follow` shows what the agent does while it works: one line for each tool call, and the agent's text for each message. It ends as `--wait` does, prints the result, and uses the same exit codes.

```text
→ bash: npm test
✗ bash: exit 1
→ edit: src/login.ts
  The test failed on an empty email. I trim it first now.
· turn succeeded
```

`--follow` reads OpenCode's event stream through the Worker, with the workspace password. When the stream drops, it connects again. When the stream does not open, it says so and checks every 10 seconds, as `--wait` does. `cf-opencode run --follow` starts a task and follows it.

With `--json`, `--follow` prints one JSON object for each event, one per line, and then the result record. Each event has `type` and `at`. The types are `text`, `tool`, `tool.failed`, `question`, `retry`, `error`, `turn.started` and `turn.ended`.

## Answer a waiting task

A task in `waiting` needs you. The result shows the question. Send your answer as one more message:

```sh
cf-opencode tasks ses_4f2a… --reply "Use the staging database."
```

`--reply` wakes a paused workspace. Add `--wait` or `--follow` to watch the task go on. A permission request is not answered this way. A task started with `--auto` does not stop for one. Open the session in your local OpenCode and answer there:

```sh
cf-opencode connect my-app --session ses_4f2a…
```

A waiting task does not keep the workspace awake. The workspace pauses after `idlePauseMinutes`. `connect` wakes it again with the question still open.

## Bring the branch to your checkout

```sh
cf-opencode tasks ses_19c0… --pull
```

```text
Fetched origin/fix-login (3f1c2a9) and made the local branch fix-login, which tracks it. Switch to it: git switch fix-login
```

`--pull` fetches the task's branch from `origin` into the checkout in the current directory. Then it makes a local branch that tracks it, or moves a local branch that is behind to the fetched commit. Your files and the branch you have checked out do not change. One exception: when the task's branch is the branch you have checked out, and it has no changes that are not committed, `--pull` moves it forward (`git merge --ff-only`).

`--pull` fails, with the fix, when:

- the task made no commit, or has no branch yet,
- the task has commits that are only on the workspace disk (`unpushed`). The fix is the `--reply` that tells the agent to push,
- `origin` does not have the branch,
- the local branch and the task's branch both have commits that the other does not have. The fetch is done. Merge them yourself,
- the current directory is a checkout of another repository than the workspace's.

`--pull` goes alone. Wait first with `--wait`, then pull.

## Continue a stopped task

A pause stops `opencode serve`. A task that still runs then is saved as `stopped`, for example at `maxAwakeHours`, or after `cf-opencode pause`. Its branch and commits are read before the pause. Open the session to continue it:

```sh
cf-opencode connect my-app --session ses_4f2a…
```

## Get a message when a task ends

Store the URL as a Worker secret. The command reads it from stdin, or asks for it on a terminal without echo. It never takes the URL as an argument, because a webhook URL often holds its own secret:

```sh
printf %s "$WEBHOOK_URL" | cf-opencode notify-url
```

The URL must be `https`, with no user or password in it, to a public host name. Running workspaces use a new URL at once. `cf-opencode notify-url --remove` deletes it. `doctor` says whether one is set, never the URL.

When a task leaves `running`, the Worker sends a `POST` to that URL. The body is the [result record](#output-for-agents). The Worker sends again when the task changes later, for example from `waiting` to `done`.

- Headers: `content-type: application/json`, `x-cf-opencode-event: task`, `x-cf-opencode-timestamp: <Unix seconds>` and `x-cf-opencode-signature: sha256=<hex>`.
- The signature is the HMAC-SHA256 of the text `<timestamp>.<raw body>`. Refuse a delivery whose timestamp is more than 5 minutes old. The key is the text that `cf-opencode notify-key` prints. Keep the key secret, and check the signature before you use the body.
- An answer other than 2xx, or no answer in 10 seconds, is a failure. The Worker tries again after 1, 5 and 30 minutes. Then it stops. `tasks <ses_…>` shows `Notified` with the time and the HTTP status, or the error.
- The Worker does not follow redirects.
- The signature covers the body only. A copy of a signed body stays valid, so drop a delivery you already have: the same `id`, `state` and `updated`.

The agent in the workspace can also send a note to the same URL with `cf-opencode-notify "<text>"`. The body is `{"type":"note","workspace":"…","text":"…","at":"…"}`, and the header `x-cf-opencode-event` is `note`. A note has at most 4000 characters. A note is sent once. A workspace can send at most 20 notes in one hour. When no notify URL is set, the command fails with one line.

A note is the agent's text. The agent can send any text, and the Worker signs it with your key. Do not act on a note as if it came from you, and drop a note whose `at` is old.

## When the laptop is off

- The task runs in the workspace. A closed laptop does not stop it.
- `--follow` and `--wait` run in your terminal. They end when the terminal ends. The task goes on.
- The result stays in the Worker. `cf-opencode tasks` shows it the next time, also when the workspace is paused. The task stays marked `*` until you read it.
- The Worker sends to the notify URL, not your laptop. Use a receiver that is always on: a chat webhook, a phone push service, or an email bridge. A URL on your laptop gets nothing while the laptop is off.

## Choose a model

`--model <provider/model>` sets the model of the new session. For example:

```sh
cf-opencode run "Update the README for the new flag" --model cloudflare-workers-ai/@cf/zai-org/glm-5.3
```

Without `--model`, the session uses the default model of the workspace. See [Models](https://cf-opencode.system3inference.dev/docs/concepts/models/).

## Output for agents

`--json` makes stdout one JSON document. Progress goes to stderr.

- `run --json`: `{"ok":true,"workspace":"…","session":"ses_…","title":"…","state":"running"}`. It adds `"newWorkspace": true` with `--new`, `"worktree": "<path>"` with `--worktree` and `"auto": true` with `--auto`.
- `tasks <ses_…> --pull --json`: `{"ok":true,"workspace":"…","session":"ses_…","branch":"…","commit":"…","local":"created","checkedOut":false}`. `local` is `created`, `updated` or `current`.
- `tasks --json`: the task list and, for each workspace, where its list came from. A task that ended and was not read has `"unseen": true`.
- `tasks <ses_…> --json`, `--wait --json` and `run --wait --json`: the result record.

The result record:

| Field | Meaning |
| --- | --- |
| `id`, `workspace`, `title` | The session ID, the workspace and the session title. |
| `state` | `running`, `done`, `failed`, `waiting` or `stopped`. |
| `summary` | The last message of the agent that has text (the end of it). |
| `branch` | The branch of the workspace checkout, or of the task's worktree. |
| `worktree` | With `--worktree`: the path of the task's git worktree in the workspace. |
| `commits` | `[{ "sha", "subject" }]`, the commits made after the task started that no other remote branch has. At most 30. An empty list means no commit. |
| `pullRequest` | The pull request of the branch, when `gh pr view` finds one. |
| `changedFiles` | The files of the task's commits, and the files with changes that are not committed. At most 100. |
| `unpushed` | The count of commits that no remote branch has. Left out when it is 0. |
| `processes` | The processes left running in the checkout: the program name and its first plain argument. At most 5. Left out when there are none. A long job is not in this list. |
| `jobs` | The long jobs of the task: `[{ "id", "name", "state", "exit"? }]`. `state` is `running`, `done`, `failed`, `timeout` or `stopped`. Left out when there are none. |
| `question` | When `waiting`: the open permission request or question. |
| `error` | When `failed` or `stopped`: why. |
| `structured`, `structuredError` | With `--schema`: the checked value, or why there is none. |
| `autoReply` | When the task ended with work that is not safe: `{ "at", "sent", "found", "error"? }`. `found` says what the Worker saw. `sent` is `false` when the reply did not go out, and `error` says why. |
| `notified`, `notifyError` | With a notify URL: the last delivery, or why it failed. |
| `started`, `updated` | ISO times. |

Fields that are not known are left out. The Worker reads `branch`, `commits`, `changedFiles`, `unpushed` and `processes` while a task runs, and once more with `pullRequest` when the task ends.

A failure is one line, `Failed: <cause> — fix: <action>`. With `--json` it is `{"ok":false,"error":"…"}`.

## The handoff skill for agents

The CLI package has a skill file that tells a local agent when and how to hand off a task: the preflight, how to write the task, how to watch it, and what to do for each state.

```sh
cf-opencode skill                       # print where it is, and its text
cf-opencode skill --install --claude    # copy it to ~/.claude/skills/cf-opencode-handoff/
cf-opencode skill --install --opencode  # copy it to ~/.config/opencode/skills/cf-opencode-handoff/
cf-opencode skill --install --dir <path>
```

OpenCode also reads `~/.claude/skills`. `--install` does not replace a file that differs. Add `--force` to replace it.

`cf-opencode init` installs this skill for Claude Code and OpenCode when their config folder exists on the machine. It asks first on a terminal. `--no-skill` skips the step.

## Skills for the task

`run --skills a,b` copies skills from this machine into the workspace before the task starts. See [Skills in a workspace](https://cf-opencode.system3inference.dev/docs/guides/skills/).

## What the agent is told

A handed-off session gets a Handoff block before the task. See [What the agent knows](https://cf-opencode.system3inference.dev/docs/concepts/what-the-agent-knows/).

## Limits

- One task at a time uses the checkout of a workspace. A second task needs `--worktree` or `--new`. See [Run two tasks at once](#run-two-tasks-at-once).
- A worktree from `--worktree` and a workspace from `--new` stay after the task. Remove them yourself.
- `run` never sends local files. Uncommitted work stays on your laptop.
- A pause stops processes. A task that still runs when the workspace pauses is `stopped`. Continue it with `connect`.
- `commits` and `changedFiles` do not count what a merge or a new branch brings from the remote. A commit that two remote branches have is not counted.
- `processes` lists a process only when nothing watches it. A process that runs in a terminal (`cf-opencode shell`, SSH) is not listed. A long job is not listed either: it is in `jobs`.
- `run` copies no file from another workspace. Use `cf-opencode cp` first. See the next section.

## Move a file between workspaces

`cf-opencode cp` copies a file or a folder from one workspace to another. Run it on your machine:

```sh
cf-opencode cp app:export.json.gz api:data/
```

- `app:export.json.gz` is a path in the workspace `app`, relative to its checkout. A path can also start with `/` or `~` inside `/home/user`.
- `api:data/` is a folder in the checkout of `api`. An existing folder, or a path that ends in `/`, takes the item inside it. A folder that does not exist is made.
- A target that exists stays as it is unless you pass `--force`.
- The target changes only when the whole copy arrives and passes the check. A copy that fails leaves the target as it was.

The same command copies between a workspace and this machine:

```sh
cf-opencode cp app:build ./build      # from the workspace to this machine
cf-opencode cp ./fixtures app:test/   # from this machine to the workspace (at most 100 MB)
```

How a copy works:

- The files go through your Worker, not through a third service. The Worker reads every name in the stream. It refuses an absolute path, a `..`, a link that points out of the copied tree, and a device file. The files are written as `user`, never as root.
- A paused workspace wakes for the copy, because its disk is only readable in a running container. The progress line says so. The wake counts toward `maxRunning`, and the workspace pauses again when it is idle.
- Only the control token can start a copy. An agent in a workspace has the workspace password, which reaches no other workspace.
- One copy moves at most 4 GB and 200,000 entries, and runs at most 30 minutes. See [Limits](https://cf-opencode.system3inference.dev/docs/limits/).

An agent in a workspace cannot run `cp`. Run it yourself before the task starts, and name the path in the task. To let agents share files during a task, turn on the store.

### Through the store

The store is an R2 bucket in your account. It is off by default. Turn it on in `~/.cf-opencode/config.json`, then upgrade:

```json
{ "store": true }
```

```sh
cf-opencode upgrade
```

`upgrade` makes the bucket `<worker>-store` (for example `cf-opencode-store`) and binds it to the Worker. The Cloudflare login needs R2 access: an API token needs Workers R2 Storage Write, and R2 must be on in the account.

On your machine, a `store:<name>` side copies a file in or out:

```sh
cf-opencode cp app:export.json.gz store:              # the name is export.json.gz
cf-opencode cp store:export.json.gz api:data/
cf-opencode cp ./seed.sql store:seeds/seed.sql        # from this machine, at most 100 MB
cf-opencode store                                     # list the files
cf-opencode store rm seeds/seed.sql                   # remove one
```

In a workspace, the agent uses `cf-opencode-store`:

```sh
cf-opencode-store put export.json.gz     # saved as <this workspace>/export.json.gz
cf-opencode-store list
cf-opencode-store get app/export.json.gz  # saved as ./export.json.gz
```

- `cf-opencode-store` needs `ai` on, which is the default: it uses the same intercepted host as the models. A workspace made before this version has no `cf-opencode-store` until you run `cf-opencode rebuild <workspace>`.
- The store holds files, not folders. Pack a folder first: `tar czf data.tgz data`.
- An agent saves a file under its own workspace name, and removes only those files. It reads every file in the store.
- A file from an agent is at most 100 MB. A copy from a workspace with `cf-opencode cp` takes up to 4 GB.
- Files in the store outlive a pause, a `delete` and an `uninstall`. R2 bills for the storage per GB-month and for each request, with a free monthly allowance. See [R2 pricing](https://developers.cloudflare.com/r2/pricing/). Remove what you do not need with `cf-opencode store rm`.
- Put no secret in the store. Every agent of the install can read it.

### Through Git

Git also moves a file, and the agent can do it during a task. Put the file on a branch with no history and fetch it there:

```sh
# In the workspace that has the file
git checkout --orphan data-snapshot
git rm -rf --cached . > /dev/null
git add -f export.json.gz
git commit -m "Data snapshot"
git push -f origin data-snapshot
git checkout -f <your branch>

# In the other workspace
git fetch origin data-snapshot
git show FETCH_HEAD:export.json.gz | gunzip > export.json
```

Name the branch and the two commands in the task. An agent that is told only "get the export" must ask where it is. GitHub refuses a file over 100 MB, so compress or split a larger file.

Source: https://cf-opencode.system3inference.dev/docs/guides/hand-off-a-task/index.mdx
