Practical workflows for leveraging Maestro’s execution environment. This guide shows you how to use the sandbox for testing, running servers, and validating your code. For architectural details about the sandbox, see Explanation: Sandbox Architecture.

Run Tests and Validation

Execute Test Suites

Ask Maestro to run your tests:
"Run the full test suite using pytest"

"Run all JavaScript tests with npm test"

"Run tests in the tests/unit directory only"
For specific tests:
"Run only the authentication tests in tests/unit/test_auth.py"

"Run the integration tests and show me detailed output"

Get Test Coverage

"Run pytest with coverage reporting. Show me which lines aren't covered."

"Run the test suite with coverage. I want to see coverage for the auth module specifically."

"Generate an HTML coverage report and show me the overall percentage."

Validate with Different Conditions

"Run tests with environment variable DEBUG=true"

"Test the application with DATABASE_URL pointing to the test database"

"Run tests under Python 3.11 to verify compatibility"

Start and Manage Servers

Development Servers

Ask Maestro to start servers on port 8080 (the only publicly exposed port):
"Start the React development server on port 8080"

"Run the Flask app on port 8080, bound to all interfaces"

"Start uvicorn serving the FastAPI app on port 8080"
Maestro will bind to 0.0.0.0:8080 so the server is publicly accessible via the preview URL.

Check Server Status

"Check if a server is running on port 8080"

"Show me what processes are using port 8080"

"Test the API server by making a request to localhost:8080/health"

Manage Long-Running Processes

Use named terminal windows to run multiple servers:
"Start the API server in a terminal window called 'api-server'"

"In a new terminal window called 'worker', start the background worker process"

"Start the Redis server in a window called 'redis'"
Each window runs independently. Starting a new command in the same window cancels the previous command.

Stop Services

"Stop the server running on port 8080"

"Kill the process using port 8080"

"Close the terminal window called 'api-server'"

Install and Manage Packages

System Packages

Ask Maestro to install Ubuntu packages:
"Install PostgreSQL in the sandbox"

"Install nginx using apt-get"

"Install python3-pip and python3-dev packages"

Python Packages

"Install the requests package using pip"

"Install all requirements from requirements.txt"

"Install pytest and pytest-cov for testing"
The sandbox uses the system Python with a default virtualenv, so no need to create separate environments.

JavaScript Packages

"Install express using npm"

"Install all dependencies from package.json using npm install"

"Install typescript as a dev dependency"

Work with Files

Check File Locations

"Check if myfile.py exists in the sandbox"

"Show me the directory structure under /home/sandbox/src"

"List all Python files in the project"

Verify File Contents

"Show me the contents of config.yaml in the sandbox"

"Display the last 20 lines of logs/app.log"

"Check the file permissions on scripts/deploy.sh"

Move or Copy Files

"Copy test_data.json to /tmp for the benchmark"

"Move build artifacts to /tmp/build directory"

"Create a backup of database.sqlite in /tmp"

Run Benchmarks and Performance Tests

Execute Benchmarks

"Run benchmark.py with 1000 iterations and show results"

"Compare performance between implementation A and B using bench_compare.sh"

"Run the load test against localhost:8080 with 100 concurrent requests"

Profile Code

"Profile the main.py script and show me the top 10 bottlenecks"

"Run the API with profiling enabled and identify slow functions"

"Profile memory usage during the data import process"

Monitor Resources

"Show me CPU and memory usage in the sandbox"

"Check if any processes are consuming excessive resources"

"Monitor disk space usage in /home/sandbox"

Debug Applications

Check Logs and Output

"Show me the last 50 lines of the application log"

"Display any error messages from the last server run"

"Check stderr output from the failing test"

Test Network Connectivity

"Test if the database is reachable at localhost:5432"

"Check if the external API at api.example.com is responding"

"Verify the Redis server is accepting connections"

Inspect Running Processes

"Show me all running Python processes"

"Check what's running in the terminal window called 'worker'"

"Display the environment variables for the running API server"

Access Services

Use the Preview URL

The sandbox exposes port 8080 publicly. Ask Maestro to show you the URL:
"What's the preview URL for this sandbox?"

"Show me the public URL where I can access the running server"
Then access it in your browser. Ask Maestro to configure servers for the public hostname:
"Configure the Vite dev server to accept connections from the public preview hostname"

"Set up CORS to allow requests from the preview URL"

Test APIs

"Make a POST request to localhost:8080/api/users with test user data"

"Test the authentication endpoint by sending valid credentials"

"Call the /health endpoint and show me the response"

Browser Testing

For visual testing:
"Take a screenshot of the running application at the preview URL"

"Open the preview URL in a browser and click the login button"

"Navigate to /dashboard on the running app and verify it loads"

Handle Build Artifacts

Run Builds

"Build the production bundle using npm run build"

"Compile the Go application"

"Run the webpack build for production"

Manage Build Output

Keep build artifacts outside synchronized paths:
"Put build output in /tmp/build to avoid syncing large files"

"Configure webpack to output to /tmp/dist"

"Set the build directory to /tmp/artifacts"

Create Archives

"Zip all files in the dist directory for download"

"Create a tarball of the built application in /tmp"

"Package the release artifacts into a zip file"

Work with Databases

Local Databases

"Start PostgreSQL in the sandbox"

"Create a test database called myapp_test"

"Connect to the database and show me the user table schema"

External Databases

After activating database secrets (see How to Connect External Services):
"Connect to the production database using the DATABASE_URL secret"

"Query the users table to check if test data exists"

"Run the migration script against the staging database"

Troubleshoot Issues

Sandbox Not Responding

"Check if the sandbox is responding"

"Show me sandbox resource usage - is something consuming all resources?"
If stuck, use:
/reset-sandbox
This forces a restart. Your files are preserved (they’re in session storage), but running processes stop.

Processes Won’t Stop

"Find the process using port 8080 and kill it"

"Show all Python processes and kill the one running worker.py"

"Force-close the terminal window called 'stuck-server'"

Port Already in Use

"Check what's using port 8080"

"Kill the process on port 8080 so I can start my server"
Or start your server on a different local port and proxy from 8080:
"Start the server on port 3000, then set up nginx to proxy from 8080 to 3000"

Files Not Syncing

Check if files are in synchronized locations:
"Is myfile.py in the /home/sandbox directory?"

"Check if the file is listed in .gitignore"

"Show me the contents of myfile.py as it appears in the sandbox"
Move files to synchronized paths:
"Move build output to /home/sandbox/dist so it syncs"

Package Installation Fails

"Update the apt package database then install \{package\}"

"Check if \{package\} is available in Ubuntu repositories"

"Install the Python package using sudo pip install if permission denied"

Best Practices

File Organization

Keep source code under /home/sandbox/ (synced):
"Put source code in /home/sandbox/src"
"Keep tests in /home/sandbox/tests"
"Store docs in /home/sandbox/docs"
Keep temporary files elsewhere (not synced):
"Put build artifacts in /tmp/build"
"Use /tmp for large cache files"
"Write logs to /tmp/logs"

Process Management

Use named terminal windows for organization:
"Run the server in window 'server'"
"Run tests in window 'tests'"
"Start background worker in window 'worker'"
Don’t reuse windows if you need multiple processes running:
"Start server in 'server' window"
"Run tests in 'tests' window"  ← Different window, server keeps running

Resource Efficiency

"Kill any idle processes consuming memory"

"Check disk usage and clean up /tmp if it's large"

"Stop the development server when not actively using it"

Next Steps

Master sandbox usage, then explore: