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

# Persistência legada do Sandbox

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

<Warning>
  Esta página legada é mantida para usuários que ainda usam a linha 1.x ou beta do SDK. Novas integrações com o SDK 2.x devem seguir a documentação atual do Sandbox.
</Warning>

A persistência da sandbox permite pausar sua sandbox e retomá-la posteriormente a partir do mesmo estado em que ela estava quando você a pausou.

Isso inclui não apenas o estado do sistema de arquivos da sandbox, mas também a memória da sandbox. Isso significa todos os processos em execução, variáveis carregadas, dados etc.

<SandboxConfigHint />

<Warning>
  Observe:

  * Leva cerca de 4 segundos por 1 GB de RAM para pausar a sandbox.
  * Leva cerca de 1 segundo para retomar a sandbox.
  * Os dados de uma sandbox pausada são mantidos permanentemente até que você chame explicitamente o método `kill`.
</Warning>

## Pausando a sandbox

Quando você pausa uma sandbox, tanto o <Link href="/docs/pt-BR/guides/sandbox-filesystem">sistema de arquivos</Link> da sandbox quanto o estado da memória serão salvos. Isso inclui todos os arquivos no sistema de arquivos da sandbox e todos os processos em execução, variáveis carregadas, dados etc.

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

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

<Warning>
  **Observação: breve período de transição após pausar**

  Pausar é uma operação assíncrona. Depois de chamar `beta_pause()`, a sandbox é pausada em segundo plano.

  Durante esse período de transição, antes que a pausa seja concluída:

  * **Operações somente leitura** (por exemplo, `get_info`, `list`): retornam normalmente; o status é exibido como `paused`
  * **Operações de execução** (por exemplo, `commands.run`, acessar URLs públicas da sandbox): retornarão erros — esse é o comportamento esperado. Aguarde a conclusão da pausa antes de tentar novamente (o tempo varia conforme o tamanho da memória, veja a observação acima)
  * **Operação de retomada** (`connect`): aguarda automaticamente a conclusão da pausa antes de retomar a sandbox — não é necessário fazer polling manual nem tentar novamente
</Warning>

## Retomando a sandbox

Quando você retoma uma sandbox, ela estará no mesmo estado em que estava quando você a pausou.
Isso significa que todos os arquivos no sistema de arquivos da sandbox serão restaurados e todos os processos em execução, variáveis carregadas, dados etc. serão restaurados.

<Tip>
  Se você chamar `connect()` imediatamente após chamar `beta_pause()`, `connect()` aguarda automaticamente a conclusão da pausa antes de retomar a sandbox. Não é necessário fazer polling manual — todo o processo é transparente para o chamador.
</Tip>

<Warning>
  Se você tentar retomar uma sandbox que foi destruída ou não existe:

  * O JavaScript SDK lançará `NotFoundError`
  * O Python SDK lançará `NotFoundException`
</Warning>

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

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  // You can save the sandbox ID in your database
  // to resume the sandbox later
  const result = await sandbox.betaPause()
  console.log('Sandbox paused', sandbox.sandboxId, result)

  // Resume the sandbox.
  // Even if called before pausing completes, connect() automatically waits for the pause to finish.
  const resumedSandbox = await sandbox.connect()
  console.log('Sandbox resumed', resumedSandbox.sandboxId)

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.create()
  print('Sandbox created', sandbox.sandbox_id)

  # Pause the sandbox.
  # You can save the sandbox ID in your database
  # to resume the sandbox later
  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # Resume the sandbox.
  # Even if called before pausing completes, connect() automatically waits for the pause to finish.
  connectedSandbox = sandbox.connect()
  print('Sandbox resumed', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Listando sandboxes pausadas

Você pode listar todas as sandboxes pausadas chamando o método `Sandbox.list` e fornecendo o parâmetro de consulta `state`.
Mais informações sobre como usar o método podem ser encontradas em [List Sandboxes](/docs/pt-BR/guides/sandbox-list).

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

  const sandbox = await Sandbox.create()

  // List all paused sandboxes.
  const paginator = Sandbox.list({ query: { state: ['paused'] } })

  // Get all paused sandboxes.
  const sandboxes: SandboxInfo[] = []
  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    sandboxes.push(...items)
  }

  console.log('all paused sandboxes', sandboxes)

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.create()

  sandbox.beta_pause()
  print('Sandbox paused', sandbox.sandbox_id)

  # List all paused sandboxes.
  paginator = Sandbox.list(query=SandboxQuery(state=[SandboxState.PAUSED]))

  # Get all paused sandboxes.
  sandboxes: list[SandboxInfo] = []
  while paginator.has_next:
    items = paginator.next_items()
    sandboxes.extend(items)

  print('all paused sandboxes', sandboxes)

  sandbox.kill()
  ```
</CodeGroup>

## Removendo sandboxes pausadas

Você pode remover sandboxes pausadas chamando o método `kill` na instância da sandbox.

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

  const sandbox = await Sandbox.create()
  console.log('Sandbox created', sandbox.sandboxId)

  // Pause the sandbox.
  await sandbox.betaPause()

  // Kill the paused sandbox.
  await sandbox.kill()
  ```

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

  sandbox = Sandbox.create()

  # Pause the sandbox.
  sandbox.beta_pause()

  # Kill the paused sandbox.
  sandbox.kill()
  ```
</CodeGroup>

## Tempo limite da sandbox

Quando você retoma uma sandbox, o tempo limite da sandbox é redefinido para o tempo limite padrão de uma sandbox — 5 minutos.

Você pode passar um tempo limite personalizado para o método `Sandbox.connect()` assim:

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

  const sandbox = await Sandbox.create()

  const connectedSandbox = await Sandbox.connect(sandbox.sandboxId, { timeoutMs: 60 * 1000 })
  console.log('Sandbox connected', connectedSandbox.sandboxId)

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.create()

  connectedSandbox = Sandbox.connect(sandbox.sandbox_id, timeout=60) # 60 seconds
  print('Sandbox connected', connectedSandbox.sandbox_id)

  sandbox.kill()
  ```
</CodeGroup>

## Rede

Se você tiver um serviço (por exemplo, um servidor) em execução dentro da sua sandbox e pausar a sandbox, o serviço não ficará acessível externamente e todos os clientes serão desconectados.
Se você retomar a sandbox, o serviço ficará acessível novamente, mas será necessário conectar os clientes novamente.