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

# Tempo limite de ociosidade

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="/docs/pt-BR/guides/sandbox-your-first-agent-sandbox#configure-environment-variables">Configure Environment Variables</a>.</Note>;
  }
};

Você pode configurar um **tempo limite de ociosidade** para seus ambientes sandbox pararem ou pausarem automaticamente quando nenhuma conexão ativa for detectada. Isso ajuda a reduzir custos, garantindo que ambientes sandbox não utilizados não fiquem em execução indefinidamente.

<SandboxConfigHint />

<Note>
  O tempo limite de ociosidade é configurado por meio do campo `metadata` ao criar um sandbox. A chave é `idle_timeout` e o valor é o número de segundos (como uma string).
</Note>

## Uso básico

Passe a chave `idle_timeout` no objeto `metadata` ao criar um sandbox. O valor é a duração do tempo limite de ociosidade em **segundos** (como uma string). Quando nenhum cliente estiver conectado ao sandbox pela duração especificada, o sandbox será encerrado ou pausado automaticamente.

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

## Como o tempo limite de ociosidade funciona

O recurso de tempo limite de ociosidade monitora conexões ativas com o seu sandbox:

1. **Quando nenhuma conexão está ativa** — o horário de término do sandbox é definido como `current_time + idle_timeout_seconds`.
2. **Quando uma conexão volta a ficar ativa** — o horário de término do sandbox é restaurado para o tempo de vida máximo original do sandbox.
3. **Quando o tempo limite de ociosidade transcorre sem nenhuma reconexão** — o sandbox é encerrado (ou pausado se `autoPause` estiver habilitado).

Isso significa que um sandbox não será interrompido enquanto houver pelo menos um cliente ativo conectado a ele (por exemplo, via `Sandbox.connect()` ou conexões WebSocket/HTTP abertas).

## Pausar em vez de encerrar

Por padrão, um sandbox ocioso é **encerrado** quando o tempo limite de ociosidade expira. Se você quiser que o sandbox seja **pausado** em vez disso para poder retomá-lo posteriormente, habilite a opção `autoPause`:

<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>
  Quando `autoPause` está habilitado, o estado do sandbox muda para `paused` no tempo limite de ociosidade. Você pode [conectar](/docs/pt-BR/guides/sandbox-connect) a ele posteriormente para retomar a execução.
</Note>

## Combinar com outros metadados

A chave de metadados `idle_timeout` pode ser combinada com outras chaves de metadados que você já utiliza:

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

## Restrições de tempo limite

| Restrição  | Valor                    | Descrição                                                                                                              |
| ---------- | ------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| **Mínimo** | 30 segundos              | Valores abaixo de 30 segundos são tratados como "ociosidade desabilitada" para evitar ciclos rápidos de início/stop.   |
| **Padrão** | Desabilitado (0)         | Se `idle_timeout` não for especificado, o recurso é desabilitado e o sandbox é executado até seu tempo de vida máximo. |
| **Máximo** | Tempo de vida do sandbox | O tempo limite de ociosidade não pode exceder o `timeout` configurado do sandbox (tempo de vida máximo).               |

<Warning>
  Se você definir `idle_timeout` como um valor abaixo do limite mínimo (30 segundos), o recurso de tempo limite de ociosidade será **silenciosamente desabilitado** para esse sandbox. O sandbox será executado até que seu tempo de vida máximo expire.
</Warning>

## Desabilitar o tempo limite de ociosidade

Para desabilitar explicitamente o tempo limite de ociosidade para um sandbox, basta omitir a chave `idle_timeout` dos metadados ou defini-la como `"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>

## Casos de uso comuns

### Tarefas de execução de curta duração

Use um tempo limite de ociosidade curto para sandboxes que executam tarefas pontuais e não precisam persistir depois que o cliente se desconecta:

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

### Sessões interativas de longa duração

Use um tempo limite de ociosidade mais longo para sandboxes usados em sessões interativas nas quais os usuários podem se ausentar temporariamente:

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