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: 'ai@example.com' }
});

// 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: 'john@example.com' }
});

// 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: support@oblien.com
• 💬 Discord: discord.gg/oblien
• 🐛 Issues: GitHub Issues

License

MIT © Oblien

---

Made with ❤️ by Oblien