Skip to main content

​
Install

Requirements: macOS Apple Silicon (M1+). Linux support coming soon.
curl -fsSL https://boxlite.ai/boxrun/install | sh
Verify the installation: 
boxrun --version

​
Try it out

1

Create a VM and drop into a shell

boxrun shell ubuntu
On first run, BoxRun automatically starts its server in the background and pulls the image:
Server not running. Starting boxrun serve in background...
Pulling ubuntu:24.04...
root@box_a1b2c3:~#
You’re now inside a full Ubuntu VM. Try uname -a, install packages, run scripts — it’s a real Linux environment with its own kernel. Exit with Ctrl-D or type exit.
2

Create a named box

boxrun create ubuntu --name dev

Box created: box_d4e5f6 (dev)
The box is now running and ready to accept commands.
3

Run commands

boxrun exec dev -- uname -a

Linux box_d4e5f6 6.1.0 #1 SMP PREEMPT aarch64 GNU/Linux

boxrun exec dev -- cat /etc/os-release | head -2

PRETTY_NAME="Ubuntu 24.04 LTS"
NAME="Ubuntu"
4

Transfer files

# Upload a file into the box
boxrun cp ./data.csv dev:/root/data.csv

# Download a file from the box
boxrun cp dev:/root/results.csv ./results.csv
5

List your boxes

boxrun ls

ID                 NAME   STATUS    IMAGE          CPU  MEM     DISK  CREATED
box_d4e5f6         dev    running   ubuntu:24.04   2    1024MB  8G    2025-01-15T10:30:00
6

Manage the lifecycle

boxrun stop dev     # preserves disk
boxrun start dev    # restart with disk intact
boxrun rm dev       # destroy permanently
The server starts automatically on your first command — no need to run boxrun serve manually.

​
Image aliases

BoxRun provides short names for common images: 
boxrun shell python    # python:3.12-slim
boxrun shell node      # node:22-slim
boxrun shell alpine    # alpine:3.20
Run boxrun images to see all aliases. Any valid OCI image reference also works (e.g. python:3.11, nginx:latest).

​
Python SDK

pip install boxrun-sdk

import asyncio
from boxrun_sdk import BoxRunClient

async def main():
    async with BoxRunClient() as client:
        # Create a sandbox
        box = await client.create("ubuntu", name="dev")

        # Run a command
        result = await box.exec(["echo", "hello from BoxRun"])
        print(f"Exit code: {result.exit_code}")

        # Stream output in real time
        async for event in box.exec_stream(["apt-get", "update"]):
            if event.type == "log":
                print(event.data, end="")

        # Upload and download files
        await box.upload("./script.py", "/root/script.py")
        await box.download("/root/output.json", "./output.json")

        await box.remove()

asyncio.run(main())
For one-shot tasks, use client.run() — it creates a box, runs the command, returns output, and destroys the box: 
result = await client.run("python", ["python3", "-c", "print(42)"])
print(result.stdout)  # "42\n"

​
Next steps

CLI Reference

All commands, flags, volume mounts, and shell completions.

Python SDK Reference

Full API, data types, error handling, AI agent patterns.

REST API

HTTP endpoints, WebSocket attach, SSE streaming.

Configuration

Environment variables, resource limits, state directory.