{"_id":"@background-agents/sandbox-terminal","name":"@background-agents/sandbox-terminal","dist-tags":{"latest":"0.2.0"},"versions":{"0.2.0":{"name":"@background-agents/sandbox-terminal","version":"0.2.0","description":"WebSocket-based PTY terminal for Daytona sandboxes","type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"./components":{"types":"./dist/components/index.d.ts","default":"./dist/components/index.js"},"./sandbox":{"types":"./dist/sandbox/index.d.ts","default":"./dist/sandbox/index.js"},"./server":{"types":"./dist/server/index.d.ts","default":"./dist/server/index.js"},"./package.json":"./package.json"},"scripts":{"build":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc && tsc-alias --resolve-full-paths","clean":"node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","test:e2e":"vitest run tests/integration","prepare":"npm run build"},"dependencies":{"xterm":"^5.3.0","xterm-addon-fit":"^0.8.0","xterm-addon-web-links":"^0.9.0"},"devDependencies":{"@daytonaio/sdk":"^0.170.0","@types/node":"^20.10.0","@types/react":"^19","@types/ws":"^8.5.10","dotenv":"^17.3.1","react":"^19.2.4","tsc-alias":"^1.8.10","typescript":"^5.3.0","vitest":"^1.0.0","ws":"^8.18.0"},"peerDependencies":{"@daytonaio/sdk":">=0.170.0","react":">=18.0.0"},"peerDependenciesMeta":{"@daytonaio/sdk":{"optional":true}},"publishConfig":{"access":"public"},"_id":"@background-agents/sandbox-terminal@0.2.0","gitHead":"803bd192a97990ac03f5d559b923f7633a853c96","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-8nXzxCilbsWxXQ6zU7f3TIx6EpbyVk3yY9gpwKYJrHaxIYzXST0eZdwWDCgK3ulUkSry5k0NBi18QFrkEjCi6w==","shasum":"e71b0c3a44d3d2939594030013a2fb53113d2f88","tarball":"https://registry.npmjs.org/@background-agents/sandbox-terminal/-/sandbox-terminal-0.2.0.tgz","fileCount":23,"unpackedSize":37697,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDl5oFXo6OeBcbVqoWO0hceSGsOtXqi/jhjxz+Th7W0OAiEA7KAY6p1q2DIM6d0ucY3jx7Liyu9w50Ifqn4+RRTb42A="}]},"_npmUser":{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"},"directories":{},"maintainers":[{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sandbox-terminal_0.2.0_1782598720943_0.081418454743728"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-27T22:18:40.804Z","0.2.0":"2026-06-27T22:18:41.074Z","modified":"2026-06-27T22:18:41.338Z"},"maintainers":[{"name":"jamesmurdza","email":"jamesmurdza@gmail.com"}],"description":"WebSocket-based PTY terminal for Daytona sandboxes","readme":"# @background-agents/sandbox-terminal\n\nWebSocket-based PTY terminal for Daytona sandboxes. Provides a full interactive terminal experience using xterm.js, with automatic server setup inside the sandbox.\n\n## Features\n\n- **Full PTY support**: Run interactive programs like vim, htop, ssh, etc.\n- **Real-time streaming**: Instant I/O via WebSocket\n- **Terminal emulation**: Full ANSI color support, cursor positioning, scrollback\n- **Resize handling**: Terminal automatically resizes to fit container\n- **Web links**: Clickable URLs in terminal output\n- **Theme support**: Light and dark mode\n- **Zero-friction setup**: Server auto-installed in sandbox\n\n## Installation\n\n```bash\nnpm install @background-agents/sandbox-terminal @daytonaio/sdk\n```\n\n## Quick Start\n\n```typescript\nimport { Daytona } from \"@daytonaio/sdk\"\nimport { setupTerminal, WebSocketTerminal } from \"@background-agents/sandbox-terminal\"\n\n// 1. Create sandbox and set up terminal\nconst daytona = new Daytona({ apiKey: process.env.DAYTONA_API_KEY })\nconst sandbox = await daytona.create()\nconst { websocketUrl, status } = await setupTerminal(sandbox)\n\n// 2. Use the WebSocket URL in your React component\nif (status === \"running\" && websocketUrl) {\n  return <WebSocketTerminal websocketUrl={websocketUrl} />\n}\n```\n\n## API Reference\n\n### Sandbox Setup Functions\n\n#### `setupTerminal(sandbox, options?)`\n\nSets up and starts the PTY terminal server in a Daytona sandbox. Auto-installs dependencies (ws, node-pty) if needed.\n\n```typescript\nimport { setupTerminal } from \"@background-agents/sandbox-terminal\"\n\nconst result = await setupTerminal(sandbox, {\n  expiresIn: 3600,  // URL expiry in seconds (default: 3600)\n  port: 44777,      // Server port (default: 44777)\n})\n\n// Result:\n// {\n//   status: \"running\" | \"starting\" | \"stopped\" | \"error\",\n//   websocketUrl?: string,  // wss:// URL for terminal connection\n//   httpsUrl?: string,      // https:// URL for health checks\n//   port: number,\n//   error?: string,\n//   details?: string,\n// }\n```\n\n#### `getTerminalStatus(sandbox, options?)`\n\nCheck if the terminal server is running and get its URL.\n\n```typescript\nimport { getTerminalStatus } from \"@background-agents/sandbox-terminal\"\n\nconst { status, websocketUrl } = await getTerminalStatus(sandbox)\n```\n\n#### `stopTerminal(sandbox)`\n\nStop the terminal server.\n\n```typescript\nimport { stopTerminal } from \"@background-agents/sandbox-terminal\"\n\nawait stopTerminal(sandbox)\n```\n\n### React Component\n\n#### `WebSocketTerminal`\n\n```tsx\nimport { WebSocketTerminal } from '@background-agents/sandbox-terminal'\n\n<WebSocketTerminal\n  websocketUrl={websocketUrl}\n  onConnect={(pid) => console.log('Connected, PID:', pid)}\n  onDisconnect={() => console.log('Disconnected')}\n  onError={(err) => console.error('Error:', err)}\n  fontSize={14}\n  theme={{\n    background: '#1e1e1e',\n    foreground: '#d4d4d4',\n    cursor: '#ffffff',\n    selection: 'rgba(255, 255, 255, 0.3)',\n  }}\n/>\n```\n\n#### Props\n\n| Prop | Type | Default | Description |\n|------|------|---------|-------------|\n| `websocketUrl` | `string` | required | WebSocket URL to connect to |\n| `className` | `string` | `''` | CSS class for container |\n| `onConnect` | `(pid: number) => void` | - | Called when connected |\n| `onDisconnect` | `(code?, reason?) => void` | - | Called when disconnected |\n| `onError` | `(error: Error) => void` | - | Called on error |\n| `theme` | `object` | - | Terminal color theme |\n| `fontSize` | `number` | `13` | Font size in pixels |\n| `fontFamily` | `string` | `'Menlo, Monaco, \"Courier New\", monospace'` | Font family |\n\n### Server Code (Advanced)\n\nFor custom deployments, you can access the raw server code:\n\n```typescript\nimport { getPtyServerCode, getPtyServerPackageJson, PTY_SERVER_PORT } from \"@background-agents/sandbox-terminal/server\"\n\n// Get the Node.js server code as a string\nconst serverCode = getPtyServerCode()\n\n// Get the package.json for dependencies\nconst packageJson = getPtyServerPackageJson()\n\n// Default port\nconsole.log(PTY_SERVER_PORT) // 44777\n```\n\n## Protocol\n\nMessages are JSON-encoded:\n\n### Client -> Server\n\n```typescript\n// Send input to PTY\n{ type: 'input', payload: 'ls -la\\n' }\n\n// Resize terminal\n{ type: 'resize', cols: 80, rows: 24 }\n```\n\n### Server -> Client\n\n```typescript\n// PTY output\n{ type: 'data', payload: '...' }\n\n// Connection ready\n{ type: 'ready', pid: 12345 }\n```\n\n## Architecture\n\n```\n┌─────────────────┐     ┌──────────────────────────────────────┐\n│   Your App      │     │          Daytona Sandbox             │\n│                 │     │  ┌─────────────────────────────────┐ │\n│  setupTerminal()│────▶│  │  PTY Server (auto-installed)    │ │\n│                 │     │  │  - node-pty for PTY             │ │\n│  <WebSocket     │◀───▶│  │  - ws for WebSocket             │ │\n│   Terminal />   │     │  └─────────────────────────────────┘ │\n└─────────────────┘     └──────────────────────────────────────┘\n```\n\n## Requirements\n\n- Node.js >= 18\n- React >= 18\n- `@daytonaio/sdk` >= 0.170.0 (for sandbox setup functions)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-57b14df39fe7c69bb51279c82ce047c1"}