Skip to main content

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.

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: 
sudo apt-get update
sudo apt-get install -y package-name
Python packages: 
pip install package-name  # Installs to default venv
JavaScript packages: 
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: 
# Build artifacts
/build/
/dist/

# Dependencies
node_modules/
.venv/

# Logs
*.log
/logs/
Use temporary directories for large outputs: 
# 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: 
# 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: 
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: 
# 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: 
pytest                  # Python
npm test               # JavaScript
cargo test             # Rust
go test ./...          # Go
Specific tests: 
pytest tests/unit/test_auth.py
npm test -- auth.test.js
With coverage: 
pytest --cov=src --cov-report=html
npm test -- --coverage
Best practice: Always run full suite before declaring success.

​
Benchmarking

Standard benchmarking: 
# 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: 
# 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: 
# 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: 
curl localhost:8080
curl $PUBLIC_HOSTNAME:8080  # Via public URL
From browser: Use preview URL shown in terminal output For testing: 
# 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: 
Create Sandbox(
    sandbox_name="secondary",
    cpu_count=4,
    memory_gb=16
)
GPU sandbox (when available): 
Create Sandbox(
    sandbox_name="gpu_training",
    gpu_type="A100",
    gpu_count=1
)
Privileged sandbox (Docker support): 
Create Sandbox(
    sandbox_name="docker_sandbox",
    privileged=True
)
Docker image sandbox: 
Create Sandbox(
    sandbox_name="python_container",
    privileged=True,
    docker_image="python:3.11"
)
SSH connection: 
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: 
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: 
# Reverse proxy (nginx)
# WebSocket multiplexing
# Path-based routing

​
Sandbox Tricks and Advanced Usage

​
Installing IDEs in Sandbox

VSCode Server: 
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: 
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: 
# 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): 
# Works out of box
sqlite3 test.db
PostgreSQL (local instance): 
sudo apt-get update && sudo apt-get install -y postgresql postgresql-contrib
sudo systemctl start postgresql
External databases: 
# Connect to cloud databases via secrets
psql postgresql://user:pass@host:5432/db

​
Accessing External Services

AWS: 
# After activating AWS secrets
aws s3 ls
aws ec2 describe-instances
GitHub API: 
# After activating GitHub token
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user/repos
Any HTTP API: 
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: 
# 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: 
# 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

# 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

# Simulate full CI pipeline
./scripts/lint.sh
./scripts/test.sh
./scripts/build.sh
./scripts/deploy-dry-run.sh

​
Performance Testing

# 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: 
# Interactive debugging
python -m pdb script.py

# Or with ipdb
pip install ipdb
python -m ipdb script.py
Node.js: 
node --inspect-brk=0.0.0.0:9229 script.js

# Chrome DevTools at chrome://inspect
GDB (for C/C++): 
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: