CLI

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:

ArgumentRequiredDescription
nameNoSandbox name (uses islo.yaml or server-generated if not provided)

Options:

OptionDefaultDescription
-i, --imageghcr.io/islo-labs/islo-runner:latestContainer image to use (env: ISLO_IMAGE)
--cpufrom islo.yamlNumber of vCPUs for new sandboxes (env: ISLO_CPU)
--memoryfrom islo.yamlMemory in MB for new sandboxes (env: ISLO_MEMORY_MB)
--diskfrom islo.yamlDisk size in GB for new sandboxes (env: ISLO_DISK_GB)
--source-Git repo to clone (e.g., github://owner/repo[:branch] or HTTPS URL). Repeatable to clone multiple repos.
--workdir/workspaceWorking directory (relative to /workspace, or absolute path)
--snapshot-Create sandbox from a snapshot
--gateway-profilefrom islo.yamlGateway profile for network policy and credentials
-e, --env <KEY=VAL>-Set an environment variable in the sandbox (repeatable)
--env-file <PATH>-Load environment variables from a .env file (repeatable, env: ISLO_ENV_FILE). --env flags override these.
--run-as-userisloUser to run commands as
-s, --sessionmainSession name to connect to
--new-session-Start a new session (generates a unique name)
--list-sessions-List active sessions in the sandbox
--agentauto-detectAgent profile to run (claude, cursor)
--task-Initial task/prompt for the agent. Requires --agent.

Examples:

$# Use sandbox with default settings (opens shell)
$islo use my-sandbox
$
$# Use sandbox with specific image
$islo use py-dev -i ghcr.io/islo-labs/islo-runner:latest
$
$# 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
$
$# Clone multiple repos
$islo use my-sandbox --source github://owner/api --source github://owner/frontend
$
$# 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 (inline and via .env file)
$islo use my-sandbox --env MY_VAR=value --env OTHER=123
$islo use my-sandbox --env-file .env
$
$# Override resources for a new sandbox
$islo use my-sandbox --cpu 4 --memory 8192 --disk 40
$
$# Run an agent with an initial task (requires --agent)
$islo use --agent claude --task "Refactor the auth module"
$
$# 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:

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

islo stop

Stop one or more running sandboxes without removing them.

Syntax:

$islo stop <name> [<name>...] [-f]

Arguments:

ArgumentRequiredDescription
nameYesSandbox name(s) or ID(s). Multiple names stop several sandboxes in one call.

Options:

OptionDescription
-f, --forceForce stop without confirmation

Examples:

$# Stop with confirmation
$islo stop my-sandbox
$
$# Force stop
$islo stop my-sandbox -f
$
$# Stop several at once
$islo stop sandbox-1 sandbox-2 sandbox-3

Exit codes:

CodeMeaning
0Sandbox stopped
1Authentication required
3Sandbox not found

islo pause

Pause a running sandbox. The VM snapshots its state and releases compute resources, so paused sandboxes don’t count against running-sandbox quotas. Use islo resume to bring it back.

For automatic pause, resume, and deletion based on idle time or TTL, set a lifecycle policy when creating the sandbox via the SDK or API.

Syntax:

$islo pause <name> [<name>...]

Arguments:

ArgumentRequiredDescription
nameYesSandbox name(s). Multiple names pause several sandboxes in one call.

Examples:

$# Pause one sandbox
$islo pause my-sandbox
$
$# Pause several at once
$islo pause sandbox-1 sandbox-2 sandbox-3

Notes:

  • Only running sandboxes can be paused.
  • Pause is cheaper than stop+rm+recreate when you’ll come back to the same workspace soon — files, processes, and in-memory state are restored on resume.

islo resume

Resume one or more paused sandboxes.

Syntax:

$islo resume <name> [<name>...]

Arguments:

ArgumentRequiredDescription
nameYesSandbox name(s) to resume

Examples:

$islo resume my-sandbox
$islo resume sandbox-1 sandbox-2

After resume, the sandbox is back to running and you can islo use it as normal.

islo rm

Remove one or more sandboxes completely (stops and deletes).

Syntax:

$islo rm <name> [<name>...] [-f]

Arguments:

ArgumentRequiredDescription
nameYesSandbox name(s) or ID(s). Multiple names remove several sandboxes in one call.

Options:

OptionDescription
-f, --forceForce removal without confirmation

Examples:

$# Remove with confirmation
$islo rm my-sandbox
$
$# Force remove
$islo rm my-sandbox -f
$
$# Remove several at once
$islo rm sandbox-a sandbox-b sandbox-c

Aliases: islo delete

Exit codes:

CodeMeaning
0Sandbox removed
1Authentication required
3Sandbox not found

islo ls

List sandboxes. By default, only sandboxes created by you are shown — pass --all to see everything in your team.

Syntax:

$islo ls [options]

Aliases: islo list

Options:

OptionDescription
-a, --allShow all sandboxes in your team (default: only yours)
--status <STATUS>Filter by status. Repeatable — values: starting, running, paused, stopping, stopped, failed, deleted

Examples:

$islo ls                                  # Your sandboxes
$islo ls --all                            # Whole team
$islo ls --status running                 # Only running
$islo ls --status running --status paused # Running or paused
$islo ls --status deleted                 # Soft-deleted sandboxes
$islo ls --output json                    # JSON array for scripting

Example output:

ID         NAME          STATUS    IMAGE                        CREATED BY    CREATED AT
sb_abc123  my-sandbox    running   islo-runner:latest           alice@…       2026-05-12 09:30
sb_def456  dev-env       paused    islo-runner:latest   alice@…       2026-05-10 14:22

--output json adds the same data as an array of objects (and includes deleted-at for deleted sandboxes).

Exit codes:

CodeMeaning
0Success
1Authentication required

islo status

Show your authentication state, integrations, project configuration, and sandboxes — or details for one sandbox.

Syntax:

$islo status           # Overview
$islo status <name>    # Sandbox details

Arguments:

ArgumentRequiredDescription
nameNoSandbox name. Omit for the overview.

For an example of the overview output, see Authentication → islo status. With <name>, islo status prints the sandbox’s status, image, resource allocation, and timestamps. Use --output json for structured output.

Exit codes:

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

islo logs

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

Syntax:

$islo logs <sandbox> [session-id]

Arguments:

ArgumentRequiredDescription
sandboxYesSandbox name or ID
session-idNoSpecific session ID to view details

Options:

OptionDescription
--type <TYPE>Log type: agent (default), exec, or interactive
-f, --followStream logs live
--tail <N>Last N entries. Defaults: 50 events for agent detail, 500 lines for exec detail. No limit for list/stream modes.
--head <N>First N log lines (exec stream mode only). Cannot be combined with --tail.
--since <DURATION>Show logs since a duration ago (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:

ArgumentRequiredDescription
nameYesSandbox name
port-mappingYesLOCAL: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:

  1. Generates SSH certificates
  2. Configures your ~/.ssh/config with Islo proxy settings
  3. 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:

CodeMeaning
0Setup successful
1Authentication 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