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

# Idle timeout

You can configure an idle timeout for your sandboxes to automatically stop or pause when no active connections are detected.

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

## Basic usage

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

// The sandbox is running...
```

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()

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

# The sandbox is running...
```

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

## Pausing instead of killing

If you want the sandbox to be paused instead so you can resume it later, enable the auto-pause option.

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

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

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()

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

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

```bash CLI icon="terminal" theme={"system"}
# --on-timeout pause is equivalent to the SDK's auto_pause option
novita sandbox create base --idle-timeout 60 --on-timeout pause -d
```

## Combining with other metadata

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

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

const sandbox = await novita.sandbox.create({
  metadata: {
    idle_timeout: '120',
    env: 'production',
    userId: 'user-123',
  },
})

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

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()

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

print('Sandbox ID:', sandbox.sandbox_id)
```

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

## Disabling idle timeout

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

```js JavaScript & TypeScript icon="js" theme={"system"}
import { Novita } from 'novita-sandbox'

const novita = new Novita()

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

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

```python Python icon="python" theme={"system"}
from novita_sandbox import Novita

novita = Novita()

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

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

```bash CLI icon="terminal" theme={"system"}
# No idle timeout — sandbox runs until its maximum lifetime.
novita sandbox create base --idle-timeout 0 -d

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


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