The API that runs inside every Baseten sandbox, and the hub templates built on it. See the sandbox docs.
Sandbox Hub is a collection of development environment templates for creating secure, isolated micro VM environments for various application types. Each template provides a pre-configured environment with all necessary tools and dependencies for specific development scenarios.
The hub directory contains the following templates:
A minimal micro VM environment based on Alpine Linux (node:24-alpine) with basic system utilities and networking capabilities. Provides a lightweight, secure foundation for running basic applications and services, featuring a minimal attack surface and optimized resource usage.
Important: The base image includes Node.js 24 and git, but does not include Python or other language runtimes. If you need Python, either use the
py-apptemplate or install it manually:apk add --no-cache python3 py3-pip
A complete Python development environment with pip package manager and common development libraries. Ideal for developing web applications, data science projects, automation scripts, and machine learning applications.
A development environment for TypeScript applications with Node.js runtime and essential development tools. Perfect for developing modern web applications, APIs, and server-side applications with type safety and modern JavaScript features.
A comprehensive development environment for building React Native applications using the Expo framework. Includes Expo CLI, development server, and all necessary tools for cross-platform mobile development.
A managed-host runtime for Omnigent agent sessions. It combines Omnigent's prebuilt host environment with the Baseten sandbox API for process execution, file transfer, streaming, and lifecycle control. The image stays hidden from general Hub discovery because Omnigent selects it automatically, but its image reference is public across workspaces.
- Docker and Docker Compose
- Git
- Make (optional, for using Makefile commands)
-
Clone the repository:
git clone https://github.com/basetenlabs/sandbox.git cd sandbox -
Start the sandbox environment:
docker-compose up -d <template-name>
Create, manage and delete sandboxes with the Baseten SDK (TypeScript, Python, Go), the Baseten CLI or the dashboard:
- Overview
- Manage sandboxes (processes, files, HTTP services)
Each template exposes specific ports for access:
- Base Image: Accessible via port 8080 (sandbox-api)
- Python App: Accessible via ports 8080 (sandbox-api) and 8000 (python-app)
- TypeScript App: Accessible via ports 8080 (sandbox-api) and 3000 (ts-app)
- Expo: Accessible via multiple ports for various Expo services (19000-19006, 8081)
The recommended way to develop on the Sandbox API is to use the dev environment with Docker Compose:
docker-compose up devThis will start the development container with the sandbox-api directory mounted as a volume, enabling hot-reloading through Air for real-time code changes. You can then request your sandbox api on port 8080.
After your server has started (You should see a log: "Starting Sandbox API server on :8080"). You can run this command to check everything is running
curl http://localhost:8080/filesystem/~Go to sandbox-api/integration-tests Detailed documentation
You can upgrade a running sandbox-api instance using the /upgrade endpoint:
curl -X POST http://localhost:8080/upgradeThis will automatically download the latest binary from GitHub Releases, validate it, and restart the server. All running processes are preserved across the upgrade.
You can also specify a version using the SANDBOX_UPGRADE_VERSION environment variable (defaults to latest).
If you prefer to upgrade manually, download the appropriate binary for your platform:
sandbox-api-linux-amd64for Linux x86_64sandbox-api-linux-arm64for Linux ARM64sandbox-api-darwin-amd64for macOS Intelsandbox-api-darwin-arm64for macOS Apple Silicon
Template configurations are defined in template.json files within each template directory. These files specify:
- Template name and display name
- Categories and descriptions
- Memory requirements
- Exposed ports and protocols
- Enterprise features and availability status
Templates can provide iconLight and iconDark URLs for each theme. Keep icon
for clients that use the original field. During publication, the CI trims the
URLs and defaults a missing or blank iconLight to icon, then iconDark if
necessary. A missing or blank iconDark defaults to the resolved iconLight.
Templates without a dark variant use the same image in both themes. Publication
fails before calling the API if none of the three fields contains a nonempty
string, so both theme fields are always populated in published metadata.
See CONTRIBUTING.md for setup, tests, hub templates and releases.
This project is licensed under the MIT License, see LICENSE.
Built with ❤️ by Baseten