@depot/sandbox

Beta TypeScript SDK for Depot sandboxes.

This package wraps the depot.sandbox.v1 API with Vercel-shaped classes for creating sandboxes, running commands, streaming command output, and using a node:fs/promises-shaped filesystem interface.

Installation

After the beta package is published:

pnpm add @depot/sandbox

Usage

Set DEPOT_TOKEN in your environment, then create a client and pass it to the static sandbox entry points. Returned sandbox instances keep that client, so instance methods do not take a client argument.

import {createClient, Sandbox} from '@depot/sandbox'

const client = createClient({token: process.env.DEPOT_TOKEN!})
const sandbox = await Sandbox.create(client, {
  env: {NODE_ENV: 'development'},
})

const command = await sandbox.runCommand({cmd: 'echo', args: ['hello from depot']})
const finished = await command.wait()

console.log(finished.exitCode)
console.log(await command.stdout())

const fs = sandbox.fs()
await fs.writeFile('/tmp/message.txt', 'hello')
console.log(await fs.readFile('/tmp/message.txt', {encoding: 'utf8'}))

await sandbox.setTimeout({timeoutMinutes: 240})
await sandbox.stop({blocking: true})

You can also pass token, organization, and endpoint options explicitly:

const client = createClient({
  token: process.env.DEPOT_TOKEN!,
  orgID: process.env.DEPOT_ORG_ID,
})

CI secrets

Pass configuration.secrets to expose your organization's CI secrets to every command in the sandbox. Each key is the environment variable to set, and each value is the name of a CI secret. environment and repository choose which variant of each secret applies, the same way a CI workflow would.

const sandbox = await Sandbox.create(client, {
  configuration: {
    secrets: {DATABASE_URL: 'PROD_DATABASE_URL'},
    environment: 'production',
    repository: 'acme/app',
  },
})

await sandbox.runCommand({cmd: 'sh', args: ['-c', 'psql "$DATABASE_URL" -c "select 1"']})

• Unknown or inapplicable name: Sandbox.create fails with InvalidArgument when a secret doesn't exist, or has no variant for the given environment and repository.
• Scoped variants: setting environment or repository requires an organization owner or an organization token; otherwise Sandbox.create fails with PermissionDenied. The same applies to runCommand and file system calls on that sandbox.
• Deleted secret: each command reads the secret's current value when it starts, so a rotated value applies to the next command. If the secret was deleted after the sandbox was created, the command fails with FailedPrecondition. Create a new sandbox to recover.
• Output is not masked: a command that prints the variable streams its value back to you.

Beta Surface

This beta package currently includes:

• createClient
• Sandbox.create (including CI secrets), Sandbox.get, Sandbox.list, Sandbox.listAll
• sandbox.stop, sandbox.kill, sandbox.setTimeout, sandbox.runCommand, sandbox.fs
• SandboxCommandExecution.wait, logs, output, stdout, and stderr
• FileSystem helpers for common file operations
• sandbox.tailnet: status() and waitForAddress(), which report the sandbox's live MagicDNS name and IPs on your organization's tailnet; opt out with disableTailnet on create

Other sandbox capabilities, such as piped stdin, command history, snapshots, and pty support, are not part of this beta surface yet.

Generated Protos

In this repository, the depot.sandbox.v1 proto sources are vendored in proto/, and the generated TypeScript files are checked in under src/gen. The published package ships the compiled generated bindings so customers do not need a separate proto module.

After changing a proto, regenerate the TypeScript bindings:

pnpm run gen

CI runs pnpm run gen:check through pnpm run validate to catch drift between proto/ and src/gen.

Releasing

Releases are published from GitHub releases through npm trusted publishing. No npm token is required for the normal publish workflow.

To publish a new version:

1. Update package.json to the next version or semver channel.
2. Merge the change to main.
3. Review the draft release generated by release-drafter and edit the release notes.
4. Publish the GitHub release with label None and tag v<release-version>.

Release Drafter starts from the committed package.json version. If that version is already represented by an unreleased draft, it keeps updating the draft. If that version is already published or tagged, it advances to the next numeric prerelease version in the same semver channel, such as 0.1.0-beta.1 to 0.1.0-beta.2. To switch channels, merge a package.json version that selects the new channel, such as 0.1.0-alpha.1, 0.1.0-rc.1, or 0.1.0.

Semver prerelease identifiers are package version channels only. They do not make the GitHub release a pre-release, and every npm publish updates the latest dist-tag.

The release.yml workflow sets package.json from the GitHub release tag, validates the package, and publishes the new @depot/sandbox version to npm as latest.

npm trusted publishing must be configured for the depot/sandbox-sdk repository and .github/workflows/release.yml workflow. The first CI publish from this repo should update npm registry metadata that still points at the earlier manual sdk-node publish.

If a GitHub release is published but the npm publish workflow fails before the package version reaches npm, the release tag is consumed but there is no npm package version to repair. First rerun the failed release workflow from GitHub Actions. If rerunning cannot recover it, delete the GitHub release and tag, then let Release Drafter create a new draft from the next main run.

If a published version has incorrect release metadata or npm dist-tags, prefer fixing forward by bumping package.json to the next version and publishing a new release. Avoid adding one-off metadata repair automation to the repo.

License

MIT License, see LICENSE.