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

# Idle timeout

export const SandboxConfigHint = () => {
  if (typeof document === "undefined") {
    return null;
  } else {
    return <Note>Before running the example code in this document, please ensure you have properly configured environment variables. For details, please refer to <a href="/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

You can configure an **idle timeout** for your sandboxes to automatically stop or pause when no active connections are detected. This helps reduce costs by ensuring unused sandboxes are not running indefinitely.

<SandboxConfigHint />

<Note>
  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).
</Note>

## Basic usage

Pass the `idle_timeout` key in the `metadata` object when creating a sandbox. The value is the idle timeout duration in **seconds** (as a string). When no client is connected to the sandbox for the specified duration, the sandbox will be automatically killed or paused.

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

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

  // The sandbox is running...
  // After 60 seconds with no active connections, it will be killed automatically.
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

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

  # The sandbox is running...
  # After 60 seconds with no active connections, it will be killed automatically.
  ```
</CodeGroup>

## How idle timeout works

The idle timeout feature monitors active connections to your sandbox:

1. **When no connections are active** — the sandbox's end time is set to `current_time + idle_timeout_seconds`.
2. **When a connection becomes active again** — the sandbox's end time is restored to the original maximum sandbox lifetime.
3. **When the idle timeout elapses without any reconnection** — the sandbox is killed (or paused if `autoPause` is enabled).

This means a sandbox won't be stopped as long as there is at least one active client connected to it (e.g., via `Sandbox.connect()` or open WebSocket/HTTP connections).

## Pausing instead of killing

By default, an idle sandbox is **killed** when the idle timeout expires. If you want the sandbox to be **paused** instead so you can resume it later, enable the `autoPause` option:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  // Create a sandbox that will be paused (instead of killed) after 60 seconds of inactivity.
  const sandbox = await Sandbox.create({
    metadata: {
      idle_timeout: '60',
    },
    autoPause: true,
  })

  // After 60 seconds of inactivity, the sandbox will be paused.
  // You can resume it later with Sandbox.connect().
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  # Create a sandbox that will be paused (instead of killed) after 60 seconds of inactivity.
  sandbox = Sandbox.create(
      metadata={
          "idle_timeout": "60",
      },
      auto_pause=True,
  )

  # After 60 seconds of inactivity, the sandbox will be paused.
  # You can resume it later with Sandbox.connect().
  ```
</CodeGroup>

<Note>
  When `autoPause` is enabled, the sandbox state transitions to `paused` on idle timeout. You can [connect](/guides/sandbox-connect) to it later to resume execution.
</Note>

## Combining with other metadata

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

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await 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.code_interpreter import Sandbox

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

  print("Sandbox ID:", sandbox.sandbox_id)
  ```
</CodeGroup>

## Timeout constraints

| Constraint  | Value            | Description                                                                                                  |
| ----------- | ---------------- | ------------------------------------------------------------------------------------------------------------ |
| **Minimum** | 30 seconds       | Values below 30 seconds are treated as "idle disabled" to prevent rapid start/stop cycles.                   |
| **Default** | Disabled (0)     | If `idle_timeout` is not specified, the feature is disabled and the sandbox runs until its maximum lifetime. |
| **Maximum** | Sandbox lifetime | The idle timeout cannot exceed the sandbox's configured `timeout` (maximum lifetime).                        |

<Warning>
  If you set `idle_timeout` to a value below the minimum threshold (30 seconds), the idle timeout feature will be **silently disabled** for that sandbox. The sandbox will run until its maximum lifetime expires.
</Warning>

## 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"`:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

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

  // Alternatively, omit idle_timeout entirely:
  const sandbox2 = await Sandbox.create()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

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

  # Alternatively, omit idle_timeout entirely:
  sandbox2 = Sandbox.create()
  ```
</CodeGroup>

## Common use cases

### Short-lived execution tasks

Use a short idle timeout for sandboxes that run one-off tasks and don't need to persist after the client disconnects:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

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

  // Execute code and get results...
  const result = await sandbox.runCode('print("Hello!")')

  // Disconnect — sandbox will be killed after 60 seconds of inactivity.
  await sandbox.kill()
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
      metadata={"idle_timeout": "60"},
  )

  # Execute code and get results...
  result = sandbox.run_code('print("Hello!")')

  # Disconnect — sandbox will be killed after 60 seconds of inactivity.
  sandbox.kill()
  ```
</CodeGroup>

### Long-running interactive sessions

Use a longer idle timeout for sandboxes used in interactive sessions where users may step away temporarily:

<CodeGroup>
  ```js JavaScript & TypeScript icon="js" theme={"system"}
  import { Sandbox } from 'novita-sandbox/code-interpreter'

  const sandbox = await Sandbox.create({
    metadata: { idle_timeout: '600' }, // 10 minutes
    autoPause: true,
  })

  // The sandbox will pause after 10 minutes of inactivity,
  // and can be resumed when the user returns.
  ```

  ```python Python icon="python" theme={"system"}
  from novita_sandbox.code_interpreter import Sandbox

  sandbox = Sandbox.create(
      metadata={"idle_timeout": "600"},  # 10 minutes
      auto_pause=True,
  )

  # The sandbox will pause after 10 minutes of inactivity,
  # and can be resumed when the user returns.
  ```
</CodeGroup>