Quick Start Guide

Get up and running with Oblien Sandbox in minutes. This guide will walk you through creating a sandbox, working with files, and executing commands.

Installation

Install the agent-sandbox npm package:

npm install agent-sandbox

No installation required. Use any HTTP client like fetch, axios, or curl.

No installation required. curl is typically pre-installed on most systems.

Authentication

Get your client credentials from oblien.com/dashboard/api.

import { OblienClient } from 'agent-sandbox';

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

Store your credentials as environment variables or in a secure configuration:

# .env
OBLIEN_CLIENT_ID=your_client_id
OBLIEN_CLIENT_SECRET=your_client_secret

Store credentials as environment variables:

export OBLIEN_CLIENT_ID="your_client_id"
export OBLIEN_CLIENT_SECRET="your_client_secret"

Create a Sandbox

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

// The sandbox is ready to use immediately
await sandbox.files.list({ dirPath: '/opt/app' });

const response = await fetch('https://api.oblien.com/sandbox', {
  method: 'POST',
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'my-dev-sandbox'
  })
});

const { sandbox } = await response.json();
// Save sandbox.url and sandbox.token for subsequent requests

curl -X POST https://api.oblien.com/sandbox \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-dev-sandbox"}'

Response:

{
  "success": true,
  "sandbox": {
    "id": "sandbox_abc123",
    "name": "my-dev-sandbox",
    "url": "https://sandbox.oblien.com",
    "token": "sandbox_token_xyz...",
    "status": "active",
    "region": "us-east-1",
    "createdAt": "2025-10-26T12:00:00Z"
  }
}

List Files

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

console.log(result.files);

const response = await fetch(`${sandbox.url}/files/list`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    dirPath: '/opt/app',
    recursive: false
  })
});

const result = await response.json();
console.log(result.files);

curl -X POST https://sandbox.oblien.com/files/list \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "dirPath": "/opt/app",
    "recursive": false
  }'

Response:

{
  "success": true,
  "files": [
    {
      "name": "index.js",
      "path": "/opt/app/index.js",
      "type": "file",
      "size": 1024,
      "modified": "2025-10-26T12:00:00Z"
    }
  ]
}

Read a File

const result = await sandbox.files.get({
  filePath: '/opt/app/index.js',
  withLineNumbers: true
});

console.log(result.content);

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

const result = await response.json();
console.log(result.content);

curl -X POST https://sandbox.oblien.com/files/get \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filePath": "/opt/app/index.js",
    "withLineNumbers": true
  }'

Response:

{
  "success": true,
  "content": "console.log('Hello World');",
  "path": "/opt/app/index.js",
  "size": 28
}

Create a File

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

await fetch(`${sandbox.url}/files/create`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fullPath: '/opt/app/hello.js',
    content: 'console.log("Hello from Sandbox!");'
  })
});

curl -X POST https://sandbox.oblien.com/files/create \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fullPath": "/opt/app/hello.js",
    "content": "console.log(\"Hello from Sandbox!\");"
  }'

Response:

{
  "success": true,
  "message": "File created successfully",
  "path": "/opt/app/hello.js"
}

Execute a Command

const result = await sandbox.terminal.execute({
  command: 'node hello.js',
  cwd: '/opt/app'
});

console.log(result.output); // "Hello from Sandbox!"

const response = await fetch(`${sandbox.url}/terminal`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    command: 'node hello.js',
    cwd: '/opt/app'
  })
});

const result = await response.json();
console.log(result.output); // "Hello from Sandbox!"

curl -X POST https://sandbox.oblien.com/terminal \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "node hello.js",
    "cwd": "/opt/app"
  }'

Response:

{
  "success": true,
  "output": "Hello from Sandbox!\n",
  "exitCode": 0
}

Common Workflows

Clone and Build a Project

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

// Install dependencies
await sandbox.terminal.execute({
  command: 'npm install',
  cwd: '/opt/app'
});

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

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

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

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

# 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/project",
    "targetDir": "/opt/app"
  }'

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

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

Make Changes and Commit

// Edit a file
await sandbox.files.edit({
  filePath: '/opt/app/README.md',
  content: '# Updated README\n\nNew content here.'
});

// Stage changes
await sandbox.git.add({
  repoPath: '/opt/app',
  files: ['.']
});

// Commit
await sandbox.git.commit({
  repoPath: '/opt/app',
  message: 'Update README',
  author: {
    name: 'AI Agent',
    email: 'ai@oblien.com'
  }
});

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

// Edit a file
await fetch(`${sandbox.url}/files/edit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/opt/app/README.md',
    content: '# Updated README\n\nNew content here.'
  })
});

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

// Commit
await fetch(`${sandbox.url}/git/commit`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    repoPath: '/opt/app',
    message: 'Update README',
    author: {
      name: 'AI Agent',
      email: 'ai@oblien.com'
    }
  })
});

// Push to remote
await fetch(`${sandbox.url}/git/push`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    repoPath: '/opt/app'
  })
});

# Edit a file
curl -X POST $SANDBOX_URL/files/edit \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filePath": "/opt/app/README.md",
    "content": "# Updated README\n\nNew content here."
  }'

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

# Commit
curl -X POST $SANDBOX_URL/git/commit \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repoPath": "/opt/app",
    "message": "Update README",
    "author": {
      "name": "AI Agent",
      "email": "ai@oblien.com"
    }
  }'

# Push to remote
curl -X POST $SANDBOX_URL/git/push \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"repoPath": "/opt/app"}'

Connect to Existing Sandbox

// Connect to existing sandbox by ID
const sandbox = await client.sandbox('sandbox_abc123');

// Use it immediately
await sandbox.files.list({ dirPath: '/opt/app' });

Or if you already have a token:

import { SandboxClient } from 'agent-sandbox';

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

// Get sandbox details
const response = await fetch('https://api.oblien.com/sandbox/sandbox_abc123', {
  headers: {
    'X-Client-ID': process.env.OBLIEN_CLIENT_ID,
    'X-Client-Secret': process.env.OBLIEN_CLIENT_SECRET
  }
});

const { sandbox } = await response.json();
// Use sandbox.url and sandbox.token for subsequent requests

# Get sandbox details
curl https://api.oblien.com/sandbox/sandbox_abc123 \
  -H "X-Client-ID: $OBLIEN_CLIENT_ID" \
  -H "X-Client-Secret: $OBLIEN_CLIENT_SECRET"

# Then use the returned sandbox.url and sandbox.token for API calls

Error Handling

All API responses follow this structure:

Success:

{
  "success": true,
  "data": { ... }
}

Error:

{
  "success": false,
  "error": "Error message here"
}

try {
  const result = await sandbox.files.get({ 
    filePath: '/nonexistent.js' 
  });
} catch (error) {
  console.error('Error:', error.message);
}

const response = await fetch(`${sandbox.url}/files/get`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${sandbox.token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    filePath: '/nonexistent.js'
  })
});

const result = await response.json();
if (!result.success) {
  console.error('Error:', result.error);
}

curl -X POST $SANDBOX_URL/files/get \
  -H "Authorization: Bearer $SANDBOX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/nonexistent.js"}'

# Response will be:
# {"success": false, "error": "File not found"}

Next Steps

Now that you know the basics:

Learn about Authentication in detail
Explore File Operations
Discover Git Integration
Set up WebSocket for real-time updates
Manage Snapshots for version control

On this page