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

<CodeGroup>
  ```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...
  ```
</CodeGroup>

## Pausing instead of killing

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

<CodeGroup>
  ```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.
  ```
</CodeGroup>

## 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 { 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)
  ```
</CodeGroup>

## 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 { 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()
  ```
</CodeGroup>