DocsImpello docs

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. This page shows you how to install an SDK, start a sandbox, run a command in it, and find the page for every other task.

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).

Install

Install the SDK for your language.

npm install @impello/sdk

@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 Impello account, and Impello is invite only: ask for access at impello.ai. Then make an API key at dashboard.impello.ai/keys. It starts with imp_, and both SDKs read it from IMPELLO_API_KEY, so put it in your environment.

export IMPELLO_API_KEY=imp_...

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; see Limits and pricing.

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; it lists the connection-pool variables, which take an IMPELLO_ name from TypeScript SDK 0.3.2.

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. The example runs one command and kills the sandbox.

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()

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.

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. Pass a template name to Sandbox.create to boot a different one; see Templates.

Where to go next

Getting started

  • Quickstart: from a key to a running sandbox, in TypeScript, Python or plain HTTP.
  • API keys: where keys are made and how the SDKs find them.
  • MCP server: connect an MCP client and drive sandboxes from an agent.

Templates

  • Templates: the default templates you can boot.
  • Build a custom template: the template builder at @impello/sdk/template. TypeScript only.
  • Browser: a headful Chromium your agent drives over CDP, with a live view.

Sandbox

Reference

  • Errors: every error class the SDKs throw.
  • Limits and pricing: plans, concurrency, sandbox size and metering.
  • Migration guide: what changes when you move an existing integration.
  • Send feedback: report a bug, a missing feature or confusing docs with one POST, no key needed.

Next: Quickstart runs the same sandbox end to end, and lists what to check when a call fails.