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

# Configure an idle timeout

> Stop or pause a sandbox automatically when no client is connected, by setting the idle_timeout metadata key, and combine it with other metadata keys.

An idle timeout stops or pauses a sandbox when no active connection is detected for a configured duration. It is separate from the sandbox [timeout](https://docs.ppio.ai/sandbox/timeout.md), which counts down regardless of activity. The value is stored in the sandbox metadata, so it is set at creation and appears beside the other metadata keys.

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

## Set an idle timeout

The idle timeout is configured through the `metadata` field when a sandbox is created. The key is `idle_timeout` and the value is the number of seconds, as a string.

**idle\_timeout** `string`

Metadata key. The number of seconds, as a string.

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

ppio = PPIO()

# Create a sandbox that will be automatically killed after 60 seconds of inactivity.
sandbox = ppio.sandbox.create(
    metadata={
        'idle_timeout': '60',
    },
)

# The sandbox is running...

sandbox.kill()
```

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

const ppio = new PPIO()

// Create a sandbox that will be automatically killed after 60 seconds of inactivity.
const sandbox = await ppio.sandbox.create({
  metadata: {
    idle_timeout: '60',
  },
})

// The sandbox is running...

await sandbox.kill()
```

```bash CLI theme={null}
# Create a sandbox that will be automatically killed after 60 seconds of inactivity (detached mode).
ppio sandbox create base --idle-timeout 60 -d
```

## Pause instead of kill

To pause the sandbox instead, so it can be resumed later, enable the auto-pause option (`auto_pause=True` in Python, `autoPause: true` in Node.js).

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

ppio = PPIO()

sandbox = ppio.sandbox.create(
    metadata={
        'idle_timeout': '60',
    },
    auto_pause=True,
)

# After 60 seconds of inactivity, the sandbox will be paused.
```

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

const ppio = new PPIO()

const sandbox = await ppio.sandbox.create({
  metadata: {
    idle_timeout: '60',
  },
  autoPause: true,
})

// After 60 seconds of inactivity, the sandbox will be paused.
```

```bash CLI theme={null}
# --on-timeout pause is equivalent to the SDK's auto_pause option
ppio sandbox create base --idle-timeout 60 --on-timeout pause -d
```

## Combine with other metadata

The `idle_timeout` key can be combined with other metadata keys already in use.

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

ppio = PPIO()

sandbox = ppio.sandbox.create(
    metadata={
        'idle_timeout': '120',
        'env': 'production',
        'user_id': 'user-123',
    },
)

print('Sandbox ID:', 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({
  metadata: {
    idle_timeout: '120',
    env: 'production',
    userId: 'user-123',
  },
})

console.log('Sandbox ID:', sandbox.sandboxId)

await sandbox.kill()
```

```bash CLI theme={null}
# --idle-timeout can be combined with other --metadata keys
ppio sandbox create base --idle-timeout 120 \
  --metadata env=production \
  --metadata user_id=user-123 \
  -d
```

## Disable the idle timeout

To disable the idle timeout for a sandbox, omit the `idle_timeout` key from the metadata, or set it to `0`.

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

ppio = PPIO()

# No idle timeout — sandbox runs until its maximum lifetime.
sandbox = ppio.sandbox.create(
    metadata={
        'idle_timeout': '0',
    },
)

# Alternatively, omit idle_timeout entirely.
sandbox2 = ppio.sandbox.create()

sandbox.kill()
sandbox2.kill()
```

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

const ppio = new PPIO()

// No idle timeout — sandbox runs until its maximum lifetime.
const sandbox = await ppio.sandbox.create({
  metadata: {
    idle_timeout: '0',
  },
})

// Alternatively, omit idle_timeout entirely.
const sandbox2 = await ppio.sandbox.create()

await sandbox.kill()
await sandbox2.kill()
```

```bash CLI theme={null}
# No idle timeout — sandbox runs until its maximum lifetime.
ppio sandbox create base --idle-timeout 0 -d

# Alternatively, omit --idle-timeout entirely.
ppio sandbox create base -d
```

> [!NOTE]
>
> The idle timeout is stored in the sandbox metadata under the `idle_timeout` key, beside any other metadata keys of the sandbox. See [List and filter sandboxes](https://docs.ppio.ai/sandbox/list.md).


## Related topics

- [Sandbox lifecycle and states](https://docs.ppio.ai/sandbox/lifecycle.md)
- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)
- [Query sandbox lifecycle events](https://docs.ppio.ai/sandbox/events.md)


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