On this page
Management via CLI
The Deno CLI includes built-in commands for managing sandboxes, allowing you to create, control, and interact with them from your terminal.
This integration makes sandbox management feel natural within your existing Deno workflow.
Creating Your First Sandbox Jump to heading
The simplest way to get started is with deno sandbox create. By default, this
creates an interactive session-based sandbox that automatically opens an SSH
connection when ready:
deno sandbox create
If SSH isn't available on your system, it will display connection information instead. The sandbox cleans itself up when you exit the session.
For development work, you'll often want to copy your project files into the
sandbox. The --copy option uploads files to the /app directory inside the
sandbox:
deno sandbox create --copy ./my-project
You can copy multiple directories during creation:
deno sandbox create --copy ./src --copy ./config
If you need the sandbox to run longer than a single session, specify a lifetime
with --lifetime:
deno sandbox create --lifetime 2m
Viewing Your Sandboxes Jump to heading
Use deno sandbox list (or deno sandbox ls) to see all sandboxes in your
organization:
$ deno sandbox list
ID CREATED STATUS UPTIME
550e8400-e29b-41d4-a716-446655440000 2024-01-15 10:30:00.00 running 5m
6ba7b810-9dad-11d1-80b4-00c04fd430c8 2024-01-15 09:45:00.00 stopped 15m
This shows each sandbox's unique ID (which you'll use with other commands), when it was created, whether it's currently running, and how long it's been active. The sandbox ID is a UUID that uniquely identifies each instance.
Running Commands Remotely Jump to heading
The deno sandbox exec command lets you run individual commands in any running
sandbox without opening an interactive session. This is perfect for automation,
CI/CD pipelines, or quick one-off tasks:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 ls -la
Most of the time, you'll want to work in the /app directory where your copied
files live. Use --cwd to set the working directory:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --cwd /app npm install
For scripting or automation, use --quiet to suppress command output:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --quiet --cwd /app npm test
You can also run complex command chains by quoting the entire command:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --cwd /app "npm install && npm test"
The exec command works naturally with Unix pipes and standard input/output. You can pipe the output of sandbox commands to local tools:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 'ls -lh /' | wc -l
Or pipe local data into sandbox processes for processing:
cat large-dataset.csv | deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --cwd /app "deno run -A main.ts"
This makes it easy to integrate sandbox processing into larger Unix workflows and data pipelines.
Transferring Files Jump to heading
While you can copy files during sandbox creation, you might need to update or
retrieve files later. The deno sandbox copy command (also available as
deno sandbox cp) transfers files in any direction: from your local machine to
sandboxes, from sandboxes back to your machine, or even between different
sandboxes.
Copy files from your local machine to a sandbox:
deno sandbox copy ./app.js 550e8400-e29b-41d4-a716-446655440000:/app/
Retrieve files from a sandbox to your local machine:
deno sandbox copy 550e8400-e29b-41d4-a716-446655440000:/app/results.json ./output/
Copy files between different sandboxes:
deno sandbox copy 550e8400-e29b-41d4-a716-446655440000:/app/data.csv 6ba7b810-9dad-11d1-80b4-00c04fd430c8:/app/input/
You can use glob patterns to copy multiple files from sandboxes:
deno sandbox copy 550e8400-e29b-41d4-a716-446655440000:/app/*.json ./config/
deno sandbox copy 550e8400-e29b-41d4-a716-446655440000:/app/logs/*.log ./logs/
You can copy multiple files and directories at once:
deno sandbox copy ./src/ ./package.json 550e8400-e29b-41d4-a716-446655440000:/app/
The target path can be customized to organize files within the sandbox:
deno sandbox copy ./frontend 550e8400-e29b-41d4-a716-446655440000:/app/web/
One-Shot Execution Jump to heading
For quick tasks where you want to create a sandbox, run a command, and clean up
automatically, use deno sandbox run. This combines sandbox creation and
command execution into a single step:
deno sandbox run ls /
This is especially useful for building and testing projects. You can copy files and run your build process in one command:
deno sandbox run --copy ./app --cwd /app "npm i && npm start"
For web applications, you can expose ports to access running services:
deno sandbox run --expose-http 3000 --copy ./web-app --cwd /app "npm i && npm run dev"
When working with tasks that take significant time, specify a lifetime to prevent premature shutdown:
deno sandbox run --lifetime 2m --copy ./project --cwd /app "deno run -A main.ts"
Complex workflows can be expressed as quoted command chains:
deno sandbox run --copy ./app --cwd /app "npm install && npm test && npm run build"
Interactive Access Jump to heading
When you need to work interactively within a sandbox; be it editing files,
debugging issues, or exploring the environment, you can use deno sandbox ssh:
deno sandbox ssh 550e8400-e29b-41d4-a716-446655440000
This gives you a full Linux shell inside the sandbox where you can use any command-line tools, edit files with vim or nano, monitor processes, or install additional software as needed. The sandbox continues running after you disconnect, so you can reconnect later or use other commands to interact with it remotely.
Managing Sandbox Lifetime Jump to heading
Extending Sandbox Duration Jump to heading
Sometimes you'll need more time to complete your work in a running sandbox. The
deno sandbox extend command allows you to extend the lifetime of any running
sandbox without interrupting ongoing processes:
deno sandbox extend 550e8400-e29b-41d4-a716-446655440000 30m
The extend command works seamlessly with any sandbox state; whether you're SSH'd into it, running remote commands, or have background processes running. All active connections and processes continue uninterrupted while the sandbox's expiration time is updated.
Cleanup and Termination Jump to heading
When you're finished with a sandbox, use deno sandbox kill (or
deno sandbox rm) to terminate it and free up resources:
deno sandbox kill 550e8400-e29b-41d4-a716-446655440000
This immediately stops all processes in the sandbox and releases its resources. Be sure to save any important work before terminating a sandbox, as all data inside will be lost.
Common Workflows Jump to heading
Development and Testing Jump to heading
A typical development workflow involves creating a sandbox with your code, setting up dependencies, and running tests:
deno sandbox create --copy ./my-app
Once created, use the returned sandbox ID to set up and test your project:
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --cwd /app npm install
deno sandbox exec 550e8400-e29b-41d4-a716-446655440000 --cwd /app npm test
As you make changes locally, you can update the sandbox, and retrieve any generated files when done:
deno sandbox copy ./src/ 550e8400-e29b-41d4-a716-446655440000:/app/src/
deno sandbox copy 550e8400-e29b-41d4-a716-446655440000:/app/build/ ./dist/
deno sandbox kill 550e8400-e29b-41d4-a716-446655440000
Data Processing Jump to heading
For data processing workflows where you need to retrieve results, use a combination of remote execution and SSH access:
SANDBOX_ID=$(deno sandbox create --lifetime 20m --copy ./data)
deno sandbox exec $SANDBOX_ID --cwd /app "deno run -A main.ts"
You can also stream data directly into sandbox processes using pipes, which is particularly useful for large datasets or real-time processing:
SANDBOX_ID=$(deno sandbox create --lifetime 20m --copy ./processing-scripts)
curl -s https://api.example.com/data.json | deno sandbox exec $SANDBOX_ID --cwd /app jq '.items[] | select(.active)'
Or combine local and remote processing in a pipeline:
grep "ERROR" /var/log/app.log | deno sandbox exec $SANDBOX_ID --cwd /app "deno run -A main.ts" | sort | uniq -c
To retrieve results, copy the generated files back to your local machine, then clean up:
deno sandbox copy $SANDBOX_ID:/app/results/*.csv ./output/
deno sandbox kill $SANDBOX_ID