Terminal interactif (PTY)

Le module PTY, ou pseudo-terminal, permet d’exécuter des sessions de terminal interactives dans la sandbox avec une communication bidirectionnelle en temps réel. Une session PTY prend en charge le streaming en temps réel, en transmettant continuellement la sortie du terminal via des callbacks à mesure qu’elle est produite, et fournit une entrée bidirectionnelle, permettant d’envoyer des données pendant que la session est toujours en cours d’exécution. Elle offre également une expérience de shell interactif avec un comportement complet de terminal, y compris les couleurs ANSI et les séquences d’échappement, et prend en charge la persistance de session, afin qu’une session en cours puisse être détachée puis reconnectée ultérieurement.

Créer une session PTY

Vous pouvez utiliser sandbox.pty.create() pour démarrer un shell bash interactif.

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

Le PTY lance un shell bash interactif avec TERM=xterm-256color, de sorte que les couleurs ANSI et les séquences d’échappement fonctionnent comme prévu.

Délai d’expiration

Le paramètre de délai d’expiration est configurable et détermine combien de temps la session PTY reste active. Vous pouvez garder une session PTY ouverte indéfiniment en définissant timeoutMs: 0 en JavaScript ou timeout=0 en Python. Par défaut, la session utilise un délai d’expiration de 60 secondes.

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
)

Envoyer une entrée au PTY

Vous pouvez utiliser sendInput() en JavaScript ou send_stdin() en Python pour envoyer des données au terminal. En JavaScript, sendInput() renvoie une Promise, et toute sortie du terminal est transmise via le callback onData plutôt que renvoyée directement. En Python, send_stdin() se termine de manière synchrone, et toute sortie du terminal est transmise via le callback on_pty passé à 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')

Redimensionner le terminal

Vous pouvez utiliser resize() pour notifier le PTY lorsque l’utilisateur modifie la taille de la fenêtre du terminal. Les valeurs cols et rows représentent les dimensions du terminal en caractères plutôt qu’en 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))

Se déconnecter et se reconnecter

Une session PTY peut rester active même après la déconnexion du client. Vous pouvez détacher la session et vous y reconnecter plus tard avec un nouveau gestionnaire de données. Cela peut être utilisé pour récupérer après des interruptions réseau, prendre en charge l’accès au terminal depuis plusieurs clients et préserver l’état de la session lors des reconnexions.

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)

Arrêter le PTY

Vous pouvez utiliser kill() pour terminer la session 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()

Attendre la fin du PTY

Vous pouvez utiliser wait() pour bloquer l’exécution jusqu’à la fin de la session de terminal, par exemple lorsque l’utilisateur saisit 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 interactif (semblable à SSH)

Vous pouvez utiliser la même API sandbox.pty décrite ci-dessus pour créer un terminal entièrement interactif comme SSH, en gérant le mode brut, la transmission de stdin et les événements de redimensionnement du terminal.

Get started

Model APIs

Agent Sandbox

GPUs

Observability

Resources

Terminal interactif (PTY)

Créer une session PTY

Délai d’expiration

Envoyer une entrée au PTY

Redimensionner le terminal

Se déconnecter et se reconnecter

Arrêter le PTY

Attendre la fin du PTY

Terminal interactif (semblable à SSH)

​Créer une session PTY

​Délai d’expiration

​Envoyer une entrée au PTY

​Redimensionner le terminal

​Se déconnecter et se reconnecter

​Arrêter le PTY

​Attendre la fin du PTY

​Terminal interactif (semblable à SSH)

Créer une session PTY

Délai d’expiration

Envoyer une entrée au PTY

Redimensionner le terminal

Se déconnecter et se reconnecter

Arrêter le PTY

Attendre la fin du PTY

Terminal interactif (semblable à SSH)