> For the complete documentation index, see [llms.txt](https://docs.computesdk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.computesdk.com/getting-started/quick-start.md).

# Quick Start

Welcome to ComputeSDK! This guide will get you up and running with secure, isolated code execution across multiple cloud providers using a unified TypeScript interface.

## Installation

Install the provider package for the platform you want to use. This guide uses E2B as an example, but the sandbox API is the same across all providers.

```bash
npm install @computesdk/e2b
```

Then add your provider credentials to a `.env` file:

```bash
E2B_API_KEY=your_e2b_api_key
```

## Basic Usage

A **sandbox** is an isolated compute environment where you can safely execute code. Each sandbox runs on your chosen cloud provider (E2B, Modal, Vercel, etc.) with a unified interface. The `create()` method provisions a new sandbox, `runCommand()` executes shell commands and returns the result, and `destroy()` tears down the sandbox to free resources.

```typescript
import { e2b } from '@computesdk/e2b';

// Create a compute instance for your provider
const compute = e2b({ apiKey: process.env.E2B_API_KEY });

// Create a sandbox
const sandbox = await compute.sandbox.create();

// Run a command
const result = await sandbox.runCommand('echo "Hello World!"');
console.log(result.stdout); // "Hello World!"

// Clean up
await sandbox.destroy();
```

## Filesystem Operations

Each sandbox has its own isolated filesystem. You can read, write, and manage files using absolute paths (starting with `/`). Files persist for the sandbox lifetime and are destroyed when you call `destroy()`.

```typescript
// Write file
await sandbox.filesystem.writeFile('/tmp/hello.py', 'print("Hello")');

// Read file
const content = await sandbox.filesystem.readFile('/tmp/hello.py');

// Create directory
await sandbox.filesystem.mkdir('/tmp/mydir');

// List directory
const files = await sandbox.filesystem.readdir('/tmp');

// Check if exists
const exists = await sandbox.filesystem.exists('/tmp/hello.py');

// Remove file/directory
await sandbox.filesystem.remove('/tmp/hello.py');
```

## Shell Commands

Use `runCommand()` for shell operations, package installation, or system commands. It provides full shell access with detailed execution results including stdout, stderr, exit codes, and execution time.

```typescript
// Run shell command
const result = await sandbox.runCommand('ls -la');
console.log(result.stdout);

// With different working directory
const result2 = await sandbox.runCommand('pwd', { cwd: '/tmp' });
```

## Error Handling

ComputeSDK methods throw exceptions for API/network failures. For command execution errors, check the `exitCode` in the result rather than relying on exceptions. Exit code `0` indicates success, non-zero indicates failure.

```typescript
try {
  const sandbox = await compute.sandbox.create();
  const result = await sandbox.runCommand('some-command');
} catch (error) {
  console.error('Failed:', error.message);
}
```

## Essential Patterns

### Resource Cleanup (Critical for Production)

Always destroy sandboxes when done to avoid resource leaks and unnecessary costs. Sandboxes consume resources until explicitly destroyed or they timeout.

```typescript
// ✅ Recommended: Use try-finally
let sandbox;
try {
  sandbox = await compute.sandbox.create();
  await sandbox.runCommand('echo "Hello"');
} finally {
  await sandbox?.destroy();
}
```

### Error Handling with Exit Codes

Commands return exit codes following Unix conventions: `0` means success, non-zero indicates failure. Always check `exitCode` rather than catching exceptions for command failures.

```typescript
const result = await sandbox.runCommand('npm test');
if (result.exitCode !== 0) {
  console.error('Tests failed:', result.stderr);
} else {
  console.log('Tests passed!', result.stdout);
}
```

## Understanding Results

### Command Execution Results

When you call `runCommand()`, you receive:

* `stdout`: Standard output (normal program output)
* `stderr`: Standard error (error messages and warnings)
* `exitCode`: `0` for success, non-zero for failures
* `durationMs`: Execution time in milliseconds

```typescript
const result = await sandbox.runCommand('npm install');
console.log(result.stdout);      // Installation logs
console.log(result.stderr);      // Warnings or errors
console.log(result.exitCode);    // 0
console.log(result.durationMs);  // 2341
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.computesdk.com/getting-started/quick-start.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.