Manage devcontainer-style sandboxes on docker, podman, or Apple container: many throwaway instances per repo from one devsandboxes.toml. This package ships the native devsandbox binary (Linux x64/arm64, macOS arm64, Windows x64) plus a typed Node API.
The package installs a devsandbox command (npm i -g devsandboxes); npx devsandboxes runs it without installing.
rm(name, { deleteBranch, force }) / rename(a, b) / done(name) / undone(name) / gc() / service.rebuild(name)
void
logs(name, { lines })
log text
Every function takes { dir, cwd, env, signal, stderr }, except the synchronous binaryPath() and execArgv(), and connect() (below). dir is the config root (-C). A failed command rejects with DevsandboxError (exitCode, stdout, stderr).
rm never prompts: deleteBranch: true deletes the worktree branch run created (git branch -D, unmerged commits too); false or omitted keeps it. Branches run reused are always kept. It rejects, removing nothing, when the worktree has uncommitted or untracked changes, unless force: true: that discards them, and a step that fails is skipped with a warning on stderr so the instance is still removed.
Daemon API
connect() talks to the per-user host daemon (the one the dashboard uses) through devsandbox api --stdio, starting it if needed: the Inbox, instances and port forwards, with change notifications. Unix only; on Windows it rejects with code unsupported.
A thread is { thread: id } or { owner, key }. Failures reject with DevsandboxApiError (code: the daemon's not-found, invalid, denied, bind-failed, …, or closed once the connection ended). The connection emits each notification by name (inbox.changed, instances.changed, forwards.changed, closing, …) and close when the relay exits; there's no automatic reconnect, connect() again. Ad-hoc forwards outlive the connection (and keep the daemon running) until forwards.rm. The verbs go through call: call('run', { root, env, sandbox, detach: true }) (an absolute root, and an env, typically process.env); a verb holds the connection until it answers, streaming output and progress events, and a failed rejection carries the exit in error.data. Protocol reference: docs/reference/api.md in the repository.
Platforms
The binary comes from an optional dependency (@devsandboxes/<platform>-<arch>), so don't install with --omit=optional. On other platforms, cargo install devsandbox and point DEVSANDBOX_BINARY at the result.