Sandbox Environment

Oblien's Sandbox provides isolated, containerized environments designed for AI agents, automated workflows, and secure code execution.

What is Sandbox?

The Sandbox is a fully-featured development environment running in an isolated Docker container. It provides AI agents and developers with complete control over a Linux environment, including:

• Full File System Access - Create, read, update, and delete any files
• Git Integration - Clone repositories, commit changes, and push code
• Terminal Access - Execute any command in a secure environment
• Real-Time Communication - WebSocket for streaming updates
• Snapshot Management - Save and restore environment states instantly
• Fast Search - Search files and content with blazing speed

Architecture

┌─────────────────────────────────────────┐
│         Your Application                │
│  (AI Agent, Automation, Developer)      │
└────────────────┬────────────────────────┘
                 │
                 │ HTTPS API / WebSocket
                 ↓
┌─────────────────────────────────────────┐
│       Sandbox Manager API               │
│         (Port: 55872)                   │
└────────────────┬────────────────────────┘
                 │
                 │ Docker API
                 ↓
┌─────────────────────────────────────────┐
│    Isolated Docker Container            │
│  • File System (/opt/app)               │
│  • Git Repository                       │
│  • Terminal Environment                 │
│  • Node.js, npm, bun                    │
└─────────────────────────────────────────┘

Key Features

Isolation & Security

Each sandbox runs in a completely isolated Docker container:

• No access to host system
• Dedicated file system
• Controlled network access
• Automatic cleanup on termination

Real-Time Operations

Stream data and updates in real-time:

• WebSocket protocol for instant updates
• File watcher notifies on file changes
• Terminal streaming with live output
• Git operations with progress updates

Complete File Control

Full CRUD operations on files and directories:

• List directory contents with metadata
• Read files with line ranges and numbers
• Create/edit files with atomic operations
• Merge changes with smart conflict detection

Git Powerhouse

Full Git workflow support:

• Clone any repository (GitHub, GitLab, Bitbucket)
• Create, checkout, and merge branches
• Stage, commit, and push changes
• View history and diffs
• SSH and token authentication

Time Machine

Snapshot management for instant rollback:

• Create checkpoints of entire environment
• Restore to any previous state
• Archive and restore full repositories
• Cleanup old snapshots automatically

Use Cases

AI Agent Workspaces

Perfect for AI coding assistants like Blurs AI:

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

// Read and modify files
const content = await sandbox.files.get({ filePath: '/opt/app/src/index.js' });
await sandbox.files.edit({
  filePath: '/opt/app/src/index.js',
  content: improvedCode
});

// Commit changes
await sandbox.git.add({ files: ['/opt/app/src/index.js'] });
await sandbox.git.commit({ message: 'AI improvements' });
await sandbox.git.push();

Automated Testing

Run tests in clean, isolated environments:

// Create snapshot before tests
await sandbox.snapshots.commit({ message: 'Pre-test state' });

// Run tests
await sandbox.terminal.execute({ command: 'npm test' });

// Rollback if needed
await sandbox.snapshots.goto({ commitHash: previousHash });

Code Review & Validation

Validate code changes safely:

// Clone PR branch
await sandbox.git.clone({ url: repo, branch: 'pr-123' });

// Run validation
await sandbox.terminal.execute({ command: 'npm run lint' });
await sandbox.terminal.execute({ command: 'npm run build' });

API Overview

The Sandbox Manager exposes a RESTful API on port 55872:

Getting Started

Ready to use the Sandbox? Check out these guides:

• Quick Start - Get started in 5 minutes
• Authentication - Secure your sandbox
• File Operations - Work with files
• Git Operations - Use Git in sandbox
• WebSocket - Real-time communication