Sandbox Commands

Sandbox commands allow you to create, manage, and interact with secure isolated environments.

islo use

Use a sandbox - creates it if it doesn’t exist, then opens a shell or runs a command.

Syntax:

$ islo use [name]              # Create if needed, open shell
$ islo use [name] -- <cmd>     # Create if needed, run command

Arguments:

Argument	Required	Description
`name`	No	Sandbox name (uses `islo.yaml` or server-generated if not provided)

Options:

Option	Default	Description
`-i, --image`	`python:3.12-slim`	Container image to use
`--source`	-	Git repository to clone (e.g., `github://owner/repo`)
`--workdir`	`/workspace`	Working directory (relative or absolute path)
`--snapshot`	-	Create sandbox from a snapshot
`--gateway-profile`	-	Gateway profile for network policy and credentials
`-e, --env`	-	Environment variables (KEY=VALUE, repeatable)
`--run-as-user`	`islo`	User to run commands as
`-s, --session`	`main`	Session name to connect to
`--new-session`	-	Start a new session (generates unique name)
`--list-sessions`	-	List active sessions in the sandbox
`--agent`	-	Run with AI agent (claude, cursor)
`--task`	-	Background task prompt for agent

Examples:

$ # Use sandbox with default settings (opens shell)
$ islo use my-sandbox
$ 
$ # Use sandbox with specific image
$ islo use py-dev -i docker.io/library/python:3.13-slim
$ 
$ # Run a command in sandbox
$ islo use my-sandbox -- echo "Hello, World!"
$ 
$ # Run Python code
$ islo use my-sandbox -- python3 -c "print('Hello from sandbox!')"
$ 
$ # Install a package and run script
$ islo use my-sandbox -- pip install requests
$ islo use my-sandbox -- python3 main.py
$ 
$ # Run with arguments
$ islo use my-sandbox -- python3 script.py --input data.json --output result.json
$ 
$ # Clone a GitHub repo into sandbox
$ islo use my-sandbox --source github://owner/repo
$ 
$ # Clone specific branch
$ islo use my-sandbox --source github://owner/repo:feature-branch
$ 
$ # Create sandbox from a snapshot
$ islo use my-sandbox --snapshot before-refactor
$ 
$ # Use with gateway profile for API access
$ islo use my-sandbox --gateway-profile production-apis
$ 
$ # Set working directory
$ islo use my-sandbox --workdir /workspace/backend
$ 
$ # Set environment variables
$ islo use my-sandbox --env MY_VAR=value --env OTHER=123
$ 
$ # Session management
$ islo use my-sandbox --list-sessions   # List active sessions
$ islo use my-sandbox --new-session     # Start new session
$ islo use my-sandbox -s debug          # Connect to 'debug' session

Exit codes:

Code	Meaning
0	Success
1	Authentication required
*	Exit code from the executed command

islo stop

Stop a running sandbox without removing it.

Syntax:

$ islo stop <name> [-f]

Arguments:

Argument	Required	Description
`name`	Yes	Sandbox name or ID

Options:

Option	Description
`-f, --force`	Force stop without confirmation

Example:

$ # Stop with confirmation
$ islo stop my-sandbox
$ 
$ # Force stop
$ islo stop my-sandbox -f

Exit codes:

Code	Meaning
0	Sandbox stopped
1	Authentication required
3	Sandbox not found

islo rm

Remove a sandbox completely (stops and deletes).

Syntax:

$ islo rm <name> [-f]

Arguments:

Argument	Required	Description
`name`	Yes	Sandbox name or ID

Options:

Option	Description
`-f, --force`	Force removal without confirmation

Examples:

$ # Remove with confirmation
$ islo rm my-sandbox
$ 
$ # Force remove
$ islo rm my-sandbox -f

Aliases: islo delete

Exit codes:

Code	Meaning
0	Sandbox removed
1	Authentication required
3	Sandbox not found

islo ls

List all sandboxes.

Syntax:

$ islo ls

Aliases: islo list

Example output:

NAME          IMAGE                  STATUS    CPU   MEMORY   CREATED
my-sandbox    python:3.12-slim      Running   2     1Gi      5 minutes ago
dev-env       python:3.13-slim      Stopped   4     4Gi      2 hours ago

Exit codes:

Code	Meaning
0	Success
1	Authentication required

islo status

Get detailed information about a sandbox or overall status.

Syntax:

$ islo status           # Show auth, config, tools overview
$ islo status <name>    # Get specific sandbox details

Arguments:

Argument	Required	Description
`name`	No	Sandbox name (if omitted, shows general status)

Example output for sandbox:

Sandbox: my-sandbox
Status: Running
Image: docker.io/library/python:3.12-slim
Resources:
  CPU: 2 cores
  Memory: 1Gi
  Disk: 10Gi
Created: 2024-01-15 10:30:00 UTC
Uptime: 5 minutes

Exit codes:

Code	Meaning
0	Success
1	Authentication required
3	Sandbox not found (when name provided)

islo logs

Investigate sandbox logs - agent sessions, exec commands, and interactive sessions.

Syntax:

$ islo logs <sandbox> [session-id]

Arguments:

Argument	Required	Description
`sandbox`	Yes	Sandbox name or ID
`session-id`	No	Specific session ID to view details

Options:

Option	Description
`--type <TYPE>`	Log type: `agent` (default), `exec`, or `interactive`
`-f, --follow`	Stream logs live
`--tail <N>`	Show last N entries
`--head <N>`	Show first N entries (exec mode only)
`--since <DURATION>`	Show logs since duration (e.g., `1h`, `30m`, `2d`)

Examples:

$ # View agent sessions (default)
$ islo logs my-sandbox
$ 
$ # View exec command logs
$ islo logs my-sandbox --type exec
$ 
$ # View interactive sessions
$ islo logs my-sandbox --type interactive
$ 
$ # Stream logs live
$ islo logs my-sandbox --follow
$ 
$ # View specific session details
$ islo logs my-sandbox abc123-session-id
$ 
$ # Recent logs only
$ islo logs my-sandbox --since 2h
$ islo logs my-sandbox --tail 100
$ 
$ # Exec logs from last hour
$ islo logs my-sandbox --type exec --since 1h --follow

islo port-forward

Forward a local port to a port inside the sandbox.

Syntax:

$ islo port-forward <name> <port-mapping>

Aliases: islo pf

Arguments:

Argument	Required	Description
`name`	Yes	Sandbox name
`port-mapping`	Yes	`LOCAL:REMOTE` or just `PORT` for same local/remote

Examples:

$ # Forward local 8080 to sandbox 8080
$ islo port-forward my-sandbox 8080
$ 
$ # Forward local 3000 to sandbox 8080
$ islo port-forward my-sandbox 3000:8080
$ 
$ # Forward PostgreSQL port
$ islo pf my-sandbox 5432:5432
$ 
$ # Forward multiple ports (run in separate terminals)
$ islo pf my-sandbox 3000:3000  # Frontend
$ islo pf my-sandbox 5432:5432  # Database

The command blocks while forwarding. Press Ctrl-C to stop.

islo ssh

Set up SSH access to sandboxes for direct shell access.

Syntax:

$ islo ssh --setup

Setup process:

Generates SSH certificates
Configures your ~/.ssh/config with Islo proxy settings
Enables direct SSH access using <sandbox-name>.islo so you can connect your IDE directly

After setup:

$ # Connect to any sandbox via SSH
$ ssh my-sandbox.islo
$ 
$ # Use with standard SSH tools
$ scp file.txt my-sandbox.islo:/workspace/
$ rsync -av ./src/ my-sandbox.islo:/workspace/src/

Exit codes:

Code	Meaning
0	Setup successful
1	Authentication required

islo snapshot

Manage VM snapshots - save, list, and restore sandbox state.

For detailed documentation, see Snapshots.

Quick reference:

$ islo snapshot save my-sandbox              # Save snapshot
$ islo snapshot save my-sandbox --name snap  # Save with custom name
$ islo snapshot ls                           # List all snapshots
$ islo snapshot rm <name>                    # Delete snapshot
$ islo use new-sandbox --snapshot <name>     # Restore from snapshot