Sphere Engine Sandboxes

Isolated Linux machines,
on demand, from your code.

One-shot runs and long-lived sessions. Your SDK provisions the machine, watches it, and takes the artifacts out. Further machines come from your code. You do not run the fleet.

Start Read the docs

An isolated Linux machine provisioned on demand from your application code.

What a sandbox is

A sandbox is a Linux machine your application controls. You build the product on top.

Your product — the agent, interpreter, workspace, or internal tool you ship.
What the image includes — interpreters and other programs shipped in that image. A browser or a desktop only when you picked an image that contains them.
Processes and files — run commands, read and write the workspace, take back exit codes and logs.
Machine — start and stop, limits on RAM and disk, a network policy.

Four descriptive layers of a Sphere Engine sandbox from your product down to the machine.

A second for a snippet.
An afternoon for an agent.

Same product, two lifecycles.

One-shot run

Create a machine, run one command, take stdout, stderr, the exit code, and resource use, then tear it down. Fits a snippet that must not keep state.

client.run.execute(…)

Session

Start a sandbox, run many commands, keep files between them, stop when the work is done. Fits an agent loop or a workspace that has to stay up.

start → exec → stop

A CLI covers the same lifecycle when you are debugging.

one-shot

from sphere_engine_sandboxes import Client

client = Client(token="YOUR_API_KEY")

result = client.run.execute(
    image="ubuntu-26.04-med",
    command=["python3", "-c", "print('hello')"],
)
print(result.exit_code, result.stdout)

import { Client } from "@sphere-engine/sandboxes-sdk";

const client = new Client({ token: "YOUR_API_KEY" });

const result = await client.run.execute({
  image: "ubuntu-26.04-med",
  command: "echo hello",
});
console.log(result.exit_code, result.stdout);

session

from sphere_engine_sandboxes import Client

client = Client(token="YOUR_API_KEY")

sb = client.sandboxes.of("job-42")
sb.start(image="ubuntu-26.04-med")
sb.exec(command=["python3", "-c", "print('still here')"])
sb.stop()

import { Client } from "@sphere-engine/sandboxes-sdk";

const client = new Client({ token: "YOUR_API_KEY" });

const sb = client.sandboxes.of("job-42");
await sb.start({ image: "ubuntu-26.04-med" });
await sb.exec({ command: ["python3", "-c", "print('still here')"] });
await sb.stop();

Quickstart

From an API key to a first run

The SDK is a thin client over the Sandboxes API. Python and TypeScript expose the same objects: a client, a sandbox, files, and a result.

main.py

# Copy the key from your account.
# Set it in your terminal.

export SPHERE_API_KEY="your_api_key"

The example in step 3 reads this variable.

# Install the Python SDK

pip install sphere_engine_sandboxes

Next: run your first snippet.

# Install the TypeScript SDK

npm install @sphere-engine/sandboxes-sdk

Next: run your first snippet.

import os
from sphere_engine_sandboxes import Client

client = Client(
    api_key=os.environ["SPHERE_API_KEY"]
)

result = client.run(
    language="python",
    code='print("Hello, Sphere!")',
)

print(result.stdout)

Expected stdoutHello, Sphere!

import { Client } from
  "@sphere-engine/sandboxes-sdk";

const client = new Client({
  apiKey: process.env.SPHERE_API_KEY,
});

const result = await client.run({
  language: "python",
  code: 'print("Hello, Sphere!")',
});

console.log(result.stdout);

Expected stdoutHello, Sphere!

Illustrative SDK example · Python 03 / 03

The CLI follows the same lifecycle for local debugging.

Start from a ready image, or bring the stack your project already uses.

Launch a prepared Linux image. Inside the machine, install the language packages the job needs. Outbound traffic follows the network policy you set. Large inputs can be mounted read-only. Outputs come back as files or logs.

Ready images for everyday Linux workloads
Dependencies installed in the sandbox when the job needs them
Outbound network only where your policy allows it

Start from a ready Linux image or install your stack inside the sandbox, including from a container registry.

Isolated Linux machines,on demand, from your code.