UN

NAME

un − execute code in secure sandboxed containers

SYNOPSIS

un [OPTIONS] source_file
un session [OPTIONS]
un service command [OPTIONS]
un key [OPTIONS]
un snapshot command [OPTIONS]

DESCRIPTION

un executes code in 42+ programming languages via the unsandbox.com API. Code runs in isolated LXD containers with configurable network access and resource limits.

The tool supports three modes of operation:
Code Execution

Run source files directly. Language is auto-detected from file extension or shebang.

Interactive Sessions

Open shell or REPL sessions with optional persistence via tmux/screen.

Services

Manage long-lived containers with exposed ports for running applications.

Key Management

Validate API keys and extend their expiration via the web portal.

Snapshots

Create, list, restore, and delete point-in-time snapshots of sessions and services.

OPTIONS

General Options

−e KEY=VALUE

Set environment variable. Can be used multiple times.

−f FILE

Add input file to /tmp/ in the sandbox. Works with code execution, sessions, and services. Can be used multiple times.

−n MODE

Network mode: zerotrust (default, isolated) or semitrusted (internet access).

Session Options

−s, −−shell SHELL

Shell or REPL to use (default: bash).

−l, −−list

List active sessions.

−−attach ID

Reconnect to existing session by ID or container name.

−−kill ID

Terminate a session by ID or container name.

−−audit

Record session for auditing. Saves terminal output to artifacts.

−−screen

Enable session persistence with screen. Allows disconnect and reconnect.

Service Options

−−name NAME

Service name (creates a new service when provided).

−−ports PORTS

Comma-separated ports to expose (e.g., 80,443).

−−bootstrap CMD

Bootstrap command or URI to run on startup.

−−bootstrap−file FILE

Upload local file as bootstrap script content. The file is read and sent as bootstrap_content in the API request.

−l, −−list

List all services.

−−info ID

Get service details.

−−logs ID

Get bootstrap logs.

−−sleep ID

Freeze a service (pause execution, preserve state).

−−wake ID

Unfreeze a service.

−−destroy ID

Destroy a service permanently.

−−redeploy ID

Re-run bootstrap script (requires −−bootstrap).

−−execute ID CMD

Run a command in a running service.

−−dump−bootstrap ID [FILE]

Dump bootstrap script from service (useful for migrations). If FILE is provided, saves to file and makes executable. Otherwise prints to stdout.

Service Environment Vault

Encrypted storage for service secrets. Variables are injected at container wake time.
env status ID

Show vault status (exists, variable count, last updated).

env set ID [−e KEY=VALUE...] [−−env−file FILE]

Set vault contents. Accepts −e flags, −−env−file, or stdin (one KEY=VALUE per line).

env export ID

Export decrypted vault contents to stdout in .env format.

env delete ID

Delete the vault. Takes effect on next container start/wake.

Key Options

(no options)

Validate API key and display status, tier, rate limits, and expiration.

−−extend

Open browser to extend API key expiration. Uses the key’s public portion to allow anyone to gift time.

Snapshot Options

−l, −−list

List all snapshots.

−−info ID

Get snapshot details.

−−delete ID

Delete a snapshot permanently.

−−name NAME

User-friendly name when creating a snapshot.

Session Snapshot Options

−−snapshot ID

Create a snapshot of a session.

−−restore SNAPSHOT_ID

Restore a session from a snapshot.

Service Snapshot Options

−−snapshot ID

Create a snapshot of a service.

−−restore SNAPSHOT_ID

Restore a service from a snapshot.

SHELLS AND REPLS

Available Shells

bash, dash, sh, zsh, fish, ksh, tcsh, csh, elvish, xonsh, ash

Available REPLs

python3, bpython, ipython, node, ruby, irb, lua, php, perl, guile, ghci, erl, iex, sbcl, clisp, r, julia, clojure

SESSION BEHAVIOR

Default (no multiplexer)

Session terminates immediately on disconnect. Clean exit, container released.

With −−tmux or −−screen

Session persists on disconnect. Reconnect anytime with −−attach.

MULTIPLEXER SHORTCUTS

tmux

Ctrl+b d

Detach (disconnect, keep session alive)

Ctrl+b c

Create new window

Ctrl+b n/p

Next/previous window

Ctrl+b 0-9

Switch to window by number

Ctrl+b %

Split pane vertically

Ctrl+b o

Switch between panes

screen

Ctrl+a d

Detach (disconnect, keep session alive)

Ctrl+a c

Create new window

Ctrl+a n/p

Next/previous window

Ctrl+a 0-9

Switch to window by number

Ctrl+a S

Split horizontally

Ctrl+a |

Split vertically

Ctrl+a Tab

Switch between regions

SUPPORTED LANGUAGES

Interpreted: python, javascript, typescript, ruby, perl, php, lua, bash, r, elixir, erlang, tcl, scheme, powershell, clojure, commonlisp, crystal, groovy, deno, awk, raku

Compiled: c, cpp, go, rust, java, kotlin, cobol, fortran, d, zig, nim, v, objc, dart, julia, haskell, ocaml, fsharp, csharp, prolog, forth

Aliases: js/node → javascript, ts → typescript, lisp → commonlisp

RESOURCE LIMITS

Processes

500 per container

I/O Rate (interactive sessions only)

Interactive sessions via streaming API or CLI are terminated if stdin/stdout exceeds rate limits (prevents runaway processes).

AUTHENTICATION

Credentials are loaded in order of priority (highest first):
1. CLI flags

−p (public key) and −k (secret key)

2. Environment variables

UNSANDBOX_PUBLIC_KEY and UNSANDBOX_SECRET_KEY

3. Config file

˜/.unsandbox/accounts.csv (format: public_key,secret_key per line)

Request Authentication:

Each request includes three authentication headers:
Authorization: Bearer <public_key>

The public key (unsb-pk-xxxx-xxxx-xxxx-xxxx). Identifies the account.

X-Timestamp: <unix_seconds>

Current Unix timestamp. Must be within ±5 minutes of server time (prevents replay attacks).

X-Signature: <signature>

HMAC-SHA256(secret_key, timestamp:method:path:body) in lowercase hex. Proves possession of secret key and prevents body tampering.

The secret key is NEVER transmitted. The server decrypts the stored encrypted secret to verify the HMAC signature. The raw request body is included in the signature to prevent tampering (empty string for bodyless requests like GET/DELETE).

ENVIRONMENT

UNSANDBOX_PUBLIC_KEY

Public key for authentication.

UNSANDBOX_SECRET_KEY

Secret key for authentication.

EXAMPLES

Code Execution

# Execute Python script
un script.py

# With environment variable
un -e DEBUG=1 script.py

# With input file
un -f data.csv process.py

# Save compiled artifacts
un -a -o ./bin main.c

# With network access
un -n semitrusted fetch.py

Interactive Sessions

# Start bash session (terminates on disconnect)
un session

# Bash with tmux (can reconnect)
un session --tmux

# Python REPL with screen
un session --shell python3 --screen

# List active sessions
un session --list

# Reconnect to session
un session --attach unsb-vm-12345

# Terminate session
un session --kill unsb-vm-12345

# Audited session (records output)
un session --audit -o ./logs

# Session with input file in /tmp/
un session -f data.csv

Services

# Create web service
un service --name web --ports 80,443 \
--bootstrap "python -m http.server 80"

# Create service with bootstrap script from file
un service --name app --ports 8000 \
--bootstrap-file ./setup.sh

# Deploy app tarball with bootstrap script
# setup.sh: cd /tmp && tar xzf app.tar.gz && ./app/start.sh
un service --name app --ports 8000 \
-f app.tar.gz --bootstrap-file ./setup.sh

# List services
un service --list

# Get service info/logs
un service --info abc123
un service --logs abc123

# Freeze/unfreeze
un service --freeze abc123
un service --unfreeze abc123

# Destroy
un service --destroy abc123

# Redeploy with updated bootstrap
un service --redeploy abc123 --bootstrap ./setup.sh

# Execute command in service
un service --execute abc123 ’journalctl -u myapp -n 50’

# Dump bootstrap script for migrations
un service --dump-bootstrap abc123
un service --dump-bootstrap abc123 backup.sh

Environment Vault

# Check if vault exists
un service env status myapp

# Set secrets from flags
un service env set myapp -e API_KEY=secret -e DB_PASS=hunter2

# Set secrets from .env file
un service env set myapp --env-file production.env

# Set secrets from stdin
cat secrets.env | un service env set myapp

# Export vault to .env format
un service env export myapp > backup.env

# Delete vault
un service env delete myapp

Key Management

# Check API key status
un key

# Extend key expiration (opens browser)
un key --extend

Snapshots

# List all snapshots
un snapshot --list

# Get snapshot info
un snapshot --info unsb-snapshot-xxxx-xxxx-xxxx-xxxx

# Create session snapshot
un session --snapshot unsb-vm-12345 --name "before upgrade"

# Create service snapshot (pauses container briefly)
un service --snapshot unsb-service-abc123 --name "stable v1.0"

# Create hot snapshot (no pause, may be inconsistent)
un service --snapshot unsb-service-abc123 --hot

# Restore session from snapshot
un session --restore unsb-snapshot-xxxx-xxxx-xxxx-xxxx

# Restore service from snapshot
un service --restore unsb-snapshot-xxxx-xxxx-xxxx-xxxx

# Delete a snapshot
un snapshot --delete unsb-snapshot-xxxx-xxxx-xxxx-xxxx

EXIT STATUS

FILES

˜/.unsandbox/accounts.csv

Credentials file. Format: public_key,secret_key (one account per line).

/tmp/artifacts/

Default location for artifacts within containers.

SEE ALSO

tmux(1), screen(1), ssh(1)

AUTHOR

unsandbox@unturf.com

COPYRIGHT

Copyright © 2025 unturf.com. All rights reserved.