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

# Set or extend a sandbox timeout

> Set the maximum lifetime of a sandbox at creation, extend it while the sandbox runs, choose pause instead of kill, and lift the cap with long-running mode.

Every sandbox has a maximum lifetime, controlled by the `timeout` setting. This page sets that limit when the sandbox is created, extends it later, chooses what happens when it expires, and lifts the cap with long-running mode (A metadata key named long\_running with the string value true; it lifts the timeout cap.). The [sandbox lifecycle](https://docs.ppio.ai/sandbox/lifecycle.md) page lists the defaults that apply when `timeout` is not passed.

> [!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).

## Create a sandbox with a timeout

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

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

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({ timeoutMs: 60_000 })

await sandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox with a 60-second timeout (detached mode), prints the sandbox ID
ppio sandbox create base --timeout 60s -d
```

If `timeout` is not set, the sandbox runs for the SDK default lifetime listed on [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md).

## Extend the timeout

`setTimeout` / `set_timeout` resets how much longer the sandbox stays alive. The value is in seconds in Python and in milliseconds in Node.js. 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(timeout=60)

sandbox.set_timeout(300)
sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({ timeoutMs: 60_000 })

await sandbox.setTimeout(300_000)
await sandbox.kill()
```

```bash CLI theme={null}
# Reset the sandbox timeout to 5 minutes
ppio sandbox set-timeout <sandbox-id> 5m
```

## Choose what happens at timeout

Combine `timeout` with `lifecycle` to choose whether the sandbox is killed or paused when the timeout expires. If `lifecycle` is not passed, the sandbox is killed when the timeout expires.

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

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

sandbox.kill()
```

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

const ppio = new PPIO()
const sandbox = await ppio.sandbox.create({
  timeoutMs: 300_000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.kill()
```

```bash CLI theme={null}
# Pause the sandbox instead of killing it when the timeout expires, and allow auto-resume
ppio sandbox create base --timeout 5m --on-timeout pause --auto-resume -d
```

## Use long-running mode

By default, `timeout` is capped by the team's maximum session duration; see [Quotas and limits](https://docs.ppio.ai/sandbox/quotas.md). Long-running mode lifts the cap, so the `timeout` passed at creation can exceed it. The setting is a `metadata` key named `long_running` with the string value `"true"`. [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md) covers how the setting is inherited by resume, clone, and reset.

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

ppio = PPIO(api_key=os.environ['PPIO_API_KEY'])

# Create a long-running code-interpreter sandbox.
# With long_running enabled, timeout can exceed your tier's cap.
sandbox = ppio.code_interpreter.create(
    metadata={
        'long_running': 'true',
    },
    timeout=86_400,  # 24 hours
)

sandbox.kill()
```

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

const ppio = new PPIO({
  apiKey: process.env.PPIO_API_KEY || '',
})

// Create a long-running code-interpreter sandbox.
// With long_running enabled, timeoutMs can exceed your tier's cap.
const sandbox = await ppio.codeInterpreter.create({
  metadata: {
    long_running: 'true',
  },
  timeoutMs: 86_400_000, // 24 hours
})

await sandbox.kill()
```

```bash CLI theme={null}
# --long-running writes long_running=true to the metadata
ppio sandbox create base --long-running --timeout 24h -d
```

### Seven-day sandbox

Create a long-running sandbox that stays alive for up to 7 days:

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

ppio = PPIO(api_key=os.environ['PPIO_API_KEY'])

# 7 days = 7 * 24 * 60 * 60 seconds
sandbox = ppio.code_interpreter.create(
    metadata={
        'long_running': 'true',
    },
    timeout=604_800,
)

sandbox.kill()
```

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

const ppio = new PPIO({
  apiKey: process.env.PPIO_API_KEY || '',
})

// 7 days = 7 * 24 * 60 * 60 * 1000 ms
const sandbox = await ppio.codeInterpreter.create({
  metadata: {
    long_running: 'true',
  },
  timeoutMs: 604_800_000,
})

await sandbox.kill()
```

```bash CLI theme={null}
# Create a long-running sandbox that stays alive for up to 7 days
ppio sandbox create base --long-running --timeout 168h -d
```

## Timeout settings

> [tab] Python
>
> **timeout** `int`
>
> Sandbox lifetime in seconds. Optional.
>
> **lifecycle** `SandboxLifecycle`
>
> What happens when the timeout expires.
>
> **properties**
>
> **on\_timeout** `string` (default: kill)
>
> `kill` or `pause`.
>
> **auto\_resume** `bool`
>
> `True` or `False`.
>
> **metadata** `dict`
>
> Custom metadata for the sandbox.
>
> **properties**
>
> **long\_running** `string`
>
> Set to `"true"` to lift the timeout cap.
>
> **set\_timeout** `int`
>
> New lifetime in seconds for a running sandbox.

> [tab] Node.js
>
> **timeoutMs** `number`
>
> Sandbox lifetime in milliseconds. Optional.
>
> **lifecycle** `SandboxLifecycle`
>
> What happens when the timeout expires.
>
> **properties**
>
> **onTimeout** `string` (default: kill)
>
> `kill` or `pause`.
>
> **autoResume** `boolean`
>
> `true` or `false`.
>
> **metadata** `object`
>
> Custom metadata for the sandbox.
>
> **properties**
>
> **long\_running** `string`
>
> Set to `"true"` to lift the timeout cap.
>
> **setTimeout** `number`
>
> New lifetime in milliseconds for a running sandbox.


## Related topics

- [Pause and resume a sandbox](https://docs.ppio.ai/sandbox/pause-resume.md)
- [Configure an idle timeout](https://docs.ppio.ai/sandbox/idle-timeout.md)
- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)


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