# Impello docs

An Impello sandbox is an isolated Linux machine that your agent starts with one
call, works in over the SDK, and kills or pauses when it is done.

These pages cover the two SDKs, `@impello/sdk` for TypeScript and `impello`
for Python. They also show the HTTP calls behind the sandbox lifecycle, file
transfer and templates, but they are not a complete HTTP reference. Every
sandbox exposes the same four modules: `files`, `commands`, `pty` and `git`
(deprecated in Python — see [Git](/docs/sandbox/git)).

## Install

<CodeTabs>
<Tab label="TypeScript">

```bash
npm install @impello/sdk
```

</Tab>
<Tab label="Python">

```bash
pip install impello
```

</Tab>
</CodeTabs>

`@impello/sdk` needs Node 20.18.1 or later on the 20 line, or Node 22 or later,
and ships as ESM and CommonJS. `impello` needs Python 3.10 or later and
includes both a sync `Sandbox` and an `AsyncSandbox` whose methods are
coroutines.

You also need an API key. Make one at
[dashboard.impello.ai/keys](https://dashboard.impello.ai/keys); it starts with
`imp_`, and both SDKs read it from `IMPELLO_API_KEY`.

A key alone is not enough. Sandboxes are billed against your team's credit, and
a team with no plan has none, so its first `create` is refused. Pick a plan at
[dashboard.impello.ai/billing](https://dashboard.impello.ai/billing); see
[Limits and pricing](/docs/limits-and-pricing).

```bash
export IMPELLO_API_KEY=imp_...
```

Every connection setting — the key, the domain, the API URL, debug and key
validation — reads its `IMPELLO_` name first, then the older name. If you are
moving code that used another prefix, see the
[migration guide](/docs/migrate-from-e2b); it lists the few connection-pool
variables that still read only the older name.

## Start a sandbox

`Sandbox.create()` with no arguments boots the default `base` template.
Commands run through `/bin/bash -l -c` and return the exit code and both
output streams. A non-zero exit raises; see [Errors](/docs/errors).

<CodeTabs>
<Tab label="TypeScript">

```ts
import { Sandbox } from '@impello/sdk'

const sandbox = await Sandbox.create()

const result = await sandbox.commands.run('echo hello')
console.log(result.exitCode, result.stdout)

await sandbox.kill()
```

</Tab>
<Tab label="Python">

```python
from impello import Sandbox

sandbox = Sandbox.create()

result = sandbox.commands.run("echo hello")
print(result.exit_code, result.stdout)

sandbox.kill()
```

</Tab>
<Tab label="curl">

```bash
# Create. The response carries the new sandboxID.
SANDBOX_ID=$(curl -s -X POST https://api.sandbox.impello.ai/sandboxes \
  -H "X-API-Key: $IMPELLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"templateID": "base", "timeout": 300}' | jq -r .sandboxID)

# Kill it when you are done.
curl -X DELETE "https://api.sandbox.impello.ai/sandboxes/$SANDBOX_ID" \
  -H "X-API-Key: $IMPELLO_API_KEY"
```

</Tab>
</CodeTabs>

The HTTP API creates, inspects and kills sandboxes. Running commands and moving
files goes through an SDK.

Created through an SDK, a new sandbox lives for 5 minutes unless you say
otherwise: pass `timeoutMs` in TypeScript, or `timeout` in seconds in Python,
or extend it later with `setTimeout` (`set_timeout` in Python). Over HTTP,
always send `timeout` — the field defaults to 15 seconds, which is why the curl
example passes it. See [Timeouts](/docs/sandbox/timeouts).

### The default template

`base` is Debian 12 (`python:3.12-bookworm`) with Python 3.12, Node 22, git,
`gh`, `jq`, `ripgrep`, `curl` and `build-essential`. It runs as the user `user`
in `/home/user`.

Commands run as `user` too. Pass `user: 'root'` (`user="root"` in Python) on a
single command to run that one as root; see
[Run commands](/docs/sandbox/commands). Pass a template name to
`Sandbox.create` to boot a different one; see [Templates](/docs/templates).

<Callout kind="note">
Some names in the SDK types are not part of the supported surface: `mcp`,
`getMcpUrl()` and `getMcpToken()` (`get_mcp_url()` and `get_mcp_token()` in
Python), `lifecycle.autoResume` (`auto_resume`), `network.maskRequestHost`
(`mask_request_host`), `volumeMounts` (`volume_mounts`; there are no volumes — see
[Errors](/docs/errors)) and the Python-only `iam`. With `mcp` and no template,
`create` boots a template named `mcp-gateway` that is not one of the default
templates, so it fails; with a template it fails when the gateway command is
not found. See the [migration guide](/docs/migrate-from-e2b).
</Callout>

## Where to go next

#### Getting started

- [Quickstart](/docs/quickstart): from a key to a running sandbox, in
  TypeScript, Python or plain HTTP.
- [API keys](/docs/api-keys): where keys are made and how the SDKs find them.

#### Templates

- [Templates](/docs/templates): the default templates you can boot today.
- [Build a custom template](/docs/templates/build): the template builder at
  `@impello/sdk/template`. TypeScript only.

#### Sandbox

- [Sandbox lifecycle](/docs/sandbox): create, connect, list, inspect and kill.
- [Run commands](/docs/sandbox/commands): foreground and background commands,
  streaming output, working directory and user.
- [Interactive terminal](/docs/sandbox/pty): a pseudo-terminal for shells and
  TUIs.
- [Filesystem](/docs/sandbox/filesystem): read, write, list and watch files.
- [Git](/docs/sandbox/git): clone, commit, push and pull inside the sandbox.
- [Network and public URLs](/docs/sandbox/network): reach a port from the
  internet and control egress.
- [Pause, resume and snapshots](/docs/sandbox/pause-and-snapshots): pause a
  sandbox and resume it later, with or without its memory.
- [Metrics](/docs/sandbox/metrics): CPU, memory and disk readings.
- [Timeouts](/docs/sandbox/timeouts): how long a sandbox lives and what happens
  when the clock runs out.

#### Reference

- [Errors](/docs/errors): every error class the SDKs throw.
- [Limits and pricing](/docs/limits-and-pricing): plans, concurrency, sandbox
  size and metering.
- [Migration guide](/docs/migrate-from-e2b): what changes when you move an
  existing integration.

Next: [Quickstart](/docs/quickstart) runs the same sandbox end to end, and
lists what to check when a call fails.