@treesap/sandbox 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-11-06
+
+### 🎉 Major Redesign - Breaking Changes
+
+TreeSap Sandbox has been completely redesigned from a terminal-centric WebSocket server to a folder-based sandbox API similar to Cloudflare's Sandbox SDK.
+
+### Added
+
+- **Sandbox Management API**
+  - Create isolated sandbox instances with dedicated working directories
+  - List all active sandboxes
+  - Get sandbox status and metrics
+  - Destroy sandboxes with optional cleanup
+
+- **File Operations API**
+  - `readFile()` - Read file contents
+  - `writeFile()` - Write/create files
+  - `listFiles()` - List directory contents with optional recursion
+  - `deleteFile()` - Remove files and directories
+  - Path traversal protection
+  - Glob pattern filtering
+
+- **Command Execution**
+  - `exec()` - Execute commands and return complete results
+  - `execStream()` - Stream command output via Server-Sent Events
+  - Timeout support
+  - Custom working directory and environment variables
+
+- **Process Management**
+  - `startProcess()` - Start long-running background processes
+  - `listProcesses()` - View all running processes
+  - `killProcess()` - Terminate specific processes
+  - `killAllProcesses()` - Terminate all processes
+  - `streamProcessLogs()` - Real-time log streaming
+  - `getProcessLogs()` - Get accumulated logs
+
+- **TypeScript SDK Client**
+  - Full-featured client library (`SandboxClient`)
+  - Promise-based API with async/await support
+  - Type-safe interfaces
+  - Streaming support with SSE parsing utilities
+
+- **REST API Server**
+  - Built with Hono framework
+  - Complete REST endpoints for all operations
+  - Server-Sent Events for streaming
+  - CORS support
+  - Health check endpoints
+
+- **CLI Tool**
+  - `treesap-sandbox` command-line interface
+  - Configurable port, host, and paths
+  - Built-in help
+
+- **Core Components**
+  - `Sandbox` class - Individual sandbox instance
+  - `SandboxManager` - Multi-sandbox management
+  - `FileService` - File operations service
+  - `StreamService` - SSE streaming utilities
+
+- **Auto-cleanup**
+  - Automatic cleanup of idle sandboxes (30 min default)
+  - Configurable cleanup intervals
+  - Graceful shutdown handling
+
+- **Documentation**
+  - Comprehensive README with examples
+  - Migration guide from v0.x
+  - API reference
+  - Use case examples
+
+### Removed
+
+- `TerminalService` - Replaced by `Sandbox` class
+- `WebSocketTerminalService` - Replaced by REST API + SSE
+- WebSocket support - Replaced by Server-Sent Events
+- `node-pty` dependency - Replaced by `child_process`
+- `ws` dependency - No longer needed
+- Terminal session persistence to disk
+
+### Changed
+
+- **Package version**: `0.1.0` → `1.0.0`
+- **Main export**: `startSandboxServer()` → `startServer()`
+- **Communication**: WebSocket → REST API + Server-Sent Events
+- **Isolation**: PTY sessions → Folder-based sandboxes
+- **Dependencies**: Removed `node-pty` and `ws`, kept `hono` and `@hono/node-server`
+
+### Migration
+
+See [MIGRATION.md](./MIGRATION.md) for detailed migration instructions from v0.x to v1.0.
+
+## [0.1.0] - Previous Version
+
+Initial release with terminal-centric WebSocket server.
+
+### Features
+
+- PTY-based terminal sessions
+- WebSocket real-time communication
+- REST API for terminal management
+- Session persistence
+- Multi-client support

package/README.md

@@ -0,0 +1,495 @@
+# 🌳 TreeSap Sandbox
+
+A self-hosted sandbox API for isolated code execution and file management. Similar to Cloudflare's Sandbox SDK, but designed for self-hosting on your own infrastructure.
+
+Perfect for AI agents, code execution platforms, and automation tools that need secure, isolated environments.
+
+> ⚠️ **Warning**: This package is experimental and exposes your machine to the local network. It executes arbitrary code with folder-based isolation only (not containerized). Proceed with caution.
+
+## Features
+
+- 🔒 **Folder-based isolation** - Each sandbox gets its own working directory
+- 📁 **File Operations API** - Read, write, list, and delete files
+- ⚡ **Command Execution** - Run commands with streaming output
+- 🔄 **Process Management** - Start, monitor, and kill background processes
+- 🌊 **Real-time Streaming** - Server-Sent Events for live output
+- 🎯 **Simple REST API** - Easy to integrate with any language
+- 📦 **TypeScript SDK** - Full-featured client library included
+- 🚀 **Self-hosted** - Run on your own servers, no cloud dependencies
+
+## Installation
+
+```bash
+npm install @treesap/sandbox
+```
+
+## Quick Start
+
+### Start the Server
+
+```bash
+# Using CLI
+npx treesap-sandbox --port 3000
+
+# Or programmatically
+import { startServer } from '@treesap/sandbox';
+
+await startServer({ port: 3000 });
+```
+
+### Use the Client SDK
+
+```typescript
+import { SandboxClient } from '@treesap/sandbox';
+
+// Create a new sandbox
+const sandbox = await SandboxClient.create('http://localhost:3000');
+
+// Execute commands
+const result = await sandbox.exec('npm install');
+console.log(result.stdout);
+
+// File operations
+await sandbox.writeFile('hello.txt', 'Hello, World!');
+const content = await sandbox.readFile('hello.txt');
+const files = await sandbox.listFiles();
+
+// Background processes
+const server = await sandbox.startProcess('node server.js');
+const logs = await sandbox.streamProcessLogs(server.id);
+
+// Cleanup
+await sandbox.destroy({ cleanup: true });
+```
+
+## API Reference
+
+### Sandbox Management
+
+#### Create a Sandbox
+
+```typescript
+POST /sandbox
+```
+
+```typescript
+const sandbox = await SandboxClient.create('http://localhost:3000', {
+  workDir: '/custom/path',  // optional
+  timeout: 60000,           // optional, default timeout for commands
+});
+```
+
+#### Get Sandbox Info
+
+```typescript
+GET /sandbox/:id
+```
+
+```typescript
+const status = await sandbox.getStatus();
+console.log(status);
+// {
+//   id: 'abc123',
+//   workDir: '/path/to/sandbox',
+//   createdAt: 1234567890,
+//   processCount: 2,
+//   ...
+// }
+```
+
+#### List All Sandboxes
+
+```typescript
+GET /sandbox
+```
+
+#### Destroy a Sandbox
+
+```typescript
+DELETE /sandbox/:id?cleanup=true
+```
+
+```typescript
+await sandbox.destroy({ cleanup: true });
+```
+
+### Command Execution
+
+#### Execute Command
+
+```typescript
+POST /sandbox/:id/exec
+```
+
+```typescript
+const result = await sandbox.exec('ls -la', {
+  timeout: 5000,
+  cwd: '/custom/dir',
+  env: { NODE_ENV: 'production' }
+});
+
+console.log(result);
+// {
+//   success: true,
+//   stdout: '...',
+//   stderr: '...',
+//   exitCode: 0
+// }
+```
+
+#### Stream Command Output
+
+```typescript
+GET /sandbox/:id/exec-stream?command=npm%20install
+```
+
+```typescript
+import { parseSSEStream } from '@treesap/sandbox';
+
+const stream = await sandbox.execStream('npm install');
+
+for await (const event of parseSSEStream(stream)) {
+  switch (event.type) {
+    case 'stdout':
+      console.log('Output:', event.data);
+      break;
+    case 'stderr':
+      console.error('Error:', event.data);
+      break;
+    case 'complete':
+      console.log('Exit code:', event.exitCode);
+      break;
+  }
+}
+```
+
+### Process Management
+
+#### Start a Background Process
+
+```typescript
+POST /sandbox/:id/process
+```
+
+```typescript
+const process = await sandbox.startProcess('python -m http.server 8000');
+console.log('Started with PID:', process.pid);
+```
+
+#### List Processes
+
+```typescript
+GET /sandbox/:id/process
+```
+
+```typescript
+const processes = await sandbox.listProcesses();
+```
+
+#### Get Process Info
+
+```typescript
+GET /sandbox/:id/process/:processId
+```
+
+```typescript
+const info = await sandbox.getProcess(processId);
+```
+
+#### Kill a Process
+
+```typescript
+DELETE /sandbox/:id/process/:processId?signal=SIGTERM
+```
+
+```typescript
+await sandbox.killProcess(processId, 'SIGTERM');
+```
+
+#### Stream Process Logs
+
+```typescript
+GET /sandbox/:id/process/:processId/logs
+```
+
+```typescript
+const stream = await sandbox.streamProcessLogs(processId);
+
+for await (const event of parseSSEStream(stream)) {
+  console.log(`[${event.timestamp}] ${event.data}`);
+}
+```
+
+### File Operations
+
+#### List Files
+
+```typescript
+GET /sandbox/:id/files?path=.&recursive=true&pattern=*.js
+```
+
+```typescript
+const files = await sandbox.listFiles('.', {
+  recursive: true,
+  pattern: '*.js',
+  includeHidden: false
+});
+
+files.forEach(file => {
+  console.log(file.name, file.type, file.size);
+});
+```
+
+#### Read File
+
+```typescript
+GET /sandbox/:id/files/path/to/file.txt
+```
+
+```typescript
+const content = await sandbox.readFile('package.json');
+console.log(content);
+```
+
+#### Write File
+
+```typescript
+POST /sandbox/:id/files/path/to/file.txt
+```
+
+```typescript
+await sandbox.writeFile('README.md', '# Hello World');
+```
+
+#### Delete File
+
+```typescript
+DELETE /sandbox/:id/files/path/to/file.txt?recursive=true
+```
+
+```typescript
+await sandbox.deleteFile('node_modules', { recursive: true });
+```
+
+## Use Cases
+
+### AI Agent Code Execution
+
+```typescript
+const sandbox = await SandboxClient.create('http://localhost:3000');
+
+// Agent writes code
+await sandbox.writeFile('script.py', `
+import pandas as pd
+print(pd.__version__)
+`);
+
+// Agent installs dependencies
+await sandbox.exec('pip install pandas');
+
+// Agent runs code
+const result = await sandbox.exec('python script.py');
+console.log(result.stdout);
+
+// Cleanup
+await sandbox.destroy({ cleanup: true });
+```
+
+### Running Tests in Isolation
+
+```typescript
+const sandbox = await SandboxClient.create('http://localhost:3000');
+
+// Clone repo
+await sandbox.exec('git clone https://github.com/user/repo.git');
+await sandbox.exec('cd repo && npm install');
+
+// Run tests
+const testResult = await sandbox.exec('cd repo && npm test');
+
+console.log('Tests passed:', testResult.success);
+```
+
+### Long-Running Services
+
+```typescript
+const sandbox = await SandboxClient.create('http://localhost:3000');
+
+// Start a web server
+const server = await sandbox.startProcess('node server.js');
+
+// Monitor logs in real-time
+const logStream = await sandbox.streamProcessLogs(server.id);
+
+for await (const log of parseSSEStream(logStream)) {
+  console.log('[Server]', log.data);
+
+  if (log.data.includes('Server started')) {
+    console.log('Server is ready!');
+    break;
+  }
+}
+
+// Later: stop the server
+await sandbox.killProcess(server.id);
+```
+
+## Server Configuration
+
+### CLI Options
+
+```bash
+treesap-sandbox [options]
+
+Options:
+  -p, --port <port>            Port to listen on (default: 3000)
+  -h, --host <host>            Host to bind to (default: 0.0.0.0)
+  -b, --base-path <path>       Base path for sandbox folders (default: ./.sandboxes)
+  -m, --max-sandboxes <num>    Maximum number of sandboxes (default: 100)
+  --cors                       Enable CORS (default: false)
+  --help                       Show this help message
+```
+
+### Programmatic Configuration
+
+```typescript
+import { startServer } from '@treesap/sandbox';
+
+const { server, manager } = await startServer({
+  port: 3000,
+  host: '0.0.0.0',
+  basePath: './.sandboxes',
+  maxSandboxes: 100,
+  cors: true,
+});
+
+// Access sandbox manager directly
+const stats = manager.getStats();
+console.log('Active sandboxes:', stats.totalSandboxes);
+```
+
+## Architecture
+
+TreeSap Sandbox uses a simple, lightweight architecture:
+
+```
+┌─────────────────────────────────────┐
+│         Client SDK / API            │
+│    (HTTP REST + Server-Sent Events) │
+└──────────────┬──────────────────────┘
+               │
+               │ HTTP/REST
+               │
+┌──────────────▼──────────────────────┐
+│         API Server (Hono)           │
+│  - Sandbox Management               │
+│  - Command Execution                │
+│  - Process Management               │
+│  - File Operations                  │
+└──────────────┬──────────────────────┘
+               │
+               │
+┌──────────────▼──────────────────────┐
+│       Sandbox Manager               │
+│  - Creates isolated sandboxes       │
+│  - Manages lifecycle                │
+│  - Auto-cleanup                     │
+└──────────────┬──────────────────────┘
+               │
+               │
+┌──────────────▼──────────────────────┐
+│     Individual Sandboxes            │
+│  - Isolated working directory       │
+│  - Process spawning (child_process) │
+│  - File operations (fs)             │
+└─────────────────────────────────────┘
+```
+
+### Security Model
+
+- **Folder-based isolation**: Each sandbox operates in its own directory
+- **Path traversal prevention**: File operations are validated to prevent `../` attacks
+- **Process limits**: Configurable max processes per sandbox
+- **Automatic cleanup**: Idle sandboxes are cleaned up after 30 minutes
+- **Resource monitoring**: Optional timeout limits for commands
+
+> ⚠️ **Note**: This is folder-based isolation, not container-based. For production use with untrusted code, consider running the server inside a Docker container or VM for an additional security layer.
+
+## Comparison with Cloudflare Sandbox SDK
+
+| Feature | TreeSap Sandbox | Cloudflare Sandbox |
+|---------|----------------|-------------------|
+| Self-hosted | ✅ Yes | ❌ Cloud only |
+| Folder isolation | ✅ Yes | Container-based |
+| File operations | ✅ Full API | ✅ Full API |
+| Command execution | ✅ Yes | ✅ Yes |
+| Process management | ✅ Yes | ✅ Yes |
+| Streaming output | ✅ SSE | ✅ SSE |
+| Code interpreters | ⚠️ Planned | ✅ Python/JS |
+| Public URLs | ❌ No | ✅ Yes |
+| Platform | Node.js | Cloudflare Workers |
+
+## Advanced Usage
+
+### Using Core Components Directly
+
+```typescript
+import { Sandbox, FileService } from '@treesap/sandbox';
+
+// Create a sandbox directly (without server)
+const sandbox = new Sandbox({
+  workDir: '/tmp/my-sandbox',
+  timeout: 30000,
+});
+
+await sandbox.initialize();
+
+// Execute commands
+const result = await sandbox.exec('ls -la');
+
+// Use file service
+const fileService = new FileService(sandbox.workDir);
+await fileService.writeFile('test.txt', 'Hello!');
+const files = await fileService.listFiles();
+
+// Cleanup
+await sandbox.destroy({ cleanup: true });
+```
+
+### Custom Server Integration
+
+```typescript
+import { createServer, SandboxManager } from '@treesap/sandbox';
+import { serve } from '@hono/node-server';
+
+const { app, manager } = createServer({
+  basePath: '/custom/sandboxes',
+  maxSandboxes: 50,
+});
+
+// Add custom routes
+app.get('/custom-endpoint', (c) => {
+  const stats = manager.getStats();
+  return c.json({ stats });
+});
+
+// Start server
+serve({ fetch: app.fetch, port: 3000 });
+```
+
+## Contributing
+
+Contributions are welcome! Please check out the [GitHub repository](https://github.com/withtreesap/treesap) for more information.
+
+## License
+
+MIT
+
+## Related Projects
+
+- [Cloudflare Sandbox SDK](https://developers.cloudflare.com/sandbox/) - Cloud-based sandbox execution
+- [TreeSap](https://github.com/withtreesap/treesap) - AI agent framework
+
+---
+
+Built with ❤️ by the TreeSap Team

package/dist/api-server.d.ts

@@ -0,0 +1,41 @@
+import { Hono } from 'hono';
+import { SandboxManager } from './sandbox-manager';
+import { HttpExposureService } from './http-exposure-service';
+export interface ServerConfig {
+    port?: number;
+    host?: string;
+    basePath?: string;
+    maxSandboxes?: number;
+    cors?: boolean;
+    /**
+     * API keys for authentication. If empty or not provided, authentication is disabled.
+     * Can also be set via SANDBOX_API_KEYS environment variable (comma-separated).
+     */
+    apiKeys?: string[];
+    /**
+     * HTTP exposure configuration for Caddy integration
+     */
+    httpExposure?: {
+        caddyAdminUrl?: string;
+        baseDomain?: string;
+        protocol?: 'http' | 'https';
+        upstreamHost?: string;
+    };
+}
+/**
+ * Create and configure the API server
+ */
+export declare function createServer(config?: ServerConfig): {
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    manager: SandboxManager;
+    httpExposure: HttpExposureService;
+};
+/**
+ * Start the sandbox server
+ */
+export declare function startServer(config?: ServerConfig): Promise<{
+    server: import("@hono/node-server").ServerType;
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    manager: SandboxManager;
+}>;
+//# sourceMappingURL=api-server.d.ts.map

package/dist/api-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-server.d.ts","sourceRoot":"","sources":["../src/api-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAMnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB;;OAEG;IACH,YAAY,CAAC,EAAE;QACb,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,GAAE,YAAiB;;;;EAglBrD;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,MAAM,GAAE,YAAiB;;;;GAiB1D"}