agent-sandbox

A powerful Node.js SDK for interacting with the Oblien Sandbox API. Build, run, and manage isolated development environments programmatically with full file system access, Git integration, and real-time capabilities.

Perfect for AI agents, automated workflows, and secure code execution.

📚 Full Documentation

Installation

npm install agent-sandbox

Quick Start

import { OblienClient } from 'agent-sandbox';

// 1. Authenticate with your Oblien account
const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

// 2. Create a sandbox - returns ready-to-use client!
const sandbox = await client.createSandbox({
  name: 'my-dev-sandbox'
});

// 3. Start using it immediately
await sandbox.files.list({ dirPath: '/opt/app' });
await sandbox.files.create({
  fullPath: '/opt/app/index.js',
  content: 'console.log("Hello World!");'
});
await sandbox.git.clone({
  url: 'https://github.com/user/repo',
  targetDir: '/opt/app'
});

Get your API credentials: oblien.com/dashboard/api

Core Features

| Feature | Description | Documentation | |---------|-------------|---------------| | 🔐 Authentication | Two-tier auth with client credentials and sandbox tokens | Docs | | 📦 Sandbox Management | Create, start, stop, and manage sandbox instances | Docs | | 🗂️ File Operations | Complete CRUD operations for files and directories | Docs | | 📂 Git Integration | Full Git workflow support (clone, commit, push, branches) | Docs | | 🔍 Search | Fast search across file contents and names | Docs | | 💻 Terminal | Execute commands with real-time streaming | Docs | | 📸 Snapshots | Create checkpoints and restore environment states | Docs | | 🌐 Browser Automation | Screenshots, page content, network monitoring | Docs | | 🗄️ Database Management | Full SQLite database operations, schema, and queries | Docs | | 🔌 WebSocket | Real-time file watching and terminal streaming | Docs | | 💪 TypeScript | Full type definitions included | - |

Usage Examples

Working with Files

// List files
const files = await sandbox.files.list({ 
  dirPath: '/opt/app',
  recursive: true
});

// Read file
const content = await sandbox.files.get({ 
  filePath: '/opt/app/index.js'
});

// Create file
await sandbox.files.create({
  fullPath: '/opt/app/hello.js',
  content: 'console.log("Hello!");'
});

→ Full File Operations Guide

Git Workflow

// Clone repository
await sandbox.git.clone({
  url: 'https://github.com/user/repo',
  targetDir: '/opt/app'
});

// Make changes and commit
await sandbox.git.add({ repoPath: '/opt/app', files: ['.'] });
await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'Update code',
  author: { name: 'AI Agent', email: '[email protected]' }
});

// Push changes
await sandbox.git.push({ repoPath: '/opt/app' });

→ Full Git Integration Guide

Real-Time Terminal

// Create interactive terminal
const terminal = await sandbox.terminal.create({
  cols: 120,
  rows: 30,
  cwd: '/opt/app',
  onData: (data) => console.log(data),
  onExit: (code) => console.log('Exit:', code)
});

// Execute commands
terminal.write('npm install\n');
terminal.write('npm test\n');

→ Full Terminal Guide

File Watching

// Watch for file changes
await sandbox.watcher.start({
  ignorePatterns: ['node_modules', '.git'],
  onChange: (path) => console.log('Changed:', path),
  onAdd: (path) => console.log('Added:', path),
  onUnlink: (path) => console.log('Deleted:', path)
});

→ Full File Watcher Guide

Browser Automation

// Take screenshot
const screenshot = await sandbox.browser.screenshot({
  url: 'https://example.com',
  width: 1920,
  height: 1080,
  fullPage: true
});

// Get page content
const content = await sandbox.browser.getPageContent({
  url: 'https://example.com',
  waitFor: 1000
});

→ Full Browser Automation Guide

Database Management

// Create a database
await sandbox.database.createDatabase({ name: 'myapp' });

// Create a table
await sandbox.database.createTable({
  database: 'myapp',
  tableName: 'users',
  columns: [
    { name: 'id', type: 'INTEGER', primaryKey: true, autoIncrement: true },
    { name: 'name', type: 'TEXT', notNull: true },
    { name: 'email', type: 'TEXT', unique: true }
  ]
});

// Insert data
await sandbox.database.insertRow({
  database: 'myapp',
  table: 'users',
  data: { name: 'John Doe', email: '[email protected]' }
});

// Query data
const result = await sandbox.database.getTableData({
  database: 'myapp',
  table: 'users',
  limit: 10,
  sortBy: 'id',
  sortOrder: 'desc'
});

// Execute custom query
await sandbox.database.executeQuery({
  database: 'myapp',
  query: 'SELECT * FROM users WHERE name LIKE ?',
  params: ['%John%']
});

// Export to JSON
const jsonData = await sandbox.database.exportTableToJSON('myapp', 'users');

→ Full Database Management Guide

Advanced Usage

Connect to Existing Sandbox

// By sandbox ID
const sandbox = await client.sandbox('sandbox_abc123');

// Or with direct token
import { SandboxClient } from 'agent-sandbox';

const sandbox = new SandboxClient({
  token: 'your_sandbox_token'
});

TypeScript Support

Full TypeScript definitions included:

import { 
  SandboxClient, 
  FileListOptions,
  TableCreateOptions 
} from 'agent-sandbox';

const options: FileListOptions = {
  dirPath: '/opt/app',
  recursive: true
};

const files = await sandbox.files.list(options);

// Database operations with full type safety
const tableOptions: TableCreateOptions = {
  database: 'myapp',
  tableName: 'users',
  columns: [
    { name: 'id', type: 'INTEGER', primaryKey: true }
  ]
};

await sandbox.database.createTable(tableOptions);

Error Handling

try {
  const files = await sandbox.files.list({ dirPath: '/opt/app' });
} catch (error) {
  console.error('Error:', error.message);
}

Documentation

| Resource | Link | |----------|------| | 📖 Complete Documentation | oblien.com/docs/sandbox | | 🚀 Quick Start Guide | oblien.com/docs/sandbox/quick-start | | 🔐 Authentication | oblien.com/docs/sandbox/authentication | | 🗂️ File Operations | oblien.com/docs/sandbox/file-operations | | 📂 Git Integration | oblien.com/docs/sandbox/git-clone | | 💻 Terminal | oblien.com/docs/sandbox/terminal | | 📸 Snapshots | oblien.com/docs/sandbox/snapshots | | 🌐 Browser Automation | oblien.com/docs/sandbox/browser | | 🗄️ Database Management | oblien.com/docs/sandbox/database | | 🔌 WebSocket & Real-time | oblien.com/docs/sandbox/websocket |

Support

• 📧 Email: [email protected]
• 💬 Discord: discord.gg/oblien
• 🐛 Issues: GitHub Issues

License

MIT © Oblien

Made with ❤️ by Oblien