Run OpenCode with Tensorlake Sandboxes

Route OpenCode’s file and shell tools into a Tensorlake sandbox with a single plugin. The model edits, runs, and searches inside an isolated environment instead of on your machine.

OpenCode is a terminal coding agent. The tensorlake-opencode plugin redirects the agent’s hands (its file and shell tools) into a Tensorlake sandbox, so the model’s commands and edits run in an isolated environment you control rather than on your laptop.

The model: brain local, hands in the sandbox

OpenCode keeps running locally: the TUI, the model loop, and your session all stay on your machine. The plugin only intercepts the tool calls and routes them to a sandbox:

OpenCode tool	Runs in the sandbox as
bash	sandbox.run('sh', { args: ['-c', cmd] })
read	sandbox.readFile(path)
write	sandbox.writeFile(path, content)
edit	read + string replace + write
multiedit	several string replacements on one file, then one write
apply_patch	parse the patch, then read/write each file in the sandbox
ls	sandbox.listDirectory(path)
glob	find in the sandbox via bash, matched against the project directory
grep	grep -rn … via bash, with include to narrow the file set

apply_patch matters more than it looks. OpenCode’s built-in apply_patch writes to your local filesystem. The plugin shadows it (plugin version 0.3.0 and later) so a patch cannot bypass the sandbox.

webfetch and websearch are not intercepted. They stay local, since they don’t touch your filesystem.

Subagents (the task tool) run in their own OpenCode session but use the sandbox of the session that spawned them. See Subagents.

The sandbox itself runs on Tensorlake: fast boot, sub-second resume from a suspended snapshot, and state that persists across OpenCode restarts. See Sandbox lifecycle for the suspend/resume and snapshot model underneath.

Why route tool calls into a sandbox

• Isolation. The agent’s bash and write never touch your host. A bad command, a runaway install, or an rm lands in a disposable environment, not your working tree.
• Reproducible environment. Every session gets the same image, CPU, and memory regardless of what’s on the developer’s machine. Pin a custom image with the right toolchain once and every session inherits it.
• State that survives restarts. Sandboxes are named and persisted to disk, so a session reconnects to its sandbox across OpenCode restarts; a suspended sandbox resumes with /tmp/workspace, installed deps, and warm caches intact.
• Work that outlives the sandbox. Mount a Tensorlake filesystem or attach a hosted git repository, and the agent’s files survive sandbox deletion. See Persist work across sandboxes.

Prerequisites

• An OpenCode installation.
• A Tensorlake project API key. Sign up at cloud.tensorlake.ai, open your project, and create a key under API Keys. Personal Access Tokens are not supported.
• A supported platform. The Tensorlake SDK ships a native binary for macOS on Apple Silicon (Intel Macs are not supported), Linux x64 and arm64 (glibc and musl), and Windows x64.

Setup

1. Add the plugin to your OpenCode config

   Add the package name to ~/.config/opencode/opencode.json (create the file if it doesn’t exist):

   {
     "$schema": "https://opencode.ai/config.json",
     "plugin": [
       "tensorlake-opencode"
     ]
   }
   

   OpenCode treats bare names as npm packages and installs them into its own cache (~/.cache/opencode/packages/). You don’t run npm install yourself.

2. Log in

   The plugin registers Tensorlake in OpenCode’s standard auth flow (plugin version 0.2.0 and later):

   opencode auth login
   

   Select Tensorlake and paste a project API key (it starts with tl_apiKey_). OpenCode stores the key in its credential store next to your other provider credentials. If the key is wrong, the first tool call shows an error toast that tells you to log in again — no restart needed, just retry after logging in.

   CI / automation: set the TENSORLAKE_API_KEY environment variable instead. It wins over the stored key. Use a project API key; the key itself selects the organization and project.

3. Start OpenCode

   opencode
   

   On startup the plugin loads but no sandbox is created yet. Confirm it loaded by tailing its log:

   tail -f ~/.local/share/opencode/log/tensorlake.log
   

   You should see a single line: OpenCode started with TensorLake plugin.

Lazy sandbox creation

The sandbox is created lazily, on the first intercepted tool call in a session, not when you launch OpenCode. If you start OpenCode and nothing appears to happen, that’s expected. A session that only uses webfetch/websearch will never spin one up, because neither is intercepted.

To trigger creation, ask the model to run something that uses a file or shell tool:

Run: uname -a

On that first bash call the plugin provisions the sandbox. You’ll see a “Sandbox created” toast and new log lines:

[INFO] Creating new sandbox for session abc123
[INFO] Sandbox created sandbox-xyz in 2300ms

uname -a will report Linux (the sandbox), confirming the command ran remotely rather than on your Mac.

Verify it’s working

Ask the model to write and read a file back:

Write the text "Hello Tensorlake" to /tmp/workspace/test.txt, then read it back.

The write call routes to sandbox.writeFile() and the read call to sandbox.readFile(), both over the SDK. The agent’s working directory inside the sandbox is /tmp/workspace.

Subagents

When the model uses the task tool, OpenCode starts a subagent in a child session. The child session does not get its own sandbox. It shares the sandbox of the session that spawned it, all the way up to the root session of the tree. This mirrors how local subagents share the user’s working tree: the parent sees the subagent’s edits, and the subagent sees the parent’s.

• Deleting a subagent session deletes nothing. The sandbox belongs to the root session, and is torn down when that session is deleted.
• Deleting the root session waits for subagent tool calls that are still running, so nothing is terminated mid-write.

Persist work across sandboxes

By default a sandbox’s disk is ephemeral: deleting the session deletes its files. Two optional plugin settings let the agent’s work outlive the sandbox. You set them as plugin options in opencode.json, or as environment variables (the environment variable wins).

Persistent filesystem

Create a Tensorlake filesystem and name it in the plugin options:

tl fs create my-workspace

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["tensorlake-opencode", { "filesystem": "my-workspace" }]
  ]
}

Every sandbox now mounts that filesystem at the working directory, /tmp/workspace. Files the agent writes there persist in durable storage, survive sandbox deletion, and are visible to every other sandbox or tl fs mount that mounts the same filesystem. Set filesystemPath (or TENSORLAKE_FILESYSTEM_PATH) to mount it somewhere else.

A misspelled filesystem name blocks tool calls with a “Filesystem attach failed” toast instead of silently running against ephemeral storage.

To put local files into the filesystem, use tl fs mount <name> <empty-dir>, not tl fs push. Mount is two-way and continuous. Push is one-way and destructive: it makes the filesystem match your local directory exactly, so a second push deletes every file the agent created. Use push once to seed a filesystem, never while a session is running. See Mount filesystems and Concurrent writes.

Hosted git repository

To let the agent persist work through git, name a Tensorlake git repository. The repository is hosted in your Tensorlake project, not on GitHub. Only people with an API key for the project can see it or push to it.

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["tensorlake-opencode", { "gitRepo": "my-repo" }]
  ]
}

The plugin creates the repository if it does not exist. In each sandbox it configures a Tensorlake credential scoped to that one repository and a fallback git identity, and refreshes the credential in long sessions. The model is told the clone URL, so “clone the repo, make the change, push” works out of the box.

Your own git credentials and remotes never enter the sandbox. To publish the code elsewhere, clone the Tensorlake repository to your machine and push it to GitHub yourself.

You can use filesystem and gitRepo together. The agent then clones the repository onto the mounted filesystem, so the working copy survives sandbox deletion and the pushed commits live in the repository. If you also mount that filesystem on your machine, run git commands from one side only: concurrent writes to the same .git files lose data silently.

Configure the sandbox

The plugin has two kinds of settings:

• Plugin options in opencode.json choose what the sandbox attaches to: a filesystem and a git repository. Each also has an environment variable, and the variable wins.
• Environment variables decide what the sandbox looks like: its image, CPUs, memory, and disk. There is no config-file form for these; you set them in the shell, then launch OpenCode from that same shell.

The plugin reads both at sandbox-creation time.

The variables are read once, when the sandbox is created (the first intercepted tool call of a session). Set them before you run opencode. Changing a variable in another terminal, or after the sandbox already exists, has no effect on the running session. Start a new session to pick up new values.

How it fits together

# 1. Authenticate once (stored by OpenCode, no env var needed)
opencode auth login   # select Tensorlake, paste a project API key

# 2. Size the sandbox VM
export TENSORLAKE_CPUS=4
export TENSORLAKE_MEMORY_MB=8192
export TENSORLAKE_DISK_MB=20480

# 3. Choose the toolchain image (optional, omit for the platform default)
export TENSORLAKE_IMAGE=my-custom-image

# 4. Launch: the next sandbox this session creates uses all of the above
opencode

Every value above describes the sandbox the plugin spins up for that OpenCode session, not OpenCode itself, and not your local machine.

Plugin options

Set these in opencode.json as the second element of the plugin entry: ["tensorlake-opencode", { ... }].

Option	Env var	What it controls
filesystem	TENSORLAKE_FILESYSTEM	Tensorlake filesystem to mount into every sandbox. See Persistent filesystem
filesystemPath	TENSORLAKE_FILESYSTEM_PATH	Mount path for that filesystem. Default: /tmp/workspace
gitRepo	TENSORLAKE_GIT_REPO	Tensorlake-hosted git repository to set up in every sandbox. See Hosted git repository

All variables

Variable	Default	What it controls
TENSORLAKE_API_KEY	(optional)	Overrides the key stored by opencode auth login. For CI/automation
TENSORLAKE_IMAGE	(platform default)	Registered image the sandbox boots from. Bake your runtimes, build tools, and repo deps in here
TENSORLAKE_CPUS	2	vCPUs allocated to the sandbox
TENSORLAKE_MEMORY_MB	4096	RAM allocated to the sandbox, in MB
TENSORLAKE_DISK_MB	10240	Ephemeral disk allocated to the sandbox, in MB
TENSORLAKE_SHUTDOWN_DRAIN_MS	15000	How long OpenCode exit waits for in-flight sandbox work before suspending the sandbox

Making the settings persistent

Your API key persists on its own — opencode auth login stores it once. The filesystem and git settings persist in opencode.json. The sandbox-sizing variables are shell exports, so to apply the same config every time, add them to your shell profile (~/.zshrc or ~/.bashrc):

echo 'export TENSORLAKE_IMAGE=my-custom-image' >> ~/.zshrc
echo 'export TENSORLAKE_CPUS=4' >> ~/.zshrc

Open a new terminal (or source ~/.zshrc) and every opencode session inherits them.

Use a custom image

TENSORLAKE_IMAGE is the most impactful setting for real work: it lets every OpenCode session start from an environment that already has your language runtimes, system packages, and project dependencies, so the agent isn’t reinstalling them on each session. Register an image, then point the variable at its name:

tl sbx image create Dockerfile --registered-name my-custom-image
export TENSORLAKE_IMAGE=my-custom-image

See Build and Import Images for building and managing images.

Troubleshooting

No sandbox starts when I launch OpenCode. Expected. The sandbox is created on the first tool call, not at launch. Ask the model to run a command (for example, Run: uname -a).

“Tensorlake login required” toast. Run opencode auth login, select Tensorlake, and paste a project API key. No restart is needed; retry the tool call.

Auth error (401/403) in the log. The stored key was revoked. Re-run opencode auth login with a fresh project API key.

“Filesystem attach failed” toast. The name in filesystem / TENSORLAKE_FILESYSTEM does not exist in this project. Create it with tl fs create <name> or fix the name.

tl fs unmount fails with volume_busy. A process still holds the mount, usually a shell whose working directory is inside it. Leave the directory (cd ~), close editors pointed at the path, then unmount.

Missing native binding for <platform>. Your platform is not supported by the Tensorlake SDK. See Prerequisites.

Anything else. Check ~/.local/share/opencode/log/tensorlake.log. If the file does not exist, the plugin never loaded.

Next steps

Plugin source

The full plugin: tool interceptors, session manager, and lifecycle handling.

Sandbox lifecycle

The suspend/resume and snapshot model that persists session state.

Build and Import Images

Build a custom image so every OpenCode session gets the same toolchain.

Filesystems

Durable storage the agent’s files survive in after the sandbox is gone.

Git repositories

Hosted repositories the agent can clone, commit, and push to.

Tool calls

The general pattern: expose sandboxes as tools to any LLM agent.