Quickstart

In this quickstart, you create a sandbox, run a command in it, and kill it, in TypeScript or Python. The curl tab covers create, read, and kill.

Before you start

You need an Impello account. Impello is invite only: you cannot sign up on your own. Ask for access at impello.ai, and once your account is added you sign in with a link sent to your email. A team invite also gets you in, joining that team.

You need an API key. Create one at dashboard.impello.ai/keys. Every key starts with imp_, and the dashboard is the only place you can read it. See API keys.

You also need a plan. Sandboxes are billed against your team's credit, and a team with no plan gets none. Once the credit is gone, creates are refused, but list and kill keep working. Pick a plan at dashboard.impello.ai/billing first. The plans are on Limits and pricing, and Refused creates shows what the refusal looks like.

Put the key in your environment. Both SDKs read IMPELLO_API_KEY.

export IMPELLO_API_KEY=imp_...

Every documented SDK setting uses the IMPELLO_ prefix. If your code already exports the older names from another sandbox provider, the SDKs still read those as a fallback — see Migrate.

Install

The TypeScript SDK needs Node 20.18.1 or later on the 20 line, or Node 22 or later. Node 21 is not supported. The Python SDK needs Python 3.10 or later. Install the SDK for your language.

npm install @impello/sdk

Your first sandbox

Create a sandbox from the default base template, run a command in it, read the sandbox's details, then kill it.

import { Sandbox } from '@impello/sdk'

const sandbox = await Sandbox.create('base')

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

const info = await sandbox.getInfo()
console.log(info.sandboxId, info.state, info.endAt)

await sandbox.kill()

Save the TypeScript as quickstart.mts and run it with npx tsx quickstart.mts; the .mts extension is what lets the top-level await run. Save the Python as quickstart.py and run it with python quickstart.py.

What each step does:

• Sandbox.create('base') starts a sandbox from the base template and returns a handle to it. The template name is optional and base is the default. The rest are on Templates.
• commands.run('echo hello') runs a shell command and waits for it to exit. The result carries stdout, stderr and exitCode (exit_code in Python). See Run commands.
• getInfo() (get_info() in Python) returns the sandbox ID, the template, the metadata, the state, the start time and the time the sandbox expires.
• kill() kills the sandbox and returns true. It returns false when the sandbox no longer exists.

Commands are not part of the HTTP API: the SDK opens a separate connection to the sandbox itself to run them. The curl tab stops at create, read and kill.

Python: with and async

A Python Sandbox is a context manager, and leaving the block calls kill().

from impello import Sandbox

with Sandbox.create("base") as sandbox:
    print(sandbox.commands.run("uname -a").stdout)

For asyncio, use AsyncSandbox. Every method is awaited, and async with kills the sandbox on the way out.

import asyncio
from impello import AsyncSandbox

async def main():
    async with await AsyncSandbox.create("base") as sandbox:
        result = await sandbox.commands.run("echo hello")
        print(result.stdout)

asyncio.run(main())

To pass a key per call or bind it to a Python client instead of the environment, see API keys.

If it fails

The SDKs raise these errors for the most common failures.

A missing key is raised before any request leaves your process. A refused create has no class of its own — read the message rather than branching on the type, and see Refused creates. The SDKs differ on keys in the older format another sandbox provider issued: Python refuses those locally, TypeScript sends them and the server rejects them. The full list is on Errors.

Next steps

• Sandbox lifecycle — connect to a sandbox you already have, and list the ones you are running.
• Filesystem — read and write files in the sandbox.
• Pause, resume and snapshots — keep a sandbox's state and come back to it later.
• Build a custom template — start from your own image.
• API keys — pass a key per call, and revoke or rotate one.