OpenCode
The CreateOS plugin for OpenCode adds 33 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: 33, 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.
Tools
| Group | Tools |
|---|---|
| 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.
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