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

import { Buntime } from 'buntime.sh';

const client = new Buntime({
  apiKey: process.env.BUNTIME_API_KEY
});

const result = await client.execute({
  sessionId: 'ses_abc123',
  code: `
    const result = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0);
    console.log("Sum:", result);
  `
});

console.log(result.stdout); // "Sum: 15"
console.log(result.exitCode); // 0

{
  "stdout": "Sum: 15\n",
  "stderr": "",
  "exitCode": 0,
  "executionTime": 45,
  "memoryUsed": 12582912,
  "cpuTime": 42,
  "timedOut": false,
  "filesWritten": []
}

POST

execute

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

import { Buntime } from 'buntime.sh';

const client = new Buntime({
  apiKey: process.env.BUNTIME_API_KEY
});

const result = await client.execute({
  sessionId: 'ses_abc123',
  code: `
    const result = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0);
    console.log("Sum:", result);
  `
});

console.log(result.stdout); // "Sum: 15"
console.log(result.exitCode); // 0

{
  "stdout": "Sum: 15\n",
  "stderr": "",
  "exitCode": 0,
  "executionTime": 45,
  "memoryUsed": 12582912,
  "cpuTime": 42,
  "timedOut": false,
  "filesWritten": []
}

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

string

required

Bearer token with your API key

string

required

Must be application/json

Request Body

string

required

ID of the session to execute code in

string

JavaScript/TypeScript code to execute. Either code or command must be provided.

string

Shell command to run (e.g., bun run index.ts). Either code or command must be provided.

array

Array of files to write before execution

Show file object

string

required

File path relative to /workspace

string

required

File content (max 10MB per file)

object

Environment variables to set for this execution (max 100 variables)

integer

Execution timeout in seconds. Default: 30, Max: 300 (5 minutes)

string

Working directory for execution. Default: /workspace

boolean

Stream output as Server-Sent Events. Default: false

Response

string

required

Standard output from the execution

string

required

Standard error output

integer

required

Process exit code (0 = success)

integer

required

Execution time in milliseconds

integer

required

Peak memory usage in bytes

integer

required

CPU time used in milliseconds

boolean

required

Whether the execution was terminated due to timeout

array

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

import { Buntime } from 'buntime.sh';

const client = new Buntime({
  apiKey: process.env.BUNTIME_API_KEY
});

const result = await client.execute({
  sessionId: 'ses_abc123',
  code: `
    const result = [1, 2, 3, 4, 5].reduce((a, b) => a + b, 0);
    console.log("Sum:", result);
  `
});

console.log(result.stdout); // "Sum: 15"
console.log(result.exitCode); // 0

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

const result = await client.execute({
  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"
    }
  }'

const result = await client.execute({
  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"
  }'

const result = await client.execute({
  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

{
  "error": {
    "code": "session_not_found",
    "message": "Session not found or expired",
    "details": {
      "sessionId": "ses_invalid"
    }
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "Either 'code' or 'command' must be provided"
  }
}

{
  "error": {
    "code": "execution_timeout",
    "message": "Execution exceeded timeout of 30 seconds",
    "stdout": "Partial output...",
    "stderr": ""
  }
}

{
  "error": {
    "code": "file_too_large",
    "message": "File exceeds maximum size of 10MB",
    "details": {
      "path": "data.json",
      "size": 15728640
    }
  }
}

{
  "error": {
    "code": "disk_full",
    "message": "Session disk limit exceeded",
    "details": {
      "used": 1073741824,
      "limit": 1073741824
    }
  }
}

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

Set appropriate timeouts

Use shorter timeouts (10-30s) for quick scripts, longer (2-5min) for complex operations like installs or tests.

Batch file writes

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.

Monitor resource usage

Check memoryUsed and cpuTime in responses to optimize your code and avoid hitting limits.

Handle errors gracefully

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

Overview

Sessions

Execution

Files

Preview

Overview

Request

Request Body

Response

Examples

Execute Inline Code

Execute with Multiple Files

Execute with Environment Variables

Execute Shell Command

Long-Running with Timeout

Error Responses

Execution Modes

Inline Code

Command Execution

Multi-file Projects

Streaming Output

Package Installation

Process Management

Best Practices

Limits

Write Files

Kill Process

List Files

​Overview

​Request

​Request Body

​Response

​Examples

​Execute Inline Code

​Execute with Multiple Files

​Execute with Environment Variables

​Execute Shell Command

​Long-Running with Timeout

​Error Responses

​Execution Modes

​Inline Code

​Command Execution

​Multi-file Projects

​Streaming Output

​Package Installation

​Process Management

​Best Practices

​Limits

​Related Endpoints

Write Files

Kill Process

List Files

Overview

Request

Request Body

Response

Examples

Execute Inline Code

Execute with Multiple Files

Execute with Environment Variables

Execute Shell Command

Long-Running with Timeout

Error Responses

Execution Modes

Inline Code

Command Execution

Multi-file Projects

Streaming Output

Package Installation

Process Management

Best Practices

Limits

Related Endpoints