Quick Start Guide

Get up and running with the Oblien Sandbox in minutes.

Base URL

All API requests are made to:

https://sandbox.oblien.com:55872

Or for local development:

http://localhost:55872

Installation

Install the Oblien Sandbox SDK:

npm install @oblien/sandbox-sdk

Or use direct HTTP requests with any HTTP client.

SDK Setup

Initialize the SDK with your authentication token:

import { SandboxClient } from '@oblien/sandbox-sdk';

const sandbox = new SandboxClient({
  baseURL: 'https://sandbox.oblien.com:55872',
  token: 'your-auth-token-here'
});

Your First Operation

Let's create a file, edit it, and commit the changes:

1. List Files

// Using SDK
const files = await sandbox.files.list({
  dirPath: '/opt/app'
});

console.log(files);

POST /files/list HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer your-auth-token
Content-Type: application/json

{
  "dirPath": "/opt/app"
}

Response:

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

2. Read a File

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

console.log(content.content);

POST /files/get HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer your-auth-token
Content-Type: application/json

{
  "filePath": "/opt/app/index.js",
  "withLineNumbers": true
}

Response:

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

3. Create a New File

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

POST /files/create HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer your-auth-token
Content-Type: application/json

{
  "filePath": "/opt/app/hello.js",
  "content": "console.log(\"Hello from Sandbox!\");"
}

Response:

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

4. Execute a Command

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

console.log(result.output);

POST /terminal HTTP/1.1
Host: sandbox.oblien.com:55872
Authorization: Bearer your-auth-token
Content-Type: application/json

{
  "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'
});

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: ['README.md']
});

// 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'
});

Search for Code

// Search file contents
const results = await sandbox.search.content({
  query: 'function',
  options: {
    caseSensitive: false,
    maxResults: 50
  }
});

console.log(results.matches);

Error Handling

All API responses follow this structure:

Success:

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

Error:

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

Example error handling:

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

Next Steps

Now that you know the basics:

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

On this page