Set up a sandbox
A setup is a list of steps the CLI runs in a sandbox right after it starts: install tools, clone a repository, warm a cache. Steps are shell lines or script files, and they work the same on every provider.
beachside create --name web --setup-cmd 'npm i -g pnpm' --setup-cmd 'pnpm --version'beachside create --name web --setup ./setup.shEach step’s output streams to stderr as it runs, under a header such as setup [2/3] ./setup.sh. stdout keeps the usual result, so scripts that read the sandbox name still work. --quiet-setup shows only the step headers and any failure.
Named setups
Section titled “Named setups”Put setups you reuse under setups in beachside.json and pick them with --setup <name>:
{ "setups": { "node": { "setup": ["curl -fsSL https://fnm.vercel.app/install | bash", "fnm install 22"], "network": "internet" }, "web": { "extends": ["node"], "setup": ["./scripts/install-web.sh", { "run": "pnpm install", "cwd": "app" }], "startup": ["pnpm --dir app dev > /tmp/dev.log 2>&1 &"], "env": { "NPM_TOKEN": "op://Dev/npm/token" } } }}beachside create --name web --setup webbeachside create --name api --setup node,./scripts/api.sh --setup-cmd 'make deps'A setup’s steps can be:
- a shell line:
"pnpm install" - an argv array:
["make", "deps"] - a script path starting with
./,../or~/, relative to the file that names it. It is uploaded and run with its shebang (shwhen it has none). - an object with exactly one of
run,script(inline text) orfile, plus any ofname,cwd(created if missing),env,timeout(like90sor10m, default 10m),user: "root"andcache: false. { "parallel": [step, step, ...], "name": "fetch" }: steps that run at the same time, as one step. It finishes when all of them have, and fails once all have finished if any failed. Their output lines are prefixed with the step’s name. Parallel groups are for setup, not startup.
A setup can also say what it needs:
extendslists setups whose steps run first. A setup reached twice runs once.networkbecomes the create’s default network. An explicit--networkthat disagrees is an error, before anything is created.envjoins the sandbox environment, under--env. Values can beenv:NAMEor password-manager references, as in credentials.
--setup takes a comma-separated list and can repeat. Named setups and files run in the order given, then every --setup-cmd. beachside setup ls lists the setups the config defines.
Defaults per profile
Section titled “Defaults per profile”A profile can name setups every sandbox it creates gets first:
{ "profiles": { "e2b": { "provider": "e2b", "setup": ["node"] } }}--no-default-setup skips them for one create. Restores from a snapshot never apply them, since the snapshot already holds its setup.
Setups in the repository
Section titled “Setups in the repository”A repository can carry its own setups in .beachside/setup.json, beside the code they prepare:
{ "setups": { "app": { "setup": ["./scripts/install-system-deps.sh", { "run": "npm ci", "cwd": "~/work" }], "cache": { "files": ["./package-lock.json"] } } }, "default": ["app"]}The CLI reads it only when "projectSetups": true is in beachside.json or BEACHSIDE_PROJECT_SETUPS=1 is set, because a checkout you didn’t write could otherwise choose what runs. It looks in the working folder and its parents, up to the repository root. Script and cache.files paths are relative to the folder that holds .beachside/. A project setup cannot reuse a name from beachside.json. default setups run on every create from the checkout, after the profile’s, unless --no-default-setup.
Startup steps
Section titled “Startup steps”Setup runs once. Startup steps run each time the sandbox comes up without its processes: at create, after create --snapshot, and after a resume that started fresh. Use them for servers and daemons that a snapshot does not keep running.
beachside create --name web --setup web --startup-cmd 'redis-server --daemonize yes'beachside create --name web --startup ./start.shThe sandbox records its startup steps, so a restore runs them again without being told. A restore that passes its own --startup or --startup-cmd runs those instead.
When a step fails
Section titled “When a step fails”A failed step stops setup. The CLI exits with code 9 and says which step failed, with the end of its output:
beachside: web: setup step 2/3 "pnpm install" failed (exit 1):ERR_PNPM_FETCH_404 GET https://registry.npmjs.org/@acme%2Fmissing: Not Foundhint: look around with `beachside sh web '...'`, rerun the missing steps with `beachside setup web`, or remove it with `beachside rm web`create keeps the sandbox so you can look around, and records its setup as failed. With --json, error.known.sandbox names it. Pass --rm-on-failure to remove it instead. run always removes its sandbox unless --keep, and exits 125 like any other CLI-side failure.
Every step has a 10 minute limit, and setup plus startup have 30 minutes together. Change them with a step’s timeout and with --setup-timeout 45m.
Run setup again
Section titled “Run setup again”beachside setup <sandbox> runs what the sandbox recorded. Steps that already finished are skipped, so after a failure it continues from the failed step:
beachside setup web # finish what failedbeachside setup web --force # run every step againbeachside setup web --setup playwright --setup-cmd 'npx playwright install'Flags add to what the sandbox already has. A setup whose env the sandbox was created without gets it for its steps.
The sandbox keeps its setup state in ~/.beachside/setup/ inside the sandbox, so it travels with snapshots. The CLI’s store keeps the setup names, the digest and each step’s outcome, never script contents; beachside inspect shows them.
In run and CI
Section titled “In run and CI”run takes the same flags. Setup runs after --push, in the pushed folder, so a lockfile is there:
beachside run --push . --setup-cmd 'npm ci' -- npm testCache a setup
Section titled “Cache a setup”A slow setup can be cached. Beachside then snapshots the sandbox right after setup, and the next create with the same setup restores that snapshot instead of running it again:
{ "setups": { "deps": { "setup": ["./install-system-deps.sh", { "run": "git pull", "cwd": "app", "cache": false }], "startup": ["redis-server --daemonize yes"], "cache": { "maxAge": "7d", "files": ["./package-lock.json"] } } }}$ beachside create --name one --setup depsbeachside: setup deps: building the cache...beachside: setup deps: cache saved as cache-3f9c… in 6s (setup took 3m12s)
$ beachside create --name two --setup depsbeachside: setup deps: cache hit (restored in 4s; built 2m ago in 3m12s)--cache caches any create’s setup, --no-cache skips the cache for one create, and --refresh-cache builds it again now.
- The key covers the provider, account and profile, the image, every step (text, scripts, working folder, user and env names) and the content of each file in
files. A change to any of them is a new cache. Env values are not part of it. - When the snapshot is taken: after setup, before startup,
--withservers and anything else the command does, so the cache never holds startup’s processes or tailnet logins. Where snapshots keep memory (boxd), anything a setup step left running in the background is restored with the cache. On a hit, steps marked"cache": falserun again, then startup. - Age: after
maxAge(7 days by default) a cache is stale. The next create rebuilds it and deletes the old snapshot once the new one exists. Nothing is deleted on a timer. - Two creates at once: the first to miss builds the cache. The other runs setup without it rather than wait.
- Where it is kept: a cache is a snapshot record named
cache-<key>in the state folder, sosnapshot lsandsnapshot inspectshow it too. On providers that label snapshots, the snapshot also carries abeachside.setup-cachelabel, and a runner with an empty state folder finds it there.
beachside setup cache ls lists the caches with their age and build time. setup cache rm <setup> deletes one setup’s caches, and setup cache prune deletes the stale ones (--dry-run shows what would go). gc prunes stale caches too. rm never deletes a cache, because it belongs to the cache, not the sandbox.
Caching needs snapshot capture and restore, plus restore-time support for any --env, --label or --ttl you pass. Where a provider lacks them, the create fails before anything is made. A provider that can only judge capture on a real sandbox, such as Daytona, is checked again after setup; if it refuses there, the create finishes and says the cache was not saved. It never runs uncached without saying so.
Caching pays when setup takes more than about 30 seconds and the provider restores faster than it creates and sets up. The timing lines show both.
In run --push, setup runs in the pushed folder, so the cache holds that folder as it was when the cache was built. A hit pushes the current files over it; files deleted since then can remain until the cache is rebuilt.
What each step sees
Section titled “What each step sees”Steps run through the provider’s exec, as the sandbox’s default user, from its home folder unless cwd says otherwise. user: "root" runs a step with sudo -n -E where the default user is not root. Each step gets the sandbox’s environment plus its own env; secrets belong in the sandbox env (--env or a setup’s env), not in a step’s text.
Beachside records a digest of each step’s command, working folder, user and env names, never env values. Two creates with the same steps get the same digest, so a rotated token does not count as a different setup.
© 2026 Beachside Compute