quickstart

Install the Python library, create a sandbox, run code inside it. The sandbox is a real container — it boots in about a second and is destroyed when the context exits.

shell shell 
pip install avlabs
main.py python 
from avlabs import Sandbox

with Sandbox("python") as sbx:
    result = sbx.run("print('hello')")
    print(result.stdout)     # hello
    print(result.exit_code)  # 0

# sandbox destroyed on exit — zero residue

python sdk

Sandbox is the core primitive. Every call executes inside the container and comes back as typed data — stdout, stderr, exit code, timing.

sandbox.py python 
from avlabs import Sandbox

sbx = Sandbox.create("linux-sandbox")   # any runtime slug

r = sbx.exec("apt-get install -y curl") # run a shell command
print(r.exit_code, r.duration_ms)

sbx.files.write("/app/main.py", code)   # push files in
out = sbx.files.read("/app/out.txt")    # pull files back

with sbx.terminal() as term:            # interactive pty
    term.send("htop\n")

sbx.destroy()                           # or use a with-block

Sandbox.create(slug)

boot a runtime — python, node, linux, or docker

sbx.run(code)

execute code with the runtime interpreter, capture stdout/stderr

sbx.exec(cmd)

run a shell command inside the container

sbx.files.read / write

move files in and out of the sandbox

sbx.terminal()

attach an interactive pty over websocket

sbx.destroy()

remove the container — automatic with a with-block

typescript sdk

The same surface from Node or the edge — npm i @avlabs/sdk.

main.ts typescript 
import { Sandbox } from "@avlabs/sdk";

const sbx = await Sandbox.create("node");
const res = await sbx.run(`console.log("hello")`);
console.log(res.stdout);   // hello
console.log(res.exitCode); // 0

await sbx.destroy(); // zero residue

rest api

The SDKs sit on four endpoints. Identify the caller with an X-AvLabs-Owner header — one active container per owner.

  • POST /api/sessions

    Create a sandbox. Body: { "slug": "linux-sandbox" }. Returns { id, slug }.

  • DELETE /api/sessions/{id}

    Destroy the session and remove its container. Returns 204.

  • WS /api/sessions/{id}/terminal

    WebSocket attached to a pty inside the container. Binary frames are tty io; frames starting with byte 0x01 carry {cols, rows} resizes.

shell shell 
curl -X POST https://api.avlabs.dev/api/sessions \
  -H "X-AvLabs-Owner: user:you" \
  -H "Content-Type: application/json" \
  -d '{"slug": "linux-sandbox"}'

# → {"id":"7f3a2c1d","slug":"linux-sandbox"}

limits

concurrency

1 container / owner

cpu

2 vCPU

memory

4 GB

ttl

60 min

Sessions are destroyed when the terminal disconnects or the owner starts a new one. Restarts are free and unlimited.