Terminal

Execute shell commands in your sandbox environment. For real-time terminal access, see WebSocket Terminal.

Execute Command

Run a shell command and get the output:

const result = await sandbox.terminal.execute({
  command: 'npm install',
  cwd: '/opt/app',
  timeout: 60000
});

console.log('Output:', result.output);
console.log('Exit code:', result.exitCode);

const response = 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',
    timeout: 60000
  })
});

const result = await response.json();

curl -X POST https://sandbox.oblien.com/terminal \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Response:

{
  "success": true,
  "output": "added 142 packages in 8s",
  "error": "",
  "exitCode": 0,
  "duration": 8234
}

Parameters

Parameter	Type	Required	Description
`command`	string	Yes	Shell command to execute
`cwd`	string	No	Working directory (default: /opt/app)
`env`	object	No	Environment variables
`timeout`	number	No	Timeout in ms (default: 30000)

With Environment Variables

const result = await sandbox.terminal.execute({
  command: 'npm run build',
  cwd: '/opt/app',
  env: {
    NODE_ENV: 'production',
    API_URL: 'https://api.example.com'
  }
});

const response = 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',
    env: {
      NODE_ENV: 'production',
      API_URL: 'https://api.example.com'
    }
  })
});

curl -X POST https://sandbox.oblien.com/terminal \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Common Use Cases

Install Dependencies

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

// Or with specific package
await sandbox.terminal.execute({
  command: 'npm install express axios',
  cwd: '/opt/app'
});

Run Build

const result = await sandbox.terminal.execute({
  command: 'npm run build',
  cwd: '/opt/app',
  env: { NODE_ENV: 'production' }
});

if (result.exitCode === 0) {
  console.log('Build successful');
} else {
  console.error('Build failed:', result.error);
}

Run Tests

const result = await sandbox.terminal.execute({
  command: 'npm test',
  cwd: '/opt/app',
  timeout: 120000 // 2 minutes
});

console.log('Test output:', result.output);

List Files

const result = await sandbox.terminal.execute({
  command: 'ls -la',
  cwd: '/opt/app'
});

console.log(result.output);

Check Node Version

const result = await sandbox.terminal.execute({
  command: 'node --version'
});

console.log('Node version:', result.output.trim());

Run Python Script

const result = await sandbox.terminal.execute({
  command: 'python3 script.py',
  cwd: '/opt/app',
  env: {
    PYTHONPATH: '/opt/app/lib'
  }
});

Complete Example

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

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

// Run linter
console.log('Running linter...');
const lintResult = await sandbox.terminal.execute({
  command: 'npm run lint',
  cwd: '/opt/app'
});

if (lintResult.exitCode !== 0) {
  console.error('Lint errors:', lintResult.output);
}

// Run tests
console.log('Running tests...');
const testResult = await sandbox.terminal.execute({
  command: 'npm test',
  cwd: '/opt/app',
  timeout: 120000
});

if (testResult.exitCode === 0) {
  console.log('All tests passed!');
} else {
  console.error('Tests failed');
}

// Build for production
console.log('Building...');
await sandbox.terminal.execute({
  command: 'npm run build',
  cwd: '/opt/app',
  env: {
    NODE_ENV: 'production'
  }
});

console.log('Done!');

// Clone repository (assuming already done)

// Install dependencies
console.log('Installing dependencies...');
let response = 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'
  })
});

await response.json();

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

const testResult = await response.json();

if (testResult.exitCode === 0) {
  console.log('All tests passed!');
}

curl -X POST https://sandbox.oblien.com/terminal \
  -H "Authorization: Bearer YOUR_SANDBOX_TOKEN" \
  -H "Content-Type: application/json"

Error Handling

try {
  const result = await sandbox.terminal.execute({
    command: 'npm run invalid-script',
    cwd: '/opt/app'
  });
  
  if (result.exitCode !== 0) {
    console.error('Command failed with exit code:', result.exitCode);
    console.error('Error output:', result.error);
  }
} catch (error) {
  console.error('Execution error:', error);
}

Response Fields

Field	Type	Description
`success`	boolean	Whether execution completed
`output`	string	Standard output (stdout)
`error`	string	Standard error (stderr)
`exitCode`	number	Process exit code (0 = success)
`duration`	number	Execution time in ms

Limitations

Timeout: Commands are limited by timeout (default 30s)
Non-interactive: Cannot handle interactive prompts
One-shot: Each command runs in a new shell session
Output buffering: Large outputs may be truncated

For Interactive Use

For interactive terminal sessions, use WebSocket-based terminals:

// Create real-time terminal
const terminal = await sandbox.terminal.create({
  cols: 120,
  rows: 30,
  cwd: '/opt/app',
  onData: (data) => console.log(data)
});

// Send commands
terminal.write('npm install\n');
terminal.write('npm run dev\n');

See WebSocket for real-time terminal access.

Best Practices

Set appropriate timeouts: Long-running commands need higher timeouts
Check exit codes: Always verify exitCode === 0 for success
Handle errors: Read error field for stderr output
Use working directory: Set cwd for correct context
Pass environment variables: Use env for configuration

Next Steps

WebSocket - Real-time terminal access
File Operations - Work with files
Git Operations - Git commands

On this page