Overview Executes JavaScript/TypeScript code or shell commands in an existing session. The session’s filesystem and running processes persist between executions, enabling iterative development.
Request Bearer token with your API key
Request Body ID of the session to execute code in
JavaScript/TypeScript code to execute. Either code or command must be provided.
Shell command to run (e.g., bun run index.ts). Either code or command must be provided.
Array of files to write before execution File path relative to /workspace
File content (max 10MB per file)
Environment variables to set for this execution (max 100 variables)
Execution timeout in seconds. Default: 30, Max: 300 (5 minutes)
Working directory for execution. Default: /workspace
Stream output as Server-Sent Events. Default: false
Response Standard output from the execution
Process exit code (0 = success)
Execution time in milliseconds
Peak memory usage in bytes
CPU time used in milliseconds
Whether the execution was terminated due to timeout
Paths of files written during execution
Examples Execute Inline Code curl -X POST https://api.buntime.sh/execute \ -H "Authorization: Bearer $BUNTIME_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "sessionId": "ses_abc123", "code": "const result = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0); console.log(\"Sum:\", result);" }'
{ "stdout" : "Sum: 15 \n " , "stderr" : "" , "exitCode" : 0 , "executionTime" : 45 , "memoryUsed" : 12582912 , "cpuTime" : 42 , "timedOut" : false , "filesWritten" : [] }
Execute with Multiple Files curl -X POST https://api.buntime.sh/execute \ -H "Authorization: Bearer $BUNTIME_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "sessionId": "ses_abc123", "files": [ { "path": "utils.ts", "content": "export const add = (a: number, b: number) => a + b;" }, { "path": "index.ts", "content": "import { add } from \"./utils\";\nconsole.log(\"Result:\", add(5, 3));" } ], "command": "bun run index.ts" }'
{ "stdout" : "Result: 8 \n " , "stderr" : "" , "exitCode" : 0 , "executionTime" : 123 , "memoryUsed" : 18874368 , "cpuTime" : 115 , "timedOut" : false , "filesWritten" : [ "utils.ts" , "index.ts" ] }
Execute with Environment Variables curl -X POST https://api.buntime.sh/execute \ -H "Authorization: Bearer $BUNTIME_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "sessionId": "ses_abc123", "code": "console.log(\"API Key:\", process.env.API_KEY);", "env": { "API_KEY": "secret_key_123", "DEBUG": "true" } }'
Execute Shell Command curl -X POST https://api.buntime.sh/execute \ -H "Authorization: Bearer $BUNTIME_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "sessionId": "ses_abc123", "command": "bun install && bun test" }'
Long-Running with Timeout const result = await client . execute ({ sessionId: 'ses_abc123' , code: ` // Process large dataset const data = Array.from({ length: 1000000 }, (_, i) => i); const sum = data.reduce((a, b) => a + b, 0); console.log("Sum:", sum); ` , timeout: 120 // 2 minutes });
Error Responses 404 Session Not Found
400 Bad Request
408 Timeout
413 File Too Large
507 Disk Full
{ "error" : { "code" : "session_not_found" , "message" : "Session not found or expired" , "details" : { "sessionId" : "ses_invalid" } } }
Execution Modes Inline Code Pass code directly in the request body. Best for short scripts or single-file executions.
await client . execute ({ sessionId: 'ses_abc123' , code: 'console.log("Hello!");' });
Command Execution Run shell commands like bun run, bun test, or bun install.
await client . execute ({ sessionId: 'ses_abc123' , command: 'bun run index.ts' });
Multi-file Projects Write multiple files atomically before execution.
await client . execute ({ sessionId: 'ses_abc123' , files: [ { path: 'file1.ts' , content: '...' }, { path: 'file2.ts' , content: '...' } ], command: 'bun run file1.ts' });
Streaming Output For long-running executions, enable streaming to receive output as it’s generated:
const stream = await client . execute ({ sessionId: 'ses_abc123' , command: 'bun test' , stream: true }); for await ( const chunk of stream ) { if ( chunk . type === 'stdout' ) { console . log ( chunk . data ); } else if ( chunk . type === 'stderr' ) { console . error ( chunk . data ); } else if ( chunk . type === 'exit' ) { console . log ( 'Exit code:' , chunk . code ); } }
Package Installation Bun automatically installs packages on import:
await client . execute ({ sessionId: 'ses_abc123' , code: ` import { z } from "zod"; // Auto-installed const schema = z.string(); console.log(schema.parse("hello")); ` });
For explicit installation:
await client . execute ({ sessionId: 'ses_abc123' , command: 'bun add lodash react' });
Process Management Processes from previous executions stay alive:
// Start a server await client . execute ({ sessionId: 'ses_abc123' , code: 'Bun.serve({ port: 8080, fetch: () => new Response("OK") });' }); // Server keeps running in background // Access at: https://ses-abc123.buntime.sh
Kill background processes:
await client . execution . kill ({ sessionId: 'ses_abc123' , pid: 1234 // Optional: specific process });
Best Practices
Use shorter timeouts (10-30s) for quick scripts, longer (2-5min) for complex operations like installs or tests.
Write all files in a single execute call rather than making multiple file write requests.
Use environment variables for secrets
Pass secrets via env parameter instead of hardcoding in code. Env vars are encrypted in transit and at rest.
Check memoryUsed and cpuTime in responses to optimize your code and avoid hitting limits.
Check exitCode and parse stderr to detect and handle errors properly.
Limits Resource Free Tier Paid Tier Enterprise Execution timeout 30s 300s (5min) Custom Memory per execution 1GB 4GB Custom File size 10MB 50MB Custom Files per request 100 1000 Custom Env variables 100 500 Custom
Write Files Write files separately
Kill Process Stop running processes
List Files See all files in session
