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

A persistência do sandbox permite pausar um sandbox e retomá-lo posteriormente com o mesmo sistema de arquivos e estado de memória. Isso é útil para tarefas de agentes de longa duração, apps interativos e fluxos de trabalho que precisam sobreviver a períodos de ociosidade sem manter recursos computacionais ativos.

Quando um sandbox é pausado:

* Os arquivos criados no sandbox são preservados.
* O estado em memória é preservado, incluindo processos em execução e variáveis.
* As conexões de rede são interrompidas até que o sandbox seja retomado.
* O sandbox permanece armazenado até que você o retome e o encerre, ou o encerre enquanto ele está pausado.

Para pausa automática por tempo limite e retomada automática por atividade, consulte [Pausa e retomada automáticas](/docs/pt-BR/guides/sandbox-auto-resume). Para tempo limite de ociosidade, consulte [Tempo limite de ociosidade](/docs/pt-BR/guides/sandbox-idle-timeout).

<SandboxConfigHint />

<Warning>
  Observe:

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

## Pausar um sandbox

Você pode chamar o método `pause` quando quiser salvar o estado atual.

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

  const sandbox = await Sandbox.create()
  await sandbox.commands.run('echo hello > /tmp/message.txt')

  const sandboxId = sandbox.sandboxId
  await sandbox.pause()

  console.log('Sandbox paused', sandboxId)
  ```

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

  sandbox = Sandbox.create()
  sandbox.commands.run("echo hello > /tmp/message.txt")

  sandbox_id = sandbox.sandbox_id
  sandbox.pause()

  print('Sandbox paused', sandbox_id)
  ```
</CodeGroup>

## Retomar um sandbox

Use o ID do sandbox salvo para se conectar novamente. Se o sandbox estiver pausado, você pode usar o método `connect` para retomá-lo antes de retornar.

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

  const sandbox = await Sandbox.connect(sandboxId)
  const result = await sandbox.commands.run('cat /tmp/message.txt')
  console.log(result.stdout)

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.connect(sandbox_id)
  result = sandbox.commands.run("cat /tmp/message.txt")
  print(result.stdout)

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

Você pode passar um novo `timeout` ao se reconectar.

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

  const sandbox = await Sandbox.connect(sandboxId, { timeoutMs: 600_000 })

  await sandbox.kill()
  ```

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

  sandbox = Sandbox.connect(sandbox_id, timeout=600)

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

Para um sandbox em execução, o tempo limite é atualizado somente quando o novo tempo limite é maior que o existente. Para um sandbox pausado, o tempo limite se aplica depois que ele é retomado.

## Listar sandboxes pausados

Você pode usar o método `list` com um filtro de estado para encontrar sandboxes pausados. Mais informações sobre como usar o método podem ser encontradas em [Listar Sandboxes](/docs/pt-BR/guides/sandbox-list).

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

  const paginator = Sandbox.list({
    query: {
      state: ['paused'],
    },
  })

  while (paginator.hasNext) {
    const items = await paginator.nextItems()
    for (const info of items) {
      console.log(info.sandboxId, info.state, info.metadata)
    }
  }
  ```

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

  paginator = Sandbox.list(
      query=SandboxQuery(state=[SandboxState.PAUSED])
  )

  while paginator.has_next:
      for info in paginator.next_items():
          print(info.sandbox_id, info.state, info.metadata)
  ```
</CodeGroup>

Filtros de metadados são úteis quando você precisa encontrar sandboxes criados por um usuário, sessão ou job específico.

## Excluir um sandbox pausado

Sandboxes pausados permanecem armazenados até que você os remova. Você pode usar o método `kill` para remover sandboxes pausados que não são mais necessários.

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

  await Sandbox.kill(sandboxId)
  ```

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

  Sandbox.kill(sandbox_id)
  ```
</CodeGroup>

## Persistência vs snapshots

A persistência serve para continuar o mesmo sandbox posteriormente. Use-a quando você se importa com o ID exato do sandbox e com o estado atual em execução.

Snapshots servem para criar estados salvos reutilizáveis. Use um snapshot quando quiser iniciar um ou mais novos sandboxes a partir do mesmo sistema de arquivos e estado de memória capturados.

Para estados reutilizáveis, consulte [Snapshot do Sandbox](/docs/pt-BR/guides/sandbox-snapshot).

## Rede

Se você pausar um sandbox que tem um serviço em execução, o serviço ficará inacessível de fora do sandbox e todos os clientes conectados serão desconectados. Depois que você retomar o sandbox, o serviço ficará acessível novamente, mas os clientes precisarão se reconectar.