UN

NAME

un − execute code in secure sandboxed containers

SYNOPSIS

un [OPTIONS] source_file
un session [OPTIONS]
un service command [OPTIONS]
un key [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.

OPTIONS

General Options

−e KEY=VALUE

Set environment variable. Can be used multiple times.

−f FILE

Add input file to the sandbox. 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, file path, or URL to run on startup.

−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.

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.

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

Services

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

# 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

Key Management

# Check API key status
un key

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

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.