Lua Documentación de la API

Descargar

# Linux x86_64
wget https://unsandbox.com/downloads/un
chmod +x un

# Move to PATH (optional)
sudo mv un /usr/local/bin/

Compilar desde el código fuente

# Requirements: GCC, libcurl, libwebsockets
sudo apt-get install build-essential libcurl4-openssl-dev libwebsockets-dev

# Compile
wget https://unsandbox.com/downloads/un.c
gcc -Wall -O2 -o un un.c -lcurl -lwebsockets

Bibliotecas SDK (un-inception)

Para lenguajes que necesitan acceso programático, usa nuestras implementaciones SDK:

# Python - download un.py
wget https://unsandbox.com/cli/inception/un.py
python un.py script.py

# JavaScript - download un.js
wget https://unsandbox.com/cli/inception/un.js
node un.js script.py

# Go - download un.go
wget https://unsandbox.com/cli/inception/un.go
go run un.go script.py

Ver los 42 SDKs de lenguajes →

Todas las solicitudes a la API requieren autenticación con firma HMAC-SHA256 por seguridad.

Encabezados requeridos

Formato de firma

HMAC-SHA256(secret_key, timestamp:METHOD:path:body)

Ejemplo de cadena de firma:

1699564800:POST:/execute:{"language":"python","code":"print('hi')"}

Tu clave secreta nunca se transmite. El servidor verifica las firmas usando tu clave cifrada.

Ejecuta cualquier archivo de código. El lenguaje se auto-detecta desde la extensión del archivo o shebang.

Uso Básico

# Python
un hello.py

# JavaScript
un app.js

# Rust (compiles and runs)
un main.rs

# C (compiles and runs)
un program.c

# Go
un main.go

Con Opciones

# Extended timeout (5 minutes)
un --ttl 300 long_script.py

# With more CPU/RAM (4 vCPUs, 8GB RAM)
un -v 4 heavy_compute.py

# Maximum resources (8 vCPUs, 16GB RAM)
un --vcpu 8 ml_training.py

Respuesta

La salida fluye directamente a tu terminal:

$ un hello.py
Hello from unsandbox!

$ echo $?
0

Equivalente API

POST /execute

{
  "success": true,
  "stdout": "Hello from unsandbox!\n",
  "stderr": "",
  "exit_code": 0,
  "language": "python",
  "total_time_ms": 127
}

Ejecuta fragmentos de código directamente desde la línea de comandos usando la flag -s.

Uso Básico

# Python
un -s python 'print("Hello World")'

# Bash
un -s bash 'echo "Hello" && date'

# JavaScript
un -s javascript 'console.log(Math.PI)'

# Ruby
un -s ruby 'puts 2 ** 100'

# Go (full program)
un -s go 'package main; import "fmt"; func main() { fmt.Println("Hi") }'

Código Multilínea

# Using heredoc
un -s python <<'EOF'
import json
data = {"name": "unsandbox", "version": 2}
print(json.dumps(data, indent=2))
EOF

Lenguajes Soportados

Cualquiera de los 42 lenguajes soportados funciona con -s:

un -s python 'print(42)'
un -s javascript 'console.log(42)'
un -s typescript 'console.log(42 as number)'
un -s ruby 'puts 42'
un -s php '<?php echo 42;'
un -s perl 'print 42'
un -s lua 'print(42)'
un -s rust 'fn main() { println!("42"); }'
un -s c 'int main() { printf("42"); return 0; }'
un -s cpp 'int main() { std::cout << 42; }'
un -s java 'class M { public static void main(String[] a) { System.out.println(42); }}'
un -s kotlin 'fun main() = println(42)'
un -s go 'package main; import "fmt"; func main() { fmt.Println(42) }'
un -s haskell 'main = print 42'
un -s elixir 'IO.puts 42'
un -s julia 'println(42)'
un -s r 'print(42)'

Pasa variables de entorno a tu código usando la flag -e.

Variable Única

un -e DEBUG=1 script.py
un -e API_KEY=secret app.js

Múltiples Variables

un -e DEBUG=1 -e NAME=World -e COUNT=42 script.py

Con Código en Línea

un -e NAME=Claude -s python 'import os; print(f"Hello {os.environ[\"NAME\"]}")'

un -e X=10 -e Y=20 -s bash 'echo "Sum: $((X + Y))"'

Ejemplo

# config_demo.py
import os

debug = os.environ.get('DEBUG', '0')
name = os.environ.get('NAME', 'World')

if debug == '1':
    print(f"Debug mode enabled")
print(f"Hello {name}!")

Ejecútalo

$ un -e DEBUG=1 -e NAME=unsandbox config_demo.py
Debug mode enabled
Hello unsandbox!

Teletransporta archivos al sandbox. CLI usa el flag -f; la API usa el arreglo input_files.

Uso CLI

# Single file
un -f data.csv process.py

# Multiple files
un -f data.csv -f config.json -f image.png script.py

# Large files (skip confirmation)
un -f large_dataset.parquet -y ml_training.py

Límites

• Máximo de archivos
• Tamaño total máximo
• Tamaño máximo de archivo individual

Teletransporta archivos fuera del sandbox. Usa -a para recopilar artefactos de /tmp/artifacts/ u obtener binarios compilados.

Recopilar Archivos Generados

# Files in /tmp/artifacts/ are collected
un -a -o ./outputs script.py

Binario precompilado

# Compile C and get the binary
un -a -o ./bin main.c

# Compile Rust and get the binary
un -a -o ./bin main.rs

# Compile Go and get the binary
un -a -o ./bin main.go

Compilación WebAssembly

# Compile to WASM (supported languages)
un --wasm -o ./wasm main.c
un --wasm -o ./wasm main.rs

Ejemplo: Generar y Recopilar

# generate_report.py
import json
import os

os.makedirs('/tmp/artifacts', exist_ok=True)

data = {"users": 100, "revenue": 50000}
with open('/tmp/artifacts/report.json', 'w') as f:
    json.dump(data, f, indent=2)

print("Report generated!")

Ejecútalo

$ un -a -o ./reports generate_report.py
Report generated!

$ ls ./reports
report.json

Confianza Cero (predeterminado)

Aislamiento de red completo. Sin acceso a internet.

# Default - no network
un script.py

Semi-Confiable

Acceso a internet vía proxy de salida.

# Enable network access
un -n semitrusted script.py

# Or with sessions
un session -n semitrusted

Casos de Uso

# Zero Trust - safe for untrusted code
un -s python 'print("Isolated execution")'

# Semi-Trusted - when you need network
un -n semitrusted -s python '
import requests
r = requests.get("https://api.github.com")
print(r.status_code)
'

# Semi-Trusted session for development
un session -n semitrusted --shell bash

Iniciar una sesión de shell interactiva en un contenedor sandbox.

Listar Trabajos Activos

# Default bash shell
un session

# Choose your shell
un session --shell zsh
un session --shell fish

Sesiones REPL

# Python REPL
un session --shell python3
un session --shell ipython
un session --shell bpython

# Node.js REPL
un session --shell node

# Ruby REPL
un session --shell irb

# Other REPLs
un session --shell julia
un session --shell ghci    # Haskell
un session --shell iex     # Elixir

Opciones de Sesión

# With network access
un session -n semitrusted

# With persistence (can reconnect)
un session --tmux
un session --screen

# With timeout (1 hour)
un session --ttl 3600

# Full audit recording
un session --audit -o ./logs

Equivalente API

POST /sessions

{
  "session_id": "sess_xyz789",
  "websocket_url": "wss://api.unsandbox.com/sessions/sess_xyz789/shell",
  "status": "running"
}

Listar Trabajos Activos

un session --list

Salida

Active sessions: 2

SESSION ID                     CONTAINER         SHELL      TTL      STATUS
sess_abc123...                 unsb-vm-12345     python3    45m30s   active
sess_def456...                 unsb-vm-67890     bash       1h2m     active

Obtener Detalles de Sesión

un session --info sess_abc123

Equivalente API

GET /sessions and GET /sessions/{id}

{
  "sessions": [
    {
      "session_id": "sess_abc123",
      "status": "running",
      "network_mode": "zerotrust",
      "shell": "python3"
    }
  ]
}

Reconectar a sesiones persistentes (requiere --tmux o --screen).

Crear Sesión Persistente

# With tmux (recommended)
un session --tmux

# With screen
un session --screen

Desconectar

# tmux: Press Ctrl+b then d
# screen: Press Ctrl+a then d

Descuento

# By session ID
un session --attach sess_abc123

# By container name
un session --attach unsb-vm-12345

Terminar Sesión

# Kill by ID
un session --kill sess_abc123

# Kill by container name
un session --kill unsb-vm-12345

Equivalente API

DELETE /sessions/{id}

{"status": "terminated"}

Congela sesiones para ahorrar recursos mientras preservas el estado.

Congelar Sesión

un session --freeze sess_abc123

Descongelar Sesión

un session --unfreeze sess_abc123

Equivalente API

POST /sessions/{id}/freeze

{"status": "frozen"}

POST /sessions/{id}/unfreeze

{"status": "running", "unfreeze_time_ms": 1250}

Crear instantáneas puntuales del estado de la sesión.

Crear Instantánea

# With name
un session --snapshot sess_abc123 --name "before-upgrade"

# Quick snapshot (auto-generated name)
un session --snapshot sess_abc123

Restaurar desde Instantánea

un session --restore snap_xyz789

Equivalente API

POST /sessions/{id}/snapshot

{
  "snapshot_id": "snap_abc123",
  "name": "before-upgrade",
  "size_bytes": 52428800
}

POST /sessions/{id}/restore

{"status": "restored"}

Create long-running services with automatic HTTPS at *.on.unsandbox.com. TLS certificates are provisioned automatically via Let's Encrypt. Custom domains supported via CNAME.

Servicio Básico

# Simple web server
un service --name myapp --ports 80 --bootstrap "python -m http.server 80"

# With multiple ports
un service --name api --ports 80,443 --bootstrap "./start.sh"

Con Archivos

# Deploy app tarball
un service --name blog --ports 8000 \
  -f app.tar.gz \
  --bootstrap "tar xzf app.tar.gz && cd app && ./start.sh"

Dominios Personalizados

un service --name api --ports 80 \
  --domains api.example.com,www.api.example.com \
  --bootstrap "./start.sh"

Nivel de Servicio:

# Web service (default)
un service --name web --ports 80

# Minecraft server
un service --name mc --type minecraft --bootstrap ./setup.sh

# Game server types
un service --name game --type mumble
un service --name game --type teamspeak
un service --name game --type source

Equivalente API

POST /services

{
  "service_id": "svc_abc123",
  "name": "myapp",
  "url": "https://myapp.on.unsandbox.com",
  "status": "starting",
  "ports": [80]
}

Listar Servicios

un service --list

Obtener Info de Servicio

un service --info svc_abc123

Congelar/Descongelar Servicio

# Freeze (auto-unfreezes on HTTP request)
un service --freeze svc_abc123

# Manual unfreeze
un service --unfreeze svc_abc123

Bloquear/Desbloquear

# Prevent accidental deletion
un service --lock svc_abc123

# Allow deletion
un service --unlock svc_abc123

Destruir Servicio

un service --destroy svc_abc123

Endpoint de API accedido

• GET /services - Listar todos los servicios
• GET /services/{id} - Obtener detalles de servicio
• POST /services/{id}/freeze - Congelar servicio
• POST /services/{id}/unfreeze - Descongelar servicio
• POST /services/{id}/lock - Bloquear servicio
• POST /services/{id}/unlock - Desbloquear Bóveda
• DELETE /services/{id} - Destruir servicio

Descongelar automáticamente

Cuando está habilitado, los servicios congelados se despiertan automáticamente al recibir una solicitud HTTP.

# Enable auto-unfreeze (default for new services)
un service --auto-unfreeze svc_abc123

# Disable auto-unfreeze
un service --no-auto-unfreeze svc_abc123

Vista de la página de congelación

Controla lo que los visitantes ven al acceder a un servicio congelado.

# Show HTML payment page (default)
un service --show-freeze-page svc_abc123

# Return JSON error instead
un service --no-show-freeze-page svc_abc123

Equivalente API

PATCH /services/{id}

# Enable auto-unfreeze
{"unfreeze_on_demand": true}

# Disable freeze page (return JSON error)
{"show_freeze_page": false}

Comportamiento de la página de congelación

• show_freeze_page: true - Muestra una página HTML con opciones de pago
• show_freeze_page: false - Retorna JSON: {"error": "service_frozen"}

Usa el modo JSON para servicios API donde las respuestas HTML podrían afectar a los clientes.

Ver Registros de Arranque

# All logs
un service --logs svc_abc123

# Last 9000 lines
un service --tail svc_abc123

Ejecutar Código

# Run any command
un service --execute svc_abc123 'ls -la'

# Check service status
un service --execute svc_abc123 'systemctl status myapp'

# View application logs
un service --execute svc_abc123 'journalctl -u myapp -n 50'

Volcar Script de Arranque

# Print to stdout
un service --dump-bootstrap svc_abc123

# Save to file
un service --dump-bootstrap svc_abc123 backup.sh

Equivalente API

GET /services/{id}/logs

{"log": "Bootstrap started...\nInstalling...\nServer listening on port 80"}

POST /services/{id}/execute

{
  "stdout": "...",
  "stderr": "",
  "exit_code": 0
}

Almacenamiento cifrado para secretos de servicio. Las variables se inyectan cuando el contenedor arranca o se descongela.

Establecer Variables de Entorno

# Using the API (PUT /services/{id}/env)
# Content-Type: text/plain
# Body: .env format

DATABASE_URL=postgres://user:pass@host/db
API_SECRET=abc123
DEBUG=false

Obtener Estado de Bóveda

GET /services/{id}/env

{
  "exists": true,
  "variable_count": 3,
  "updated_at": "2026-01-14T12:00:00Z"
}

Exportar Bóveda Descifrada

POST /services/{id}/env/export

{"env": "DATABASE_URL=postgres://...\nAPI_SECRET=abc123\nDEBUG=false"}

Eliminar

DELETE /services/{id}/env

{"status": "deleted"}

Re-ejecutar Arranque

# Re-run existing bootstrap
un service --redeploy svc_abc123

# Redeploy with new bootstrap
un service --redeploy svc_abc123 --bootstrap ./new-setup.sh

Crear Instantánea de Servicio

# Standard snapshot (pauses briefly)
un service --snapshot svc_abc123 --name "stable-v1.0"

# Hot snapshot (no pause)
un service --snapshot svc_abc123 --hot

Equivalente API

POST /services/{id}/redeploy

{"state": "redeploying"}

POST /services/{id}/snapshot

{
  "snapshot_id": "snap_def456",
  "name": "stable-v1.0",
  "size_bytes": 104857600
}

Listar Todas las Instantáneas

un snapshot --list

Salida

Snapshots: 3

SNAPSHOT ID                  NAME              SOURCE     SIZE     CREATED
snap_a1b2-c3d4-e5f6-g7h8     before-upgrade    session    512 MB   2h ago
snap_i9j0-k1l2-m3n4-o5p6     stable-v1.0       service    1.2 GB   1d ago
snap_q7r8-s9t0-u1v2-w3x4     dev-checkpoint    session    256 MB   3d ago

Obtener Info de Instantánea

un snapshot --info snap_a1b2-c3d4-e5f6-g7h8

Eliminar Instantánea

un snapshot --delete snap_a1b2-c3d4-e5f6-g7h8

Equivalente API

GET /snapshots

{
  "snapshots": [
    {
      "snapshot_id": "snap_abc123",
      "name": "before-upgrade",
      "source_type": "session",
      "size_bytes": 52428800
    }
  ]
}

Restaurar al Original

# Restore session from snapshot
un session --restore snap_abc123

# Restore service from snapshot
un service --restore snap_def456

Clonar a Nuevo Contenedor

POST /snapshots/{id}/clone

# Clone to new session
{
  "type": "session",
  "shell": "bash"
}

# Clone to new service
{
  "type": "service",
  "name": "cloned-app"
}

Respuesta

Clonar a sesión:

{"session_id": "sess_new123"}

Clonar a servicio:

{
  "service_id": "svc_new456",
  "url": "https://cloned-app.on.unsandbox.com"
}

Bloquear/Desbloquear Instantáneas

POST /snapshots/{id}/lock - Prevenir eliminación

POST /snapshots/{id}/unlock - Permitir eliminación

Ejecuta código de inmediato y espera los resultados. Ideal para scripts rápidos y uso interactivo.

Parámetros de solicitud

Submit code for execution and receive a job ID to poll for results. Best for long-running scripts or when you need to decouple submission from execution.

Parámetros de solicitud

Execute code with automatic language detection via shebang. Send raw code as the request body with Content-Type: text/plain.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env python3)

Query Parameters

Submit code with automatic language detection and receive a job ID. Combines the convenience of /run with the flexibility of async execution.

Request

• Content-Type: text/plain
• Body: Raw code with shebang (e.g., #!/usr/bin/env ruby)

Query Parameters

Check the status and results of an asynchronous job. Poll this endpoint after submitting a job via /execute/async or /run/async.

URL Parameters

Possible Status Values

• pending - Job queued, waiting to execute
• running - Job currently executing
• completed - Job finished successfully
• failed - Job execution failed
• timeout - Job exceeded TTL limit
• cancelled - Job was cancelled via DELETE

List all active (pending or running) jobs for your API key. Useful for monitoring multiple async executions.

Cancel a pending or running job. If the job is already executing, it will be terminated and partial output returned.

URL Parameters

Publicar una imagen desde un servicio o instantánea.

Cuerpo de Solicitud

Metadatos de Solicitud:

{
  "source_type": "service",
  "source_id": "unsb-service-abc123",
  "name": "my-app-v1.0",
  "description": "Production-ready app image"
}

Respuesta

{
  "id": "unsb-image-xyz789",
  "name": "my-app-v1.0",
  "description": "Production-ready app image",
  "source_type": "service",
  "source_id": "unsb-service-abc123",
  "fingerprint": "abc123def456...",
  "size_bytes": 524288000,
  "visibility": "private",
  "locked": false,
  "owner_api_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx",
  "created_at": "2025-01-11T12:00:00Z"
}

Listar todas las imágenes que posees o que se compartieron con tu clave API.

Endpoints relacionados

• GET /images/public — Listar imágenes del marketplace
• GET /images/owned — Listar solo tus imágenes
• GET /images/shared — Listar imágenes compartidas contigo

Respuesta

{
  "images": [
    {
      "id": "unsb-image-xyz789",
      "name": "my-app-v1.0",
      "fingerprint": "abc123...",
      "size_bytes": 524288000,
      "visibility": "private",
      "locked": false,
      "created_at": "2025-01-11T12:00:00Z"
    }
  ]
}

Obtener información detallada sobre una imagen.

Parámetros de URL

Respuesta

{
  "id": "unsb-image-xyz789",
  "name": "my-app-v1.0",
  "description": "Production-ready app image",
  "source_type": "service",
  "source_id": "unsb-service-abc123",
  "fingerprint": "abc123def456...",
  "node": "cammy",
  "size_bytes": 524288000,
  "visibility": "private",
  "locked": false,
  "owner_api_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx",
  "trusted_keys": [],
  "created_at": "2025-01-11T12:00:00Z"
}

Crear un nuevo servicio usando esta imagen como base.

Cuerpo de Solicitud

Metadatos de Solicitud:

{
  "name": "my-app-instance",
  "ports": [8080],
  "network_mode": "semitrusted"
}

Respuesta

{
  "service_id": "unsb-service-xyz789",
  "name": "my-app-instance",
  "source_image": "unsb-image-abc123",
  "state": "starting"
}

Visibilidad

POST /images/{id}/visibility

{"visibility": "unlisted"}

Clonar imagen

POST /images/{id}/clone

{
  "name": "my-copy-of-app",
  "description": "My personal copy"
}

Bloquear/Desbloquear

• POST /images/{id}/lock — Prevenir eliminación
• POST /images/{id}/unlock — Permitir eliminación

Eliminar imagen

DELETE /images/{id}

Otorgar acceso

POST /images/{id}/grant

{
  "api_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx"
}

Revocar acceso

POST /images/{id}/revoke

{
  "api_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx"
}

Listar claves de confianza

GET /images/{id}/trusted

{
  "trusted_keys": [
    "unsb-pk-aaaa-bbbb-cccc-dddd",
    "unsb-pk-1111-2222-3333-4444"
  ]
}

Transferir propiedad

POST /images/{id}/transfer

{
  "to_api_key": "unsb-pk-xxxx-xxxx-xxxx-xxxx"
}

Valida tu par de claves API y obtén su configuración incluyendo límites de tasa, límites de concurrencia y estado de expiración.

Esto es útil para:

• Verificando si tu par de claves es válido
• Viendo tus límites actuales
• Construyendo interfaces de gestión de claves
• Monitoreando expiración de claves

Autenticación

Usa autenticación HMAC estándar (igual que todos los demás endpoints).

Retorna todos los lenguajes de programación soportados y sus alias.

Alias Comunes

• node, js → javascript
• ts → typescript
• lisp → commonlisp

Respuesta

{
  "languages": [
    "python",
    "javascript",
    "typescript",
    "ruby",
    "go",
    "rust",
    "c",
    "cpp"
  ],
  "aliases": {
    "js": "javascript",
    "node": "javascript",
    "ts": "typescript",
    "lisp": "commonlisp"
  },
  "count": 42
}

Retorna todos los shells y REPL soportados para sesiones interactivas, agrupados por categoría.

Categorías

• unix — bash, dash, sh, zsh, fish, ksh
• python — python, python3, ipython, bpython
• javascript — node
• ruby — ruby, irb
• lisp — scheme, guile, sbcl, clisp, clojure
• erlang — erl, iex
• data — r, julia, sqlite3

Respuesta

{
  "shells": [
    "bash", "bpython", "clisp",
    "clojure", "dash", "fish",
    "ghci", "guile", "iex",
    "ipython", "irb", "julia"
  ],
  "categories": {
    "unix": ["bash", "dash", "sh", "zsh", "fish"],
    "python": ["python", "python3", "ipython", "bpython"],
    "javascript": ["node"],
    "ruby": ["ruby", "irb"],
    "lisp": ["scheme", "guile", "sbcl", "clisp", "clojure"]
  },
  "count": 35
}

Endpoint simple de verificación de estado. Retorna el estado del servicio.

Respuesta

{"status": "ok"}

Obtener información sobre el pool de contenedores y el estado del sistema.

Modos de Red

• zerotrust_only — Only isolated containers
• semitrusted_only — Only network-enabled containers
• hybrid — Both types available

Respuesta

{
  "mode": "pooled",
  "pool_size": 288,
  "allocated": 5,
  "available": 280,
  "spawning": 0,
  "total_containers": 285,
  "network_mode": "hybrid",
  "network_breakdown": {
    "zerotrust": {
      "allocated": 2,
      "available": 140,
      "total": 142
    },
    "semitrusted": {
      "allocated": 3,
      "available": 140,
      "services": 1,
      "total": 143
    }
  }
}

Obtener el estado de todos los pools de contenedores registrados (escalado horizontal).

Respuesta

{
  "pool_count": 2,
  "total_capacity": 288,
  "total_allocated": 8,
  "total_available": 280,
  "pools": [
    {
      "id": "pool_manager@cammy",
      "allocated": 4,
      "available": 140,
      "total": 144
    },
    {
      "id": "pool_manager@ai",
      "allocated": 4,
      "available": 140,
      "total": 144
    }
  ]
}

Obtener estadísticas detalladas del sistema incluyendo carga y métricas de contenedores.

Respuesta

{
  "containers": 285,
  "load_1min": "2.15",
  "load_5min": "1.89",
  "load_15min": "1.45"
}