Terminal

Execute shell commands in your isolated sandbox environment with full terminal access.

Execute Command

Run any shell command in your sandbox.

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

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

POST /terminal HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "command": "npm install",
  "cwd": "/opt/app"
}

Response:

{
  "success": true,
  "output": "added 142 packages in 5.2s\n",
  "exitCode": 0,
  "duration": 5234
}

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	Command timeout in ms (default: 30000)

Common Commands

Package Management

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

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

// Using Bun (faster)
await sandbox.terminal.execute({
  command: 'bun install',
  cwd: '/opt/app'
});

Build & Test

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

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

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

File Operations

// Create directory
await sandbox.terminal.execute({
  command: 'mkdir -p /opt/app/src/components',
  cwd: '/opt/app'
});

// Copy files
await sandbox.terminal.execute({
  command: 'cp config.example.json config.json',
  cwd: '/opt/app'
});

// Find files
await sandbox.terminal.execute({
  command: 'find . -name "*.js" -type f',
  cwd: '/opt/app'
});

Check Environment

// Check Node.js version
const node = await sandbox.terminal.execute({
  command: 'node --version'
});

// Check npm version
const npm = await sandbox.terminal.execute({
  command: 'npm --version'
});

// List environment variables
const env = await sandbox.terminal.execute({
  command: 'printenv'
});

Environment Variables

Pass custom environment variables:

await sandbox.terminal.execute({
  command: 'echo $API_KEY',
  env: {
    API_KEY: 'secret-key-here',
    NODE_ENV: 'production'
  }
});

POST /terminal HTTP/1.1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "command": "npm run build",
  "env": {
    "NODE_ENV": "production",
    "API_URL": "https://api.example.com"
  }
}

Working Directory

Specify the working directory for commands:

// Run in specific directory
await sandbox.terminal.execute({
  command: 'ls -la',
  cwd: '/opt/app/src'
});

// Chain commands
await sandbox.terminal.execute({
  command: 'cd /opt/app && npm install && npm run build'
});

Long-Running Commands

For commands that take time:

// Set longer timeout
const result = await sandbox.terminal.execute({
  command: 'npm run build',
  cwd: '/opt/app',
  timeout: 300000 // 5 minutes
});

ℹ️ Info: For real-time output from long-running commands, use WebSocket terminal streaming instead.

Command Chaining

Execute multiple commands:

// Using && for sequential execution
await sandbox.terminal.execute({
  command: 'npm install && npm run build && npm test',
  cwd: '/opt/app',
  timeout: 180000 // 3 minutes
});

// Using ; for independent execution
await sandbox.terminal.execute({
  command: 'mkdir -p dist; rm -rf dist/*; npm run build',
  cwd: '/opt/app'
});

Exit Codes

Handle command success/failure:

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

if (result.exitCode === 0) {
  console.log('Tests passed!');
} else {
  console.log('Tests failed');
  console.log('Output:', result.output);
}

Common Workflows

Setup New Project

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

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

// 3. Start development server
await sandbox.terminal.execute({
  command: 'npm run dev &',
  cwd: '/opt/app'
});

Run Tests

// Run all tests
const tests = await sandbox.terminal.execute({
  command: 'npm test',
  cwd: '/opt/app'
});

if (tests.exitCode !== 0) {
  console.log('Tests failed:', tests.output);
}

Check Code Quality

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

// Run type checking
const typecheck = await sandbox.terminal.execute({
  command: 'npm run typecheck',
  cwd: '/opt/app'
});

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

Security Considerations

⚠️ Warning: The sandbox terminal has full access to the container environment. Be cautious with:

Commands that modify system files

Commands that install global packages

Commands that access network resources

Safe commands:

// ✅ Safe - operates within /opt/app
await sandbox.terminal.execute({ command: 'npm install' });
await sandbox.terminal.execute({ command: 'ls -la' });
await sandbox.terminal.execute({ command: 'cat package.json' });

Potentially dangerous:

// ⚠️ Be careful with these
await sandbox.terminal.execute({ command: 'rm -rf /' }); // Destructive
await sandbox.terminal.execute({ command: 'curl external-api' }); // Network access

Error Handling

try {
  const result = await sandbox.terminal.execute({
    command: 'npm run nonexistent-script',
    cwd: '/opt/app'
  });
} catch (error) {
  console.log('Command failed:', error.message);
}

// Or check exit code
const result = await sandbox.terminal.execute({ command: 'npm test' });
if (result.exitCode !== 0) {
  console.log('Command failed with exit code:', result.exitCode);
  console.log('Error output:', result.output);
}

Best Practices

1. Set Appropriate Timeouts

// Quick commands - short timeout
await sandbox.terminal.execute({
  command: 'ls',
  timeout: 5000 // 5 seconds
});

// Build commands - long timeout
await sandbox.terminal.execute({
  command: 'npm run build',
  timeout: 300000 // 5 minutes
});

2. Check Exit Codes

const result = await sandbox.terminal.execute({ command: 'npm test' });

if (result.exitCode === 0) {
  console.log('Success');
} else {
  throw new Error('Command failed');
}

3. Use WebSocket for Long Commands

For long-running commands with streaming output, use WebSocket:

// Better for long-running commands
const ws = await sandbox.websocket.connect();

ws.send({
  type: 'terminal',
  command: 'npm run dev'
});

ws.on('message', (data) => {
  console.log('Output:', data.output);
});

Next Steps

Set up WebSocket for real-time terminal
Learn about Search for finding code
Explore File Operations

On this page