Terminal interativo (PTY)

O módulo PTY, ou pseudo-terminal, permite sessões de terminal interativas dentro do sandbox com comunicação bidirecional em tempo real. Uma sessão PTY oferece suporte a streaming em tempo real, entregando continuamente a saída do terminal por meio de callbacks à medida que ela é produzida, e fornece entrada bidirecional, permitindo que dados sejam enviados enquanto a sessão ainda está em execução. Ela também oferece uma experiência de shell interativo com comportamento completo de terminal, incluindo cores ANSI e sequências de escape, além de oferecer suporte à persistência de sessão, de modo que uma sessão em execução possa ser desconectada e reconectada posteriormente.

Criar uma sessão PTY

Você pode usar sandbox.pty.create() para iniciar um shell bash interativo.

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,              // Terminal width in characters
  rows: 24,              // Terminal height in characters
  onData: (data) => {
    // Called whenever terminal outputs data
    process.stdout.write(data)
  },
  envs: { MY_VAR: 'hello' },  // Optional environment variables
  cwd: '/home/user',          // Optional working directory
  user: 'root',               // Optional user to run as
})

// terminal.pid contains the process ID
console.log('Terminal PID:', terminal.pid)

import threading

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(
    size=PtySize(rows=24, cols=80),  # PtySize is (rows, cols)
    envs={'MY_VAR': 'hello'},        # Optional environment variables
    cwd='/home/user',                # Optional working directory
    user='root',                     # Optional user to run as
)

# terminal.pid contains the process ID
print('Terminal PID:', terminal.pid)

# The Python SDK has no on_data param. Output is streamed via wait(on_pty=...),
# which blocks, so run it in a background thread.
threading.Thread(
    target=lambda: terminal.wait(on_pty=lambda data: print(data.decode(), end='')),
    daemon=True,
).start()

O PTY inicia um shell bash interativo com TERM=xterm-256color, portanto cores ANSI e sequências de escape funcionam conforme esperado.

Timeout

A configuração de timeout é configurável e determina por quanto tempo a sessão PTY permanece ativa. Você pode manter uma sessão PTY aberta indefinidamente definindo timeoutMs: 0 em JavaScript ou timeout=0 em Python. Por padrão, a sessão usa um timeout de 60 segundos.

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => process.stdout.write(data),
  timeoutMs: 0,  // Keep the session open indefinitely
})

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(
    size=PtySize(rows=24, cols=80),
    timeout=0,  # Keep the session open indefinitely
)

Enviar entrada para o PTY

Você pode usar sendInput() em JavaScript ou send_stdin() em Python para enviar dados ao terminal. Em JavaScript, sendInput() retorna uma Promise, e qualquer saída do terminal é entregue por meio do callback onData, em vez de ser retornada diretamente. Em Python, send_stdin() é concluído de forma síncrona, e qualquer saída do terminal é entregue por meio do callback on_pty passado para wait().

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => process.stdout.write(data),
})

// Send a command (don't forget the newline!)
await sandbox.pty.sendInput(
  terminal.pid,
  new TextEncoder().encode('echo "Hello from PTY"\n')
)

import threading

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(size=PtySize(rows=24, cols=80))

# Stream output in a background thread (Python uses wait(on_pty=...))
threading.Thread(
    target=lambda: terminal.wait(on_pty=lambda data: print(data.decode(), end='')),
    daemon=True,
).start()

# Send a command as bytes (b'...' is Python's byte string syntax)
# Don't forget the newline!
sandbox.pty.send_stdin(terminal.pid, b'echo "Hello from PTY"\n')

Redimensionar o terminal

Você pode usar resize() para notificar o PTY quando o usuário alterar o tamanho da janela do terminal. Os valores cols e rows representam as dimensões do terminal em caracteres, e não em pixels.

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => process.stdout.write(data),
})

// Resize to new dimensions (in characters)
await sandbox.pty.resize(terminal.pid, {
  cols: 120,
  rows: 40,
})

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(size=PtySize(rows=24, cols=80))

# Resize to new dimensions (in characters)
sandbox.pty.resize(terminal.pid, PtySize(rows=40, cols=120))

Desconectar e reconectar

Uma sessão PTY pode permanecer ativa mesmo depois que o cliente se desconecta. Você pode se desconectar da sessão e reconectar-se a ela novamente mais tarde com um novo manipulador de dados. Isso pode ser usado para se recuperar de interrupções de rede, oferecer suporte ao acesso ao terminal por vários clientes e preservar o estado da sessão entre reconexões.

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

const sandbox = await Sandbox.create()

// Create a PTY session
const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => console.log('Handler 1:', new TextDecoder().decode(data)),
})

const pid = terminal.pid

// Send a command
await sandbox.pty.sendInput(pid, new TextEncoder().encode('echo hello\n'))

// Disconnect - PTY keeps running in the background
await terminal.disconnect()

// Later: reconnect with a new data handler
const reconnected = await sandbox.pty.connect(pid, {
  onData: (data) => console.log('Handler 2:', new TextDecoder().decode(data)),
})

// Continue using the session
await sandbox.pty.sendInput(pid, new TextEncoder().encode('echo world\n'))

// Wait for the terminal to exit
await reconnected.wait()

import threading
import time

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

# Create a PTY session
terminal = sandbox.pty.create(size=PtySize(rows=24, cols=80))
pid = terminal.pid

# Send a command
sandbox.pty.send_stdin(pid, b'echo hello\n')
time.sleep(0.5)

# Disconnect - PTY keeps running in the background.
# Don't disconnect while a wait() is iterating the same handle.
terminal.disconnect()

# Later: reconnect with a new handle and stream its output
reconnected = sandbox.pty.connect(pid)
threading.Thread(
    target=lambda: reconnected.wait(on_pty=lambda data: print('Handler 2:', data.decode())),
    daemon=True,
).start()

# Continue using the session
sandbox.pty.send_stdin(pid, b'echo world\n')
time.sleep(1.5)

Encerrar o PTY

Você pode usar kill() para encerrar a sessão PTY.

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => process.stdout.write(data),
})

// Kill the PTY
const killed = await sandbox.pty.kill(terminal.pid)
console.log('Killed:', killed)  // true if successful

// Or use the handle method
// await terminal.kill()

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(size=PtySize(rows=24, cols=80))

# Kill the PTY
killed = sandbox.pty.kill(terminal.pid)
print('Killed:', killed)  # True if successful

# Or use the handle method
# terminal.kill()

Aguardar o PTY sair

Você pode usar wait() para bloquear até que a sessão do terminal termine, por exemplo, quando o usuário digita exit.

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

const sandbox = await Sandbox.create()

const terminal = await sandbox.pty.create({
  cols: 80,
  rows: 24,
  onData: (data) => process.stdout.write(data),
})

// Send exit command
await sandbox.pty.sendInput(terminal.pid, new TextEncoder().encode('exit\n'))

// Wait for the terminal to exit
const result = await terminal.wait()
console.log('Exit code:', result.exitCode)

from novita_sandbox.code_interpreter import Sandbox, PtySize

sandbox = Sandbox.create()

terminal = sandbox.pty.create(size=PtySize(rows=24, cols=80))

# Send exit command
sandbox.pty.send_stdin(terminal.pid, b'exit\n')

# wait() blocks until the terminal exits; pass on_pty to stream output
result = terminal.wait(on_pty=lambda data: print(data.decode(), end=''))
print('Exit code:', result.exit_code)

Terminal interativo (semelhante a SSH)

Você pode usar a mesma API sandbox.pty descrita acima para criar um terminal totalmente interativo, como SSH, lidando com raw mode, encaminhamento de stdin e eventos de redimensionamento do terminal.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Terminal interativo (PTY)

Criar uma sessão PTY

Timeout

Enviar entrada para o PTY

Redimensionar o terminal

Desconectar e reconectar

Encerrar o PTY

Aguardar o PTY sair

Terminal interativo (semelhante a SSH)

​Criar uma sessão PTY

​Timeout

​Enviar entrada para o PTY

​Redimensionar o terminal

​Desconectar e reconectar

​Encerrar o PTY

​Aguardar o PTY sair

​Terminal interativo (semelhante a SSH)

Criar uma sessão PTY

Timeout

Enviar entrada para o PTY

Redimensionar o terminal

Desconectar e reconectar

Encerrar o PTY

Aguardar o PTY sair

Terminal interativo (semelhante a SSH)