OpenCode
The CreateOS plugin for OpenCode adds 38 sandbox tools to the agent. OpenCode keeps running locally; the tools give it a remote Linux box to build in, run services on, and throw away.
At a glance
- Package:
@createos/opencode - Tools: 38, all prefixed
sandbox_ - Auth:
createos login - Sandbox: created on the first tool call, destroyed when the session is deleted
Prerequisites
Install the createos CLI:
Bash
The plugin installs it on first use if it is missing, so this step is optional.
Then authenticate. At a terminal, sign in:
Bash
For CI or headless use, set an API key instead:
Bash
The plugin holds no credentials of its own. It shells out to the CLI and uses whatever session the CLI has, so anything that authenticates the CLI authenticates the plugin.
Install
Bash
How it works
The plugin does not replace OpenCode's built-in bash, read, or write tools. Those keep acting on your machine. What it adds is a parallel set of sandbox_* tools that act on a remote box, so the agent chooses explicitly when to work remotely.
The sandbox is created lazily, on the first sandbox_* call rather than at startup, so a session that never touches these tools never creates one. When it is created:
| Setting | Value |
|---|---|
| Shape | s-2vcpu-2gb, or CREATEOS_SHAPE |
| Root filesystem | CREATEOS_ROOTFS, otherwise the CLI default |
| Networks | CREATEOS_NETWORKS, comma-separated |
| Working directory | /root/workspace |
| Public HTTPS URL | Enabled |
The box is destroyed when the session is deleted.
Because the agent picks tools explicitly, tell it where you want work to run. "Run the test suite in the sandbox" is unambiguous; "run the tests" will use the local shell.
Offloading, or driving a box
Two shapes of work, two sets of tools, and mixing them up is the common mistake.
| The work | The tool |
|---|---|
| Has a finish line — a build, a test suite, a script | sandbox_offload — one call, box destroyed afterwards |
| Several variants of that at once — shards, a config matrix | sandbox_fanout — one throwaway box per command |
| Outlives one command — a dev server, a watcher, a session | sandbox_create and sandbox_exec, then sandbox_destroy |
sandbox_offload is not a convenience wrapper over create plus exec. It carries what a hand-rolled sequence silently drops: egress restricted to the domains the build actually needs, a keepalive so a dropped stream does not kill a long build, destruction guaranteed even when the command fails, and staging excludes that keep .git, node_modules, target, and large media off the wire.
Tools
| Group | Tools |
|---|---|
| Offload and fan-out (2) | sandbox_offload, sandbox_fanout |
| Desktop (3) | sandbox_desktop, sandbox_computer, sandbox_screenshot |
| Lifecycle (8) | sandbox_create, sandbox_exec, sandbox_info, sandbox_list, sandbox_pause, sandbox_resume, sandbox_fork, sandbox_destroy |
| Configuration (5) | sandbox_ingress, sandbox_firewall, sandbox_bandwidth, sandbox_shapes, sandbox_images |
| Ports and sync (3) | sandbox_preview_url, sandbox_tunnel, sandbox_sync |
| Networks (6) | sandbox_network_create, sandbox_network_list, sandbox_network_show, sandbox_network_attach, sandbox_network_detach, sandbox_network_delete |
| Disks (6) | sandbox_disk_create, sandbox_disk_list, sandbox_disk_show, sandbox_disk_delete, sandbox_disk_attach, sandbox_disk_detach |
| Device VPN (5) | sandbox_device_register, sandbox_device_status, sandbox_vpn_up, sandbox_device_attach, sandbox_device_detach |
sandbox_exec requires a sandbox ID. Have the agent call sandbox_info or sandbox_list first if it needs to discover the active box.
sandbox_vpn_up is advisory — it returns the command for you to run, because bringing up WireGuard needs sudo.
To move files, run the transfer through sandbox_exec, or set up a directory sync with sandbox_sync.
Desktop
On a box created with the desktop:1 root filesystem, sandbox_desktop returns a live noVNC URL you can open in a browser to watch or drive it. sandbox_computer performs one desktop action from the agent side — read the screen bounds, move the cursor, click, type, press a key, open a URL, or list windows — and sandbox_screenshot captures the screen as a PNG.
Coordinates are raw X11 pixels, so read the screen bounds rather than assuming a resolution.
Configuration
| Variable | Purpose |
|---|---|
CREATEOS_ENABLED | Turn the plugin on or off |
CREATEOS_SHAPE | Machine size |
CREATEOS_ROOTFS | Base image or template |
CREATEOS_NETWORKS | Private networks to join, comma-separated |
File sync
sandbox_sync mirrors a local directory into the box and keeps it there for the session. It takes a local and remote directory, an optional mode — two-way, one-way, or mirror — and optional exclude globs.
It applies no exclusions of its own, so pass excludes for anything large or sensitive. A sync of a project root without excludes will pick up node_modules, build output, and .env files.
See also
- Pi — the same tool surface, and it can replace the agent's built-in tools too
- CLI reference — what the tools call underneath
- Concepts — sandboxes, networks, ingress, snapshots