> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

Deep dive into Maestro's execution environment.

## What Is the Sandbox?

The sandbox is a **cloud-based Ubuntu Linux environment** attached to your session. Think of it as a clean, disposable computer where Maestro can:

* Compile and run code
* Execute tests and benchmarks
* Start web servers
* Install packages
* Perform real validation

**Every chat gets its own isolated sandbox**--your work never interferes with others.

## Sandbox Lifecycle

### Starting

* Sandbox starts **on first terminal command** in a session
* Fresh Ubuntu environment each time
* Passwordless root access via `sudo`
* Port 8080 exposed on public preview URL

### Running

* Processes run until explicitly stopped
* Web servers keep serving
* Long-running tasks continue in background
* Terminal windows maintain state

### Auto-Termination

After periods of inactivity, the sandbox automatically terminates:

**Default behavior**:

* **1 hour** after last execution
* Applies when no commands have been run for 60 minutes
* Session itself is preserved (checkpointed)
* Sandbox resources cleaned up

**Extended persistence** (via settings):

* Enable "Persist Sandbox" in settings UI
* Extends auto-termination to **24 hours** after last execution
* Useful for long-running demos or extended breaks
* Still terminates eventually to free resources

**Important**: Session state (files, memories, code) is always preserved via checkpointing. Only the sandbox execution environment terminates.

### Resuming

* When you send another command, a new sandbox starts
* Files restore automatically from session state
* Previously installed packages need reinstallation
* Environment variables need reactivation

### Manual Control

* **`/reset-sandbox` command**: Force immediate reset
* Confirms before resetting to prevent accidents
* Useful when sandbox becomes unresponsive

## System Environment

### Operating System

* **Distribution**: Ubuntu Linux (x86-64)
* **User account**: `sandbox` user with passwordless `sudo`
* **Resources**: 2 vCPU, 7 GB RAM (shared with support services)
* **Container**: Firecracker microVM (secure isolation)

### Default Software

* **Python**: System Python 3.x with default virtualenv at `./user_venv`
* **Compilers**: GCC, system development tools
* **Package managers**: `apt-get` (system), `pip` (Python), `npm`/`pnpm` (JavaScript)

### Installing Packages

**System packages**:

```bash theme={null}
sudo apt-get update
sudo apt-get install -y package-name
```

**Python packages**:

```bash theme={null}
pip install package-name  # Installs to default venv
```

**JavaScript packages**:

```bash theme={null}
npm install package-name  # or pnpm
```

**Recommendation**: Use system Python directly, no need for separate virtual environments.

## File Synchronization

### Working Directory

Files are mounted to `/home/sandbox/`. Your session's file structure is preserved:

```
Session file: example/test.txt
Sandbox path: /home/sandbox/example/test.txt
```

### Understanding Sandbox Files

**Important concepts**:

* **Synced files**: Files tracked by Maestro and synchronized between session and sandbox
* **Local sandbox files**: Files created directly in the sandbox (e.g., via SSH or terminal commands) that are NOT automatically synced
* **Ephemeral nature**: The sandbox environment itself is temporary and will be terminated after inactivity. Only synced files persist across sandbox resets.

**What this means**:

* Files created or modified by Maestro's tools are automatically synced and persist
* Files you create via SSH or terminal commands in the sandbox are local and ephemeral unless they're synced file types
* When the sandbox terminates, only synced files are preserved in your session
* Build artifacts, installed packages, and non-synced files are lost when sandbox terminates

### Synchronization Behavior

**Automatically Synchronized**:

* Text-based source code files
* Configuration files (JSON, YAML, TOML, etc.)
* Documentation (Markdown, text)
* Specific media: PNG, JPG, WebP, GIF, PDF

**NOT Synchronized**:

* Build artifacts
* Dependencies (node\_modules, .venv, etc.)
* Large binaries
* Temporary files
* Log directories

**Direction**:

* **To sandbox**: All synced file changes sync immediately (eager synchronization)
* **From sandbox**: Only source code and specific media types sync back to session
* **Live reload**: If server running, sees changes instantly
* **SSH changes**: When you SSH to the sandbox and modify synced files, those changes will sync back to Maestro's file system

### Working with SSH

If you connect to the sandbox via SSH:

* Changes to synced files (e.g., editing a Python file) will sync back to Maestro's session
* Changes to non-synced files (e.g., adding files to node\_modules) will NOT sync and are ephemeral
* Use synced directories (`/home/sandbox/`) for files you want to persist
* Use temporary directories or excluded paths for ephemeral work

### Managing File Synchronization

**Use `.gitignore`** to prevent syncing unwanted files:

```gitignore theme={null}
# Build artifacts
/build/
/dist/

# Dependencies
node_modules/
.venv/

# Logs
*.log
/logs/
```

**Use temporary directories** for large outputs:

```bash theme={null}
# Good - won't sync
mkdir /tmp/build
./compile.sh --output /tmp/build

# Good - won't sync if .gitignored
mkdir logs/
```

**Key principle**: Keep only lightweight source code under `/home/sandbox/`

### File Visibility to Maestro

Maestro can see (via View Files tool):

* All text-representable source code
* PNG, JPG, WebP, GIF, PDF files

Maestro cannot see (use sandbox tools to inspect):

* Compiled binaries
* Large data files
* Non-synchronized formats

## Network and Ports

### Public Access

* **Port 8080**: Only port exposed publicly
* **Preview URL**: Unique per sandbox (e.g., `abc123.preview.igent.ai`)
* **Access**: Anyone with URL can access (don't share sensitive services)

**Using the preview URL**:

```bash theme={null}
# Inside sandbox, access via environment variable
curl $PUBLIC_HOSTNAME:8080

# Configure web frameworks to bind to 0.0.0.0:8080
# Set up CORS to allow preview hostname
```

**Important**: Configure your frameworks for the public hostname. Example in `vite.config.js`:

```javascript theme={null}
server: {
  host: '0.0.0.0',
  port: 8080,
  cors: { origin: process.env.PUBLIC_HOSTNAME }
}
```

### Local Access

* **Localhost**: Services on any port accessible within sandbox
* **Internal testing**: Test APIs on any port from terminal

### Reverse Proxy Pattern

For multi-service deployments on port 8080:

```bash theme={null}
# Install and configure nginx
sudo apt-get update && sudo apt-get install -y nginx

# Configure path-based routing
# /api → localhost:3000
# /app → localhost:8080
```

## Terminal Windows

### Named Windows

Maestro uses named terminal windows to isolate activities:

```
"tests" window    → Running pytest
"server" window   → Development server
"monitor" window  → Watching logs
"build" window    → Compilation
```

**Advantages**:

* Parallel execution
* Process isolation
* Clear organization
* Easy to reference

### Window Behavior

**Reusing windows**:

* Running new command in active window **cancels** previous command
* Use different window names to keep multiple processes running

**Example**:

```
# Start server in "server" window
PORT=8080 npm start

# Test server in "test" window (server keeps running)
curl localhost:8080

# Don't run curl in "server" window - would stop server
```

**Window lifecycle**:

* Created on first use
* Persist across commands
* Auto-close after 600s of inactivity
* Manually close with Close Terminal Windows tool

### Terminal Streaming

When Maestro runs commands, you see real-time output:

* Command execution
* Build progress
* Test results
* Server logs

**Terminal streamer** (UI component):

* Shows while Maestro watches command
* Disappears when command background or complete
* Command may still be running after streamer hidden

## Running Tests and Benchmarks

### Test Execution

**Full test suite**:

```bash theme={null}
pytest                  # Python
npm test               # JavaScript
cargo test             # Rust
go test ./...          # Go
```

**Specific tests**:

```bash theme={null}
pytest tests/unit/test_auth.py
npm test -- auth.test.js
```

**With coverage**:

```bash theme={null}
pytest --cov=src --cov-report=html
npm test -- --coverage
```

**Best practice**: Always run full suite before declaring success.

### Benchmarking

**Standard benchmarking**:

```bash theme={null}
# Create benchmark script
python benchmark.py --iterations 1000

# Compare implementations
./benchmark_redis.sh > redis_results.txt
./benchmark_memcached.sh > memcached_results.txt
diff redis_results.txt memcached_results.txt
```

**Performance profiling**:

```bash theme={null}
# Python
python -m cProfile -o profile.stats script.py
python -m pstats profile.stats

# Node.js
node --prof script.js
node --prof-process isolate-*.log > profile.txt
```

## Web Development in Sandbox

### Starting Servers

**Development servers**:

```bash theme={null}
# React
PORT=8080 npm start

# Flask
flask run --host 0.0.0.0 --port 8080

# FastAPI
uvicorn main:app --host 0.0.0.0 --port 8080
```

**Important**: Bind to \`0.0.0.0:8080 for public access.

### Accessing Services

**From sandbox**:

```bash theme={null}
curl localhost:8080
curl $PUBLIC_HOSTNAME:8080  # Via public URL
```

**From browser**: Use preview URL shown in terminal output

**For testing**:

```bash theme={null}
# API testing
curl -X POST http://localhost:8080/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "test"}'

# Browser testing (via Browser Operator tool)
Maestro can automate browser interactions with your app
```

## Advanced Sandbox Features

### Multiple Sandbox Instances

Create additional sandboxes with custom configurations:

**Standard additional sandbox**:

```python theme={null}
Create Sandbox(
    sandbox_name="secondary",
    cpu_count=4,
    memory_gb=16
)
```

**GPU sandbox** (when available):

```python theme={null}
Create Sandbox(
    sandbox_name="gpu_training",
    gpu_type="A100",
    gpu_count=1
)
```

**Privileged sandbox** (Docker support):

```python theme={null}
Create Sandbox(
    sandbox_name="docker_sandbox",
    privileged=True
)
```

**Docker image sandbox**:

```python theme={null}
Create Sandbox(
    sandbox_name="python_container",
    privileged=True,
    docker_image="python:3.11"
)
```

**SSH connection**:

```python theme={null}
Create Sandbox(
    sandbox_name="remote_system",
    ssh_connection="user@host:22",
    ssh_private_key="credential://SSH_KEY"
)
```

### Use Cases for Multiple Sandboxes

**Isolation**:

* Primary sandbox for development
* Secondary for benchmarking (prevent interference)
* Third for testing different configurations

**Resource allocation**:

* High-memory sandbox for data processing
* GPU sandbox for ML training
* Standard sandbox for testing

**Environment separation**:

* Docker sandbox for containerized workflows
* SSH sandbox for remote systems
* Privileged sandbox for special requirements

## Environment Variables and Secrets

### Secret Activation

**Flow**:

1. Register secrets in Secret Manager (top-right menu)
2. Use `/secrets` command to activate for session
3. Secrets appear as environment variables in sandbox

**Verification**:

```bash theme={null}
echo $AWS_ACCESS_KEY_ID
echo $GITHUB_TOKEN
env | grep CREDENTIAL_NAME
```

### Security

**Isolation guarantees**:

* Secrets never exposed in logs
* Session-scoped only
* Automatic cleanup on session end
* Never visible to other users/sessions

**Best practices**:

* Activate only when needed
* Deactivate sensitive secrets after use
* Review active secrets regularly

## Limitations and Constraints

### Container Constraints

**No nested containers**:

* Cannot run Docker inside default sandbox
* No Podman or other containerization
* Use privileged sandbox if you need Docker support
* Firecracker microVM limitation

**Resource limits**:

* 2 vCPU / 7 GB RAM (default)
* No GPU access (yet, coming soon)
* Shared with support services

### File System Constraints

**Path recommendations**:

* `/home/sandbox/`: Synchronized code and docs
* `/tmp/`: Temporary files, not synchronized
* Other paths: Use for builds, logs, caches

**Size considerations**:

* Large files outside `/home/sandbox/`
* Use `.gitignore` to exclude heavy artifacts
* Prevents slow synchronization

### Network Constraints

**Outbound**: Full internet access (HTTPS, databases, APIs, etc.)

**Inbound**: Only port 8080 exposed publicly

**Solutions for multiple services**:

```bash theme={null}
# Reverse proxy (nginx)
# WebSocket multiplexing
# Path-based routing
```

## Sandbox Tricks and Advanced Usage

### Installing IDEs in Sandbox

**VSCode Server**:

```bash theme={null}
wget https://github.com/coder/code-server/releases/download/v4.x.x/code-server-4.x.x-linux-amd64.tar.gz
tar -xzf code-server-*.tar.gz
cd code-server-*/
./code-server --bind-addr 0.0.0.0:8080

# Access at preview URL - full VSCode in browser
```

**Jupyter Lab**:

```bash theme={null}
pip install jupyterlab
jupyter lab --ip 0.0.0.0 --port 8080 --no-browser

# Access notebooks at preview URL
```

### Ad-Hoc File Downloads

**For large datasets or binary artifacts**:

```bash theme={null}
# Zip desired files
cd /tmp/artifacts
zip -r results.zip *

# Serve with Python
python -m http.server 8080

# Download from preview URL
# Navigate to preview_url:8080/results.zip
```

### Database Development

**SQLite** (local):

```bash theme={null}
# Works out of box
sqlite3 test.db
```

**PostgreSQL** (local instance):

```bash theme={null}
sudo apt-get update && sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl start postgresql
```

**External databases**:

```bash theme={null}
# Connect to cloud databases via secrets
psql postgresql://user:pass@host:5432/db
```

### Accessing External Services

**AWS**:

```bash theme={null}
# After activating AWS secrets
aws s3 ls
aws ec2 describe-instances
```

**GitHub API**:

```bash theme={null}
# After activating GitHub token
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user/repos
```

**Any HTTP API**:

```bash theme={null}
curl -X POST https://api.service.com/endpoint \
  -H "Authorization: Bearer $API_KEY" \
  -d '{"data": "value"}'
```

## Troubleshooting

### Sandbox Not Responding

**Symptoms**:

* Commands timeout
* No terminal output
* UI shows "sandbox unavailable"

**Solutions**:

1. Wait for auto-recovery (sandbox health monitoring active)
2. Use `/reset-sandbox` to force reset
3. Check if processes consumed all resources

### Processes Won't Stop

**Issue**: Server or process won't terminate

**Solutions**:

```bash theme={null}
# Find process
ps aux | grep process_name

# Kill it
kill -9 PID

# Or force reset
```

Use `/reset-sandbox` if `kill` doesn't work.

### Files Not Syncing

**Check**:

1. Is file under `/home/sandbox/`?
2. Is it in `.gitignore`?
3. Is it a synchronized file type?

**Fix**:

* Move files to `/home/sandbox/`
* Remove from `.gitignore` if needed
* Use sandbox tools to inspect non-synchronized files

### Port 8080 Already in Use

**Cause**: Previous server not stopped

**Solutions**:

```bash theme={null}
# Find process on port 8080
sudo lsof -i :8080

# Kill it
sudo kill -9 PID
```

Or start server on different port and proxy from 8080.

## Best Practices

### File Organization

**Good structure**:

```
/home/sandbox/
    src/           # Source code (synced)
    tests/         # Tests (synced)
    docs/          # Documentation (synced)

/tmp/
    build/         # Build artifacts (not synced)
    cache/         # Caches (not synced)
    logs/          # Logs (not synced)
```

### Process Management

**Use named windows** for different activities:

```
"server" → Development server
"tests" → Test execution
"build" → Compilation
"debug" → Debugging sessions
```

**Avoid window reuse** when you want parallel execution.

### Resource Efficiency

**Don't consume unnecessary resources**:

* Stop servers when not needed
* Clean up `/tmp/` periodically
* Avoid infinite loops
* Monitor resource usage with `htop`

### Security Practices

**Secrets**:

* Activate only when needed
* Deactivate after use
* Never commit to files

**Public preview URL**:

* Don't share URLs with sensitive data
* Stop services when done testing
* Use authentication if needed

## Advanced Patterns

### Multi-Stage Testing

```bash theme={null}
# Terminal window "unit"
pytest tests/unit/

# Terminal window "integration"  
pytest tests/integration/

# Terminal window "e2e"
pytest tests/e2e/ --headless
```

All run in parallel, isolated from each other.

### CI/CD Simulation

```bash theme={null}
# Simulate full CI pipeline
./scripts/lint.sh
./scripts/test.sh
./scripts/build.sh
./scripts/deploy-dry-run.sh
```

### Performance Testing

```bash theme={null}
# Load testing with Apache Bench
ab -n 10000 -c 100 http://localhost:8080/api/endpoint

# Or wrk
wrk -t 12 -c 400 -d 30s http://localhost:8080/api/endpoint
```

### Debugging Workflows

**Python**:

```bash theme={null}
# Interactive debugging
python -m pdb script.py

# Or with ipdb
pip install ipdb
python -m ipdb script.py
```

**Node.js**:

```bash theme={null}
node --inspect-brk=0.0.0.0:9229 script.js

# Chrome DevTools at chrome://inspect
```

**GDB** (for C/C++):

```bash theme={null}
gdb ./program
(gdb) break main
(gdb) run
```

## Sandbox Limitations

### What's NOT Available

**No Nested containers**: No Docker/Podman inside default sandbox
**No GPU acceleration**: Not yet available (coming soon)
**No Multiple public ports**: Only 8080 exposed
**No Persistent storage**: Sandbox is ephemeral
**No Rebooting**: Don't reboot - terminates session

### Workarounds

**Need Docker?** Use privileged sandbox mode (request via Create Sandbox tool).

**Need multiple ports?** Use reverse proxy on 8080.

**Need persistence?** Files sync to session (they persist). Sandbox state is ephemeral by design.

**Need GPU?** Coming soon. For now, use external GPU services via API.

## Sandbox vs Local Development

### When to Use Sandbox

**Running tests** - Isolated, reproducible environment
**Benchmarking** - Consistent hardware
**Validating** - Proof code actually works
**Prototyping** - Fast iteration without local setup
**Collaboration** - Same environment for everyone

### When to Use Local

**Heavy IDE usage** - VSCode, IntelliJ, etc.
**GPU-intensive work** - Until sandbox supports GPU
**Large datasets** - If sync would be too slow
**Complex Docker workflows** - Until privileged mode
**Personal preference** - Some developers prefer local

### Hybrid Workflows

**Common pattern**:

1. Maestro implements and validates in sandbox
2. You download changes with `/download-changed`
3. Extract to local project
4. Continue development locally
5. Or create PR directly from session

## Next Steps

Master the sandbox, then explore:

* **[Source Control](getting-started/source-control)**: GitHub integration workflows
* **[Session Strategies](getting-started/session-strategies)**: Patterns for different projects
* **[Advanced Features](getting-started/advanced-features)**: Power user capabilities
* **[Troubleshooting](../reference/troubleshooting)**: Common issues and solutions