Sandbox

An isolated, intelligent environment where AI agents can build, run, and manage applications. Oblien Sandbox provides fully-managed, secure development environments with complete file system access, Git integration, and real-time capabilities.

What is Sandbox?

Oblien Sandbox is a cloud-based development environment service that gives you complete control over an isolated Linux environment. Perfect for AI agents, automated workflows, and secure code execution.

Features

Full File System Access - Create, read, update, and delete files
Git Integration - Clone, commit, push, and manage repositories
Terminal Access - Execute commands in a secure environment
Real-Time Updates - WebSocket for file watching and live terminal
Snapshot Management - Save and restore environment states
Fast Search - Search file contents and names instantly
Browser Automation - Screenshots, page content, network monitoring

Architecture

┌─────────────────────────────────────────┐
│         Your Application                │
│  (AI Agent, Automation, Developer)      │
└────────────────┬────────────────────────┘
                 │
                 │ HTTPS API / WebSocket
                 ↓
┌─────────────────────────────────────────┐
│         Oblien Sandbox Service          │
│                                         │
│  • Managed Sandbox Instances            │
│  • Automatic Scaling                    │
│  • High Availability                    │
└────────────────┬────────────────────────┘
                 │
                 ↓
┌─────────────────────────────────────────┐
│    Your Isolated Environment            │
│  • File System (/opt/app)               │
│  • Git Repository                       │
│  • Terminal Environment                 │
│  • Node.js, npm, bun, Python            │
└─────────────────────────────────────────┘

Key Features

Isolation & Security

Each sandbox runs in a completely isolated environment:

Dedicated file system and resources
Controlled network access
Automatic cleanup and management
Token-based authentication

Real-Time Operations

Stream data and updates in real-time:

WebSocket for instant updates
File watcher for change notifications
Terminal streaming with live output
Event-driven architecture

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 Travel

Snapshot management for instant rollback:

Create checkpoints of entire environment
Restore to any previous state
Archive and restore full repositories
Automatic cleanup

Use Cases

AI Agent Workspaces

Perfect for AI coding assistants:

import { OblienClient } from 'agent-sandbox';

const client = new OblienClient({
  clientId: process.env.OBLIEN_CLIENT_ID,
  clientSecret: process.env.OBLIEN_CLIENT_SECRET
});

// Create sandbox
const sandbox = await client.createSandbox({ name: 'ai-workspace' });

// 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({ repoPath: '/opt/app', files: ['.'] });
await sandbox.git.commit({ 
  repoPath: '/opt/app',
  message: 'AI improvements' 
});

// Create sandbox
const authResponse = await fetch('https://api.oblien.com/sandboxes', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ name: 'ai-workspace' })
});
const { token, url } = await authResponse.json();

// Clone repository
await fetch(`${url}/git/clone`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://github.com/user/repo',
    targetDir: '/opt/app'
  })
});

// Read file
const fileResponse = await fetch(`${url}/files/get`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ filePath: '/opt/app/src/index.js' })
});
const { content } = await fileResponse.json();

// Edit file
await fetch(`${url}/files/edit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/src/index.js',
    content: improvedCode
  })
});

// Commit changes
await fetch(`${url}/git/add`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    repoPath: '/opt/app',
    files: ['.']
  })
});

await fetch(`${url}/git/commit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    repoPath: '/opt/app',
    message: 'AI improvements'
  })
});

# Create sandbox
SANDBOX=$(curl -X POST https://api.oblien.com/sandboxes \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ai-workspace"}')

SANDBOX_URL=$(echo $SANDBOX | jq -r '.url')
SANDBOX_TOKEN=$(echo $SANDBOX | jq -r '.token')

# Clone repository
curl -X POST $SANDBOX_URL/git/clone \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo",
    "targetDir": "/opt/app"
  }'

# Read file
curl -X POST $SANDBOX_URL/files/get \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/opt/app/src/index.js"}'

# Edit file
curl -X POST $SANDBOX_URL/files/edit \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filePath": "/opt/app/src/index.js",
    "content": "// improved code here"
  }'

# Commit changes
curl -X POST $SANDBOX_URL/git/add \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repoPath": "/opt/app", "files": ["."]}'

curl -X POST $SANDBOX_URL/git/commit \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repoPath": "/opt/app",
    "message": "AI improvements"
  }'

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',
  cwd: '/opt/app'
});

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

// Create snapshot
const snapshotResponse = await fetch(`${sandbox.url}/snapshots/commit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ message: 'Pre-test state' })
});

// Run tests
await fetch(`${sandbox.url}/terminal/execute`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'npm test',
    cwd: '/opt/app'
  })
});

// Rollback if needed
await fetch(`${sandbox.url}/snapshots/goto`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ commitHash: previousHash })
});

# Create snapshot
curl -X POST $SANDBOX_URL/snapshots/commit \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Pre-test state"}'

# Run tests
curl -X POST $SANDBOX_URL/terminal/execute \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm test",
    "cwd": "/opt/app"
  }'

# Rollback if needed
curl -X POST $SANDBOX_URL/snapshots/goto \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commitHash": "PREVIOUS_COMMIT_HASH"}'

Code Review & Validation

Validate code changes safely:

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

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

// Clone PR branch
await fetch(`${sandbox.url}/git/clone`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: repo,
    targetDir: '/opt/app',
    branch: 'pr-123'
  })
});

// Run validation
await fetch(`${sandbox.url}/terminal/execute`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'npm run lint && npm run build',
    cwd: '/opt/app'
  })
});

# Clone PR branch
curl -X POST $SANDBOX_URL/git/clone \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/user/repo",
    "targetDir": "/opt/app",
    "branch": "pr-123"
  }'

# Run validation
curl -X POST $SANDBOX_URL/terminal/execute \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "npm run lint && npm run build",
    "cwd": "/opt/app"
  }'

API Overview

The Sandbox API provides comprehensive endpoints:

Category	Features
Files	List, read, create, edit, delete, rename files
Git	Clone, commit, push, pull, branches, history
Search	Search file contents and filenames
Terminal	Execute commands (REST and real-time)
Snapshots	Create checkpoints, restore states
Browser	Screenshots, page content, network monitoring
WebSocket	Real-time terminal and file watcher

Getting Started

Ready to use Sandbox? Check out these guides:

Quick Start - Get started in 5 minutes
Authentication - Authenticate and create sandboxes
File Operations - Work with files
Git Operations - Use Git in your sandbox
WebSocket - Real-time communication

On this page