feat: add PTY/terminal session support with ghostty-web UI

[NathanFlurry]

Summary

Adds PTY/terminal session support to the Process Manager API with an interactive terminal UI using ghostty-web.

Backend (Rust)

New API Endpoints:

• GET /v1/process/:id/terminal — WebSocket for bidirectional terminal I/O
• POST /v1/process/:id/resize — Resize terminal (cols, rows)
• POST /v1/process/:id/input — Write data to terminal

Extended StartProcessRequest:

• tty: bool — Allocate pseudo-TTY (like Docker -t)
• interactive: bool — Keep stdin open (like Docker -i)
• terminalSize: {cols, rows} — Initial terminal size

Features:

• PTY allocation with portable-pty
• TERM=xterm-256color environment variable
• Terminal resize support
• WebSocket protocol for real-time I/O

Frontend (React/TypeScript)

• Terminal component using ghostty-web (replaced xterm.js)
• WebSocket integration for live terminal I/O
• Auto-resize with FitAddon
• PTY badge and tabbed view in ProcessesTab

Builds on

• PR feat: add process manager API #42 (Process Manager API)

[railway-app]

🚅 Deployed to the sandbox-agent-pr-44 environment in sandbox-agent

Service	Status	Web	Updated (UTC)
inspector	😴 Sleeping (View Logs)	Web	Jan 30, 2026 at 9:49 pm
website	😴 Sleeping (View Logs)	Web	Jan 30, 2026 at 9:47 pm

[claude]

Code Review

I found 2 CLAUDE.md compliance issues that need to be addressed:

1. Missing CLI ⇄ HTTP endpoint map entries in CLAUDE.md

This PR adds new HTTP API routes for process management that need to be documented in the CLI ⇄ HTTP endpoint map (CLAUDE.md lines 51-65):

• sandbox-agent api process start ↔ POST /v1/process
• sandbox-agent api process list ↔ GET /v1/process
• sandbox-agent api process get ↔ GET /v1/process/:id
• sandbox-agent api process delete ↔ DELETE /v1/process/:id
• sandbox-agent api process stop ↔ POST /v1/process/:id/stop
• sandbox-agent api process kill ↔ POST /v1/process/:id/kill
• sandbox-agent api process logs ↔ GET /v1/process/:id/logs
• sandbox-agent api process resize ↔ POST /v1/process/:id/resize
• sandbox-agent api process input ↔ POST /v1/process/:id/input
• sandbox-agent api process terminal ↔ GET /v1/process/:id/terminal (WebSocket)

These routes are added in

sandbox-agent/server/packages/sandbox-agent/src/router.rs

Lines 2499 to 2515 in 1d1069d

	let session = Self::session_mut(&mut sessions, session_id).ok_or_else(|| {
	SandboxError::SessionNotFound {
	session_id: session_id.to_string(),
	}
	})?;
	Ok(session.record_conversions(conversions))
	}
	async fn parse_claude_line(&self, line: &str, session_id: &str) -> Vec<EventConversion> {
	let trimmed = line.trim();
	if trimmed.is_empty() {
	return Vec::new();
	}
	let mut value: Value = match serde_json::from_str(trimmed) {
	Ok(value) => value,
	Err(err) => {
	return vec![agent_unparsed(

Per

sandbox-agent/CLAUDE.md

Lines 30 to 34 in 1d1069d

	- Keep CLI subcommands in sync with every HTTP endpoint.
	- Update `CLAUDE.md` to keep CLI endpoints in sync with HTTP API changes.
	- When adding or modifying CLI commands, update `docs/cli.mdx` to reflect the changes.
	- When changing the HTTP API, update the TypeScript SDK and CLI together.

:

Keep CLI subcommands in sync with every HTTP endpoint.
Update CLAUDE.md to keep CLI endpoints in sync with HTTP API changes.

---

2. Missing HTTP test coverage for new API routes

The PR adds 10 new HTTP API routes for process/terminal management but does not include corresponding test coverage in server/packages/sandbox-agent/tests/http/.

Routes added in

sandbox-agent/server/packages/sandbox-agent/src/router.rs

Lines 2499 to 2515 in 1d1069d

	let session = Self::session_mut(&mut sessions, session_id).ok_or_else(|| {
	SandboxError::SessionNotFound {
	session_id: session_id.to_string(),
	}
	})?;
	Ok(session.record_conversions(conversions))
	}
	async fn parse_claude_line(&self, line: &str, session_id: &str) -> Vec<EventConversion> {
	let trimmed = line.trim();
	if trimmed.is_empty() {
	return Vec::new();
	}
	let mut value: Value = match serde_json::from_str(trimmed) {
	Ok(value) => value,
	Err(err) => {
	return vec![agent_unparsed(

:

• POST /v1/process
• GET /v1/process
• GET /v1/process/:id
• DELETE /v1/process/:id
• POST /v1/process/:id/stop
• POST /v1/process/:id/kill
• GET /v1/process/:id/logs
• POST /v1/process/:id/resize
• POST /v1/process/:id/input
• GET /v1/process/:id/terminal (WebSocket)

Per

sandbox-agent/CLAUDE.md

Lines 35 to 37 in 1d1069d

	- Do not make breaking changes to API endpoints.
	- When changing API routes, ensure the HTTP/SSE test suite has full coverage of every route.
	- When agent schema changes, ensure API tests cover the new schema and event shapes end-to-end.

:

When changing API routes, ensure the HTTP/SSE test suite has full coverage of every route.