> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistent sandboxes

> Create long-running Linux VMs with persistent disks, interactive shells, services, and forks.

A persistent sandbox is a reusable Linux microVM backed by a dedicated Archil disk. Stop and start it
while retaining its disk, or pause and resume it to also preserve CPU and memory state.

Use a persistent sandbox when you need a long-running environment. For an individual command on an
existing disk, use [`disk.exec`](/compute/serverless-sandboxes).

<Note>
  Persistent sandboxes are in preview and may be preempted. Preemption stops running processes and
  discards in-memory state, and recent filesystem changes may be lost.
</Note>

## Create and use a sandbox

Install the TypeScript SDK:

```bash theme={null}
npm install disk
```

Create a sandbox from any public Linux OCI image, then run commands inside it. `baseImage` accepts
Docker Hub shorthand such as `python:3.13` or a full custom image reference such as
`ghcr.io/acme/agent-runtime:v2`. Private registry images are not supported yet. If you need private
image support or another sandbox feature, [contact us](https://archil.com/contact).

```typescript theme={null}
import { Archil } from "disk";

const client = new Archil({
  apiKey: process.env.ARCHIL_API_KEY,
  region: "aws-us-east-1",
});

const sandbox = await client.sandboxes.create({
  name: "agent-workspace",
  baseImage: "python:3.13",
  vcpuCount: 2,
  memSizeMiB: 4096,
  maxTtlSeconds: 3600,
});

const result = await sandbox.exec("python --version && pwd");
console.log(result.stdout);
```

Set `maxTtlSeconds` when creating the sandbox (60 to 28,800 seconds). For now, it cannot be changed
after creation. Each start or resume gets that much powered-on time before Archil shuts down the VM
while preserving its disk. The default is eight hours, and activity does not extend the timer.

## Connect an interactive shell

Pass `pty: true` to stream terminal output and send input:

```typescript theme={null}
const shell = await sandbox.exec("/bin/sh", {
  pty: true,
  onData: (data) => process.stdout.write(data),
});

await shell.sendInput("ls -la\n");
const { exitCode } = await shell.wait();
```

## Expose an application

A sandbox can expose an application at a stable HTTPS URL. Archil starts or resumes an inactive
sandbox when a request reaches the URL.

Create a supervised process with the sandbox service manager:

```typescript theme={null}
const service = await sandbox.exec(
  "archil-sandbox services create web --tcp-port 8080 -- python3 -m http.server 8080",
);
console.log(service.stdout);
```

The command returns the application's hostname. Its process definition survives sandbox restarts.

<Warning>
  Sandbox service hostnames are public. Add authentication before exposing private data or
  privileged actions.
</Warning>

## Manage sandbox lifecycle

Pause preserves CPU and memory. Stop preserves the disk but cold-boots the next time you start:

```typescript theme={null}
await sandbox.pause();
await sandbox.resume();

await sandbox.stop();
await sandbox.start();
```

Fork a sandbox to create an isolated, writable copy of its current environment:

```typescript theme={null}
const fork = await sandbox.fork({ name: "agent-task" });
const result = await fork.exec("python task.py");

await fork.stop();
await fork.delete();
```

The fork's starting state depends on the source:

* **Running:** Archil briefly pauses the source to capture its disk, CPU, and memory state, then resumes it.
* **Paused:** The fork includes the source's disk, CPU, and memory state.
* **Stopped:** The fork includes the source's disk state and cold-boots without memory state.

Forks can be forked again. Delete child forks before deleting their parent.

## Reference

* [TypeScript SDK](/sdks/typescript#persistent-sandboxes)
* [Create a sandbox](/api-reference/sandboxes/create-sandbox)
* [Run a command](/api-reference/sandboxes/exec-in-sandbox)
* [Create an interactive connection](/api-reference/sandboxes/create-sandbox-connection)
* [Fork a sandbox](/api-reference/sandboxes/fork-sandbox)
* [Sandbox lifecycle endpoints](/api-reference/sandboxes/pause-sandbox)