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

Install

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 API key. Make one at 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; see Limits and pricing.

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

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.

Templates

• Templates: the default templates you can boot today.
• Build a custom template: the template builder at @impello/sdk/template. TypeScript only.

Sandbox

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

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.

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