Metadata-Version: 2.5
Name: impello
Version: 0.2.0
Summary: Python SDK for Impello sandboxes.
Project-URL: Homepage, https://impello.ai
Project-URL: Repository, https://github.com/21-Dreams/impello
License-Expression: MIT
Keywords: agents,code-interpreter,impello,microvm,sandbox
Requires-Python: >=3.9
Requires-Dist: e2b<3,>=2.46.0
Description-Content-Type: text/markdown

# `impello`

The Python SDK for Impello sandboxes.

## Install

```bash
pip install impello
```

## Use

```python
from impello import Sandbox

sandbox = Sandbox.create()
result = sandbox.commands.run("echo hello")

print(result.stdout)

sandbox.pause()
```

Set your key in the environment, or pass it to each call:

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

```python
Sandbox.list(api_key="imp_...")
```

For a process that talks to more than one account or more than one fleet, bind
the settings to a client instead:

```python
from impello import Impello

client = Impello(api_key="imp_...")
sandbox = client.Sandbox.create()
```

## Settings

Every setting reads an `IMPELLO_` name first, then the matching `E2B_` name.

| Variable | Default | What it does |
|---|---|---|
| `IMPELLO_API_KEY` | none | The key. Starts with `imp_` |
| `IMPELLO_DOMAIN` | `sandbox.impello.ai` | The domain the API and the sandboxes sit on |
| `IMPELLO_API_URL` | `https://api.<domain>` | The API address. Set this to reach a self-hosted API |
| `IMPELLO_SANDBOX_URL` | derived from the domain | The address a sandbox is reached at |
| `IMPELLO_DEBUG` | `false` | Talk to `http://localhost:3000` |

The `E2B_` fallback is the migration, not politeness. Callers already export
`E2B_API_KEY`, `E2B_API_URL` and `E2B_DOMAIN`. Rename when it suits you.
Nothing breaks if you never do.

Only the domain has a default. Without one the SDK falls back to E2B's own
`e2b.app`, and the failure is a connection to somebody else's fleet.

Params passed to a single call beat a client's params, which beat the
environment. That is E2B's own rule and this package keeps it.

## Why this one is a wrapper, when the TypeScript one is a copy

The TypeScript client cannot talk to Impello at all. Its `validateApiKey` runs
inside the `ApiClient` constructor, is not exported, has no off switch, and
accepts only `e2b_`. So `@impello/sdk` had to be a copy.

Python has no `e2b_` pattern anywhere. It takes an `imp_` key today. So the
only thing missing is where to send the request, and that is all this package
supplies.

It supplies it through `ClientFactory._resolve_api_params`, which is E2B's own
seam for binding defaults. That means one method is overridden rather than the
twelve descriptors on `Sandbox`, and **`e2b` itself is untouched**: importing
`impello` does not retarget a plain `e2b` call in the same process, and it
never writes to `os.environ`. A test holds that.

## This package will be replaced

A permanent wrapper is the worst outcome. `pip show impello` prints `e2b`, and
the client sends a `publisher: e2b` header to our own servers. So the wrapper
ships now and the full clone lands before we take payments, with
`e2b/api/client/` regenerated from our own spec.

See `docs/decisions/sdk-self-contained.md`.

## Develop

```bash
python -m venv .venv
./.venv/bin/pip install -e . pytest
./.venv/bin/python -m pytest
```
