Pausa e retomada automáticas

Esses recursos se baseiam na Persistência de sandbox. A pausa automática mantém o estado da sandbox quando a duração máxima expira. A retomada automática desperta uma sandbox pausada quando uma nova atividade chega.

Configurar

Ao criar uma sandbox, passe uma configuração lifecycle. Isso controla o comportamento de tempo limite e se uma sandbox pausada pode despertar automaticamente.

import { Sandbox } from 'novita-sandbox'

const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true, // resume when activity arrives
  },
})

from novita_sandbox.core import Sandbox

sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,  # resume when activity arrives
    },
)

Opções de ciclo de vida

A configuração lifecycle oferece suporte a estes campos:

Configuração	Opção	Significado
`onTimeout` (JS) / `on_timeout` (Python)	`"kill"`	Comportamento padrão. A sandbox é removida após seu tempo limite.
`onTimeout` (JS) / `on_timeout` (Python)	`"pause"`	A sandbox é pausada após o tempo limite em vez de ser excluída.
`autoResume` (JS) / `auto_resume` (Python)	`false`	Comportamento padrão. Sandboxes pausadas permanecem pausadas até serem retomadas manualmente.
`autoResume` (JS) / `auto_resume` (Python)	`true`	Sandboxes pausadas reiniciam quando uma atividade compatível chega. Isso exige que o comportamento de tempo limite seja `"pause"`.

Se a retomada automática estiver desabilitada ou omitida, uma sandbox pausada ainda poderá ser retomada manualmente com Sandbox.connect().

Pausa automática

Por padrão, uma sandbox é encerrada quando seu tempo limite expira. Para manter o estado em vez disso, defina onTimeout em JavaScript ou on_timeout em Python para pausar no tempo limite.

import { Sandbox } from 'novita-sandbox/code-interpreter'

const sandbox = await Sandbox.create({
  timeoutMs: 300_000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: false,
  },
})

await sandbox.kill()

from novita_sandbox.code_interpreter import Sandbox

sandbox = Sandbox.create(
    timeout=300,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": False,
    },
)

sandbox.kill()

Retomada automática

A retomada automática pode despertar uma sandbox pausada quando uma atividade compatível chega. Isso funciona somente quando a sandbox está configurada para pausar no tempo limite.

Tempo limite após a retomada automática

Após uma retomada automática, a sandbox recebe um tempo limite de pelo menos cinco minutos. Se o tempo limite original era maior que cinco minutos, o valor original mais longo é reutilizado. O temporizador de tempo limite começa quando a sandbox é retomada, não quando ela foi criada originalmente. Exemplo com um tempo limite de dois minutos:

A sandbox é executada por dois minutos e então pausa.
Uma nova atividade chega à sandbox, fazendo com que ela seja retomada.
A sandbox retomada recebe um tempo limite de cinco minutos porque esse é o mínimo.
Se nada redefinir o temporizador, a sandbox pausará novamente após cinco minutos.

Exemplo com um tempo limite de uma hora:

A sandbox é retomada com um tempo limite de uma hora, porque o tempo limite original é maior que o mínimo de cinco minutos.

Esse comportamento continua em ciclos futuros de pausa e retomada, porque as configurações de ciclo de vida permanecem associadas à sandbox.

Você pode atualizar o tempo limite após retomar usando setTimeout() em JavaScript ou set_timeout() em Python.

O que conta como atividade

A retomada automática pode ser acionada por ações do SDK e tráfego HTTP. Exemplos compatíveis incluem:

sandbox.commands.run(...)
sandbox.files.read(...)
sandbox.files.write(...)
Visitar a URL de uma aplicação em túnel
Enviar solicitações para um serviço em execução dentro da sandbox

Quando uma sandbox está pausada e a retomada automática está habilitada, a próxima ação compatível a retoma automaticamente. Você não precisa chamar Sandbox.connect() primeiro.

Exemplo de SDK: pausar e depois ler um arquivo

Este exemplo cria uma sandbox, grava um arquivo, pausa a sandbox e depois lê o arquivo. A operação de leitura faz com que a sandbox seja retomada.

import { Sandbox } from 'novita-sandbox'

const sandbox = await Sandbox.create({
  timeoutMs: 10 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.files.write('/home/user/hello.txt', 'hello from a paused sandbox')
await sandbox.pause()

const content = await sandbox.files.read('/home/user/hello.txt')
console.log(content)
console.log(`State after read: ${(await sandbox.getInfo()).state}`)

from novita_sandbox.core import Sandbox

sandbox = Sandbox.create(
    timeout=10 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

sandbox.files.write("/home/user/hello.txt", "hello from a paused sandbox")
sandbox.pause()

content = sandbox.files.read("/home/user/hello.txt")
print(content)
print(f"State after read: {sandbox.get_info().state}")

Exemplo: servidor Web com retomada automática

A retomada automática funciona bem para ambientes de pré-visualização e servidores Web. Depois que a sandbox pausa, uma solicitação HTTP de entrada para o serviço exposto pode despertá-la. O exemplo abaixo inicia um servidor HTTP Python simples e imprime uma URL pública de pré-visualização. Você pode usar getHost() em JavaScript ou get_host() em Python para obter o hostname público de uma porta.

import { Sandbox } from 'novita-sandbox'

const sandbox = await Sandbox.create({
  timeoutMs: 5 * 60 * 1000,
  lifecycle: {
    onTimeout: 'pause',
    autoResume: true,
  },
})

await sandbox.commands.run('python3 -m http.server 3000', { background: true })

const host = sandbox.getHost(3000)
// Once the sandbox times out and pauses, any request to the preview URL will automatically resume it.
console.log(`Preview URL: https://${host}`)

from novita_sandbox.core import Sandbox

sandbox = Sandbox.create(
    timeout=5 * 60,
    lifecycle={
        "on_timeout": "pause",
        "auto_resume": True,
    },
)

sandbox.commands.run("python3 -m http.server 3000", background=True)

host = sandbox.get_host(3000)
# Once the sandbox times out and pauses, any request to the preview URL will automatically resume it.
print(f"Preview URL: https://{host}")

Limpeza

A retomada automática permanece habilitada ao longo de ciclos repetidos de retomada e pausa. Cada retomada inicia um novo período de tempo limite, usando pelo menos cinco minutos ou o tempo limite original mais longo. Depois que a sandbox é retomada, os clientes devem se reconectar a todos os serviços que estavam usando. Conexões HTTP, WebSocket, de banco de dados e de terminal existentes não permanecem abertas enquanto a sandbox está pausada. Você pode chamar .kill() para excluir a sandbox permanentemente. Depois disso, ela não poderá ser retomada.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Pausa e retomada automáticas

Configurar

Opções de ciclo de vida

Pausa automática

Retomada automática

Tempo limite após a retomada automática

O que conta como atividade

Exemplo de SDK: pausar e depois ler um arquivo

Exemplo: servidor Web com retomada automática

Limpeza

​Configurar

​Opções de ciclo de vida

​Pausa automática

​Retomada automática

​Tempo limite após a retomada automática

​O que conta como atividade

​Exemplo de SDK: pausar e depois ler um arquivo

​Exemplo: servidor Web com retomada automática

​Limpeza

Configurar

Opções de ciclo de vida

Pausa automática

Retomada automática

Tempo limite após a retomada automática

O que conta como atividade

Exemplo de SDK: pausar e depois ler um arquivo

Exemplo: servidor Web com retomada automática

Limpeza