Sandboxes

Overview

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.

Table of Contents

• Templates
• Prerequisites
• Installation
• Usage
• Configuration
• Contributing
• License
• Support

Templates

The hub directory contains the following templates:

Base Image

A minimal micro VM environment based on Alpine Linux (node:22-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 22 and git, but does not include Python or other language runtimes. If you need Python, either use the py-app template or install it manually:

apk add --no-cache python3 py3-pip

Python App

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.

TypeScript App

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.

Expo

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.

Prerequisites

• Docker and Docker Compose
• Git
• Make (optional, for using Makefile commands)

Installation

1. Clone the repository:

   git clone https://github.com/blaxel-ai/sandbox.git
   cd sandbox

2. Start the sandbox environment:

   docker-compose up -d <template-name>

Usage

Blaxel SDK

Languages:

• Python
• Typescript

You can find sample on how to create/retrieve/remove a Sandbox at this url: https://docs.blaxel.ai/Sandboxes/Overview Sandbox operations:

• Process
• Filesystem

Accessing template environments

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)

Developing with the Sandbox API

Development server

The recommended way to develop on the Sandbox API is to use the dev environment with Docker Compose:

docker-compose up dev

This 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/~

Test server

Go to sandbox-api/integration-tests Detailed documentation

Upgrading the Sandbox API

You can upgrade a running sandbox-api instance using the /upgrade endpoint:

curl -X POST http://localhost:8080/upgrade

This 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-amd64 for Linux x86_64
• sandbox-api-linux-arm64 for Linux ARM64
• sandbox-api-darwin-amd64 for macOS Intel
• sandbox-api-darwin-arm64 for macOS Apple Silicon

Configuration

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

Contributing

We welcome contributions to Sandbox Hub! Please follow these steps:

1. Fork the repository
2. Create a new branch (git checkout -b feature/new-template)
3. Make your changes
4. Commit your changes (git commit -m 'Add new template')
5. Push to the branch (git push origin feature/new-template)
6. Open a Pull Request

Creating a New Template

To create a new template:

1. Create a new directory in the hub folder with your template name
2. Add a Dockerfile that sets up the required environment
3. Create a template.json file with the template configuration
4. Add your template to docker-compose.yaml
5. Test your template
6. Submit a pull request with your new template

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For support, please:

• Open an issue on GitHub
• Contact the Blaxel team at support@blaxel.ai
• Join our community channels

---

Built with ❤️ by Blaxel