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:

computah.config.mjs
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

sandboxwhat it iswhat it needs
exeSandbox()a standalone exe.dev vm per request, cut off from the internet except exe's model gatewayan ssh key exe.dev knows, on the runner's machine
modalSandbox()a modal sandbox per requestthe 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:

javascript
sandbox: { in: exeSandbox(), warm: { max: 3 } },
optiondefault
max2the most sandboxes sitting ready at once
idleMs90 secondsa ready one nobody used for this long gets thrown away
min0keep 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

optiondefault
egress"integrations""integrations" reaches only exe.dev's own services like the model gateway, "all" the whole internet
setuppoints claude code and codex at exe's gatewayshell commands run once in a new sandbox, before the code goes in
sshextra arguments for every ssh call, like ["-i", "/path/to/key"]
prefix"computah-sbx-" and a few characters of this runner's ownthe 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

optiondefault
app"computah"the modal app the sandboxes are created under
image"node:24-bookworm-slim"a registry image to start from
buildinstalls git, claude code, codex and opencodedockerfile lines that put git and your agent on the image
secretsnonenames of modal secrets to give the agent, like one holding ANTHROPIC_API_KEY
blockNetworkfalseno network at all, only useful with an agent that needs none
timeoutMs20 minuteshow long a sandbox can live
javascript
modalSandbox({ secrets: ["anthropic"] });

writing your own

a name and open(), which returns a session with two functions:

typescript
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