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

# Pause and resume a sandbox

> Pause a sandbox to stop compute billing while its filesystem and memory are kept, resume it later with the same state, or pause and resume automatically.

Sandbox persistence pauses a sandbox and resumes it later with the same filesystem and memory state. Use it for long-running agent tasks, interactive apps, and workflows that survive idle periods without keeping compute resources active.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## Pause and resume a sandbox

When a sandbox is paused:

* Files created in the sandbox are preserved.
* In-memory state is preserved, including running processes and variables.
* Network connections are interrupted until the sandbox resumes.
* The sandbox remains stored until it is resumed and killed, or killed while it is paused.

**1. Pause the sandbox**

Write a file so the state is visible after the resume, then pause.

```python Python theme={null}
sandbox.commands.run("echo hello > /tmp/message.txt")
sandbox_id = sandbox.sandbox_id
sandbox.pause()

print('Sandbox paused', sandbox_id)
```

```javascript Node.js theme={null}
await sandbox.commands.run('echo hello > /tmp/message.txt')
const sandboxId = sandbox.sandboxId
await sandbox.pause()

console.log('Sandbox paused', sandboxId)
```

**2. Resume the sandbox**

Resume with `ppio.sandbox.connect()`, then read the file back.

```python Python theme={null}
resumed = ppio.sandbox.connect(sandbox_id)
result = resumed.commands.run("cat /tmp/message.txt")
print(result.stdout)

resumed.kill()
```

```javascript Node.js theme={null}
const resumed = await ppio.sandbox.connect(sandboxId)
const result = await resumed.commands.run('cat /tmp/message.txt')
console.log(result.stdout)

await resumed.kill()
```

### Full example

In the CLI example, `<sandbox-id>` is the sandbox ID.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

sandbox.commands.run("echo hello > /tmp/message.txt")
sandbox_id = sandbox.sandbox_id
sandbox.pause()

print('Sandbox paused', sandbox_id)

resumed = ppio.sandbox.connect(sandbox_id)
result = resumed.commands.run("cat /tmp/message.txt")
print(result.stdout)

resumed.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

await sandbox.commands.run('echo hello > /tmp/message.txt')
const sandboxId = sandbox.sandboxId
await sandbox.pause()

console.log('Sandbox paused', sandboxId)

const resumed = await ppio.sandbox.connect(sandboxId)
const result = await resumed.commands.run('cat /tmp/message.txt')
console.log(result.stdout)

await resumed.kill()
```

```bash CLI theme={null}
# Pause a running sandbox (alias: sandbox ps)
ppio sandbox pause <sandbox-id>

# Resume a paused sandbox (alias: sandbox rs)
ppio sandbox resume <sandbox-id>
```

## Set the timeout when resuming

Resuming a sandbox with `connect()` resets its timeout to the SDK default listed on [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md). To set a different timeout, pass it to `connect()`: `timeout` in seconds in Python, `timeoutMs` in milliseconds in Node.js.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create()

connected_sandbox = ppio.sandbox.connect(sandbox.sandbox_id, timeout=60)  # 60 seconds
print('Sandbox connected', connected_sandbox.sandbox_id)

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create()

const connectedSandbox = await ppio.sandbox.connect(sandbox.sandboxId, { timeoutMs: 60 * 1000 })
console.log('Sandbox connected', connectedSandbox.sandboxId)

await sandbox.kill()
```

## Pause and resume automatically

Use lifecycle settings to pause the sandbox automatically after its timeout, and optionally resume it when activity is detected.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create(
    timeout=10 * 60,
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)

sandbox.files.write('/home/user/hello.txt', 'hello from a paused sandbox')
sandbox.pause()

content = sandbox.files.read('/home/user/hello.txt')
print(content)
print(f'State after read: {sandbox.get_info().state}')

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.files.write('/home/user/hello.txt', 'hello from a paused sandbox')
await sandbox.pause()

const content = await sandbox.files.read('/home/user/hello.txt')
console.log(content)
console.log(`State after read: ${(await sandbox.getInfo()).state}`)

await sandbox.kill()
```

## Use auto-resume with a web server

Auto-resume works well for preview environments and web servers.

```python Python theme={null}
from ppio_sandbox import PPIO

ppio = PPIO()
sandbox = ppio.sandbox.create(
    timeout=5 * 60,
    lifecycle={
        'on_timeout': 'pause',
        'auto_resume': True,
    },
)

sandbox.commands.run('python3 -m http.server 3000', background=True)
host = sandbox.get_host(3000)
print(f'Preview URL: https://{host}')

sandbox.kill()
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  timeoutMs: 5 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.commands.run('python3 -m http.server 3000', { background: true })
const host = sandbox.getHost(3000)
console.log(`Preview URL: https://${host}`)

await sandbox.kill()
```

## Common questions

> [accordion] Are paused sandboxes billed?
>
> Paused sandboxes stop CPU and RAM billing. While paused, the filesystem and memory stay in persistent storage. See [How Agent Sandbox billing works](https://docs.ppio.ai/sandbox/billing.md).

> [accordion] How many sandboxes count toward the concurrency limit?
>
> Read `usage` from the [quota API](https://docs.ppio.ai/sandbox/quotas.md) to see how many sandboxes currently count toward the concurrency limit.


## Related topics

- [How Agent Sandbox billing works](https://docs.ppio.ai/sandbox/billing.md)
- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)
- [Secure access to sandbox services](https://docs.ppio.ai/sandbox/secured-access.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.