> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.islo.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.islo.dev/_mcp/server. # Sandbox Commands > Islo CLI commands for creating, managing, and executing code in secure sandbox environments. 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:** ```bash islo use [name] # Create if needed, open shell islo use [name] -- # 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` | `ghcr.io/islo-labs/islo-runner:latest` | Container image to use (env: `ISLO_IMAGE`) | | `--cpu` | from `islo.yaml` | Number of vCPUs for new sandboxes (env: `ISLO_CPU`) | | `--memory` | from `islo.yaml` | Memory in MB for new sandboxes (env: `ISLO_MEMORY_MB`) | | `--disk` | from `islo.yaml` | Disk 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` | `/workspace` | Working directory (relative to `/workspace`, or absolute path) | | `--snapshot` | - | Create sandbox from a snapshot | | `--gateway-profile` | from `islo.yaml` | Gateway profile for network policy and credentials | | `--environment` | from `islo.yaml` | Named reusable environment for sandbox env vars and environment-owned gateway-injected secrets | | `-e, --env ` | - | Set an environment variable in the sandbox (repeatable) | | `--env-file ` | - | Load environment variables from a `.env` file (repeatable, env: `ISLO_ENV_FILE`). `--env` flags override these. | | `--run-as-user` | `islo` | User to run commands as | | `-s, --session` | `main` | Session name to connect to | | `--new-session` | - | Start a new session (generates a unique name) | | `--list-sessions` | - | List active sessions in the sandbox | | `--agent` | auto-detect | Agent profile to run (claude, cursor) | | `--task` | - | Initial task/prompt for the agent. **Requires `--agent`.** | **Examples:** ```bash # 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 # Use a named reusable environment islo use my-sandbox --environment production # 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 ``` ## Common exit codes | Code | Meaning | | ---- | ----------------------------------- | | 0 | Success | | 1 | Authentication required | | \* | Exit code from the executed command | ## islo environment Manage reusable environments for sandbox env vars and environment-owned gateway-injected secrets. Use environment names in user-facing flows. ```bash islo environment list islo environment get production islo environment create --name production --variable PUBLIC_FLAG=enabled islo environment patch production --secret OPENAI_API_KEY="$OPENAI_API_KEY" islo environment remove production ``` ## islo stop Stop one or more running sandboxes without removing them. **Syntax:** ```bash islo stop [...] [-f] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------------------------------- | | `name` | Yes | Sandbox name(s) or ID(s). Multiple names stop several sandboxes in one call. | **Options:** | Option | Description | | ------------- | ------------------------------- | | `-f, --force` | Force stop without confirmation | **Examples:** ```bash # 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:** | Code | Meaning | | ---- | ----------------------- | | 0 | Sandbox stopped | | 1 | Authentication required | | 3 | Sandbox 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](/concepts/sandbox-lifecycle/) when creating the sandbox via the SDK or API. **Syntax:** ```bash islo pause [...] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | -------------------------------------------------------------------- | | `name` | Yes | Sandbox name(s). Multiple names pause several sandboxes in one call. | **Examples:** ```bash # 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:** ```bash islo resume [...] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ------------------------- | | `name` | Yes | Sandbox name(s) to resume | **Examples:** ```bash 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:** ```bash islo rm [...] [-f] ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------ | | `name` | Yes | Sandbox name(s) or ID(s). Multiple names remove several sandboxes in one call. | **Options:** | Option | Description | | ------------- | ---------------------------------- | | `-f, --force` | Force removal without confirmation | **Examples:** ```bash # 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:** | Code | Meaning | | ---- | ----------------------- | | 0 | Sandbox removed | | 1 | Authentication required | | 3 | Sandbox not found | ## islo ls List sandboxes. By default, only sandboxes created by you are shown — pass `--all` to see everything in your team. **Syntax:** ```bash islo ls [options] ``` **Aliases:** `islo list` **Options:** | Option | Description | | ------------------- | ------------------------------------------------------------------------------------------------------------------ | | `-a, --all` | Show all sandboxes in your team (default: only yours) | | `--status ` | Filter by status. Repeatable — values: `starting`, `running`, `paused`, `stopping`, `stopped`, `failed`, `deleted` | **Examples:** ```bash 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:** | Code | Meaning | | ---- | ----------------------- | | 0 | Success | | 1 | Authentication required | ## islo status Show your authentication state, integrations, project configuration, and sandboxes — or details for one sandbox. **Syntax:** ```bash islo status # Overview islo status # Sandbox details ``` **Arguments:** | Argument | Required | Description | | -------- | -------- | ------------------------------------ | | `name` | No | Sandbox name. Omit for the overview. | For an example of the overview output, see [Authentication → `islo status`](/cli/authentication/#islo-status). With ``, `islo status` prints the sandbox's status, image, resource allocation, and timestamps. Use `--output json` for structured output. **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:** ```bash islo logs [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 ` | Log type: `agent` (default), `exec`, or `interactive` | | `-f, --follow` | Stream logs live | | `--tail ` | Last N entries. Defaults: 50 events for agent detail, 500 lines for exec detail. No limit for list/stream modes. | | `--head ` | First N log lines (exec stream mode only). **Cannot be combined with `--tail`.** | | `--since ` | Show logs since a duration ago (e.g., `1h`, `30m`, `2d`) | **Examples:** ```bash # 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:** ```bash islo port-forward ``` **Aliases:** `islo pf` **Arguments:** | Argument | Required | Description | | -------------- | -------- | --------------------------------------------------- | | `name` | Yes | Sandbox name | | `port-mapping` | Yes | `LOCAL:REMOTE` or just `PORT` for same local/remote | **Examples:** ```bash # 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:** ```bash islo ssh --setup ``` **Setup process:** 1. Generates SSH certificates 2. Configures your `~/.ssh/config` with Islo proxy settings 3. Enables direct SSH access using `.islo` so you can connect your IDE directly **After setup:** ```bash # 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](/cli/snapshots/). **Quick reference:** ```bash 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 # Delete snapshot islo use new-sandbox --snapshot # Restore from snapshot ```