sandboxes
running the agent on a throwaway machine
normally the agent runs on the runner's machine with all its access, and a sandbox moves it somewhere disposable instead:
import { exeSandbox } from "@tetraslam13/computah/server";
export default {
// ...
// members only. add `for: "everyone"` to sandbox owners too
sandbox: { in: exeSandbox() },
};what actually happens
the code gets copied in without your ignored files (so no .env), the agent works on that copy, only a patch comes back for the runner to apply, commit, check and build like any change, and the sandbox is thrown away. there's no live preview while that happens, it all shows up at the end
sandbox.in is which sandbox, and sandbox.for is who gets one: "members" (default) is everyone who isn't owner or trusted, "everyone" is every request
| sandbox | what it is | what it needs |
|---|---|---|
exeSandbox() | a standalone exe.dev vm per request, cut off from the internet except exe's model gateway | an ssh key exe.dev knows, on the runner's machine |
modalSandbox() | a modal sandbox per request | the modal package, modal credentials, and a modal secret holding your model key |
on exe a real claude code change took 12 seconds end to end, about 5 of it starting the vm. on modal the first sandbox took 113 seconds building the image and 2 seconds after that
keeping one ready
starting the machine is the slow part (about 5 seconds on exe), and the person is sitting there typing for longer than that anyway. so with warm the runner starts a sandbox when someone opens the box, and their request gets that one when they send it:
sandbox: { in: exeSandbox(), warm: { max: 3 } },| option | default | |
|---|---|---|
max | 2 | the most sandboxes sitting ready at once |
idleMs | 90 seconds | a ready one nobody used for this long gets thrown away |
min | 0 | keep this many ready all the time, whether anyone's around or not |
i set it up this way so it costs nothing while nobody is on the site. a sandbox only exists from the moment someone opens the box until their request is done, or for 90 seconds if they never ask. on exe that's $0.105 an hour for the default size, so someone who opens the box and wanders off costs about a quarter of a cent, and the worst a person could do by opening it over and over is keep max of them alive
min: 1 would make the very first person faster too, but then one is running day and night, which on exe is about $2.50 a day. i left it at 0
ready ones are deleted when the runner shuts down, and any that got left behind anyway are swept up when it starts again
each sandbox is still used for one request and thrown away. this works with any sandbox, including your own
exeSandbox
made and deleted over ssh. the stock image has claude code, codex and opencode, and by default it uses exe.dev's model gateway so no model keys go in
| option | default | |
|---|---|---|
egress | "integrations" | "integrations" reaches only exe.dev's own services like the model gateway, "all" the whole internet |
setup | points claude code and codex at exe's gateway | shell commands run once in a new sandbox, before the code goes in |
ssh | extra arguments for every ssh call, like ["-i", "/path/to/key"] | |
prefix | "computah-sbx-" and a few characters of this runner's own | the start of each sandbox's name. two runners on one account get different ones, so neither deletes the other's |
modalSandbox
install modal next to computah and put modal credentials in the environment or ~/.modal.toml
| option | default | |
|---|---|---|
app | "computah" | the modal app the sandboxes are created under |
image | "node:24-bookworm-slim" | a registry image to start from |
build | installs git, claude code, codex and opencode | dockerfile lines that put git and your agent on the image |
secrets | none | names of modal secrets to give the agent, like one holding ANTHROPIC_API_KEY |
blockNetwork | false | no network at all, only useful with an agent that needs none |
timeoutMs | 20 minutes | how long a sandbox can live |
modalSandbox({ secrets: ["anthropic"] });writing your own
a name and open(), which returns a session with two functions:
import type { Sandbox } from "@tetraslam13/computah/server";
const mine: Sandbox = {
name: "mine",
async open() {
// start a machine
return {
// Run a command there. Feed it `stdin`, call `onLine`
// for each line it prints, and resolve with its exit code,
// what it printed, and the end of its stderr.
async exec(command, { stdin, onLine } = {}) {
return { code: 0, stdout: "", stderr: "" };
},
// Stop whatever is running and throw the machine away.
// Safe to call more than once.
async close() {},
};
},
};the runner does the rest through exec (unpacking, running the agent, reading the patch back), so the machine needs sh, tar, base64, git and your agent
if your sandboxes cost money while they exist, also give it a sweep() that deletes any this runner left behind. the runner calls it when it starts, cause a runner that gets killed mid-request can't clean up after itself. exeSandbox has one, and it only touches sandboxes with its own runner's name on them
what's untested
modal has only run with a scripted agent. a real one needs a model key in a modal secret and i haven't tried that yet, so idk