Sandbox Testing

Ignition includes a sandbox script that spins up an ephemeral microVM for safe recipe testing. No real server needed.

What sandboxes are

Sandboxes are short-lived Linux VMs provided by Deno Deploy. They come pre-configured with SSH access and are automatically destroyed after a timeout. This lets you test recipes against a disposable machine without risking your production servers.

Prerequisites

Set the DENO_DEPLOY_TOKEN environment variable. You can put it in a .env file in the project root:

DENO_DEPLOY_TOKEN=your-token-here

Basic usage

Start a sandbox with a default 10-minute lifetime:

bun run sandbox

The script prints connection details:

═══ Sandbox ready ═══
  hostname: sandbox-host.example.com
  username: sandbox-user
  ssh:      ssh -o StrictHostKeyChecking=no sandbox-user@sandbox-host.example.com
  target:   sandbox-user@sandbox-host.example.com

═══ Ignition commands ═══
  # Dry-run
  bun run dev run --check examples/smoke-test.ts sandbox-user@sandbox-host.example.com --host-key-policy off

  # Apply
  bun run dev run examples/smoke-test.ts sandbox-user@sandbox-host.example.com --host-key-policy off

Custom timeout

Specify a custom lifetime:

bun run sandbox 15m    # 15 minutes
bun run sandbox 30m    # 30 minutes

Auto-run a recipe

Run a recipe against the sandbox automatically, then keep the sandbox alive for further use:

bun run sandbox 5m -- examples/smoke-test.ts

This starts the sandbox, runs the specified recipe, then drops you back to the interactive prompt where you can run more commands.

Workflow

A typical sandbox workflow:

# 1. Start a sandbox
bun run sandbox 15m

# 2. In another terminal, run your recipe
ignition run --check my-recipe.ts sandbox-user@sandbox-host.example.com --host-key-policy off
ignition run my-recipe.ts sandbox-user@sandbox-host.example.com --host-key-policy off

# 3. Iterate — edit recipe, re-run
ignition run my-recipe.ts sandbox-user@sandbox-host.example.com --host-key-policy off

# 4. When done, Ctrl+C in the sandbox terminal to tear it down

Safe examples

Three example recipes are designed to be safe on any server:

# Quick connectivity check
bun run sandbox 5m -- examples/smoke-test.ts

# Read-only system info
bun run sandbox 5m -- examples/system-info.ts

# File/directory roundtrip with cleanup
bun run sandbox 5m -- examples/file-roundtrip.ts