# 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](https://sphere-engine.com/signup)

[Read the docs](https://docs.sphere-engine.com/)

## What a sandbox is

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

1. **Your product** — the agent, interpreter, workspace, or internal tool you ship.
2. **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.
3. **Processes and files** — run commands, read and write the workspace, take back exit codes and logs.
4. **Machine** — start and stop, limits on RAM and disk, a network policy.

## 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**

```python
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)
```

```typescript
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**

```python
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()
```

```typescript
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();
```

## 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.

1. Create an account and copy the API key.
2. Install `sphere_engine_sandboxes` or `@sphere-engine/sandboxes-sdk`.
3. Call the one-shot run or start a session, as in the sample above.

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

Updated: 2026-10-30