---
title: "exe.dev Python SDK"
description: "pip install exedev: the official exe.dev Python SDK. Create VMs, run commands, move files, share apps, and manage keys and integrations, sync or asyncio."
url: https://exe.dev/deploy/python-sdk
category: "AI agents"
published: 2026-11-21
updated: 2026-11-21
---

# exe.dev Python SDK

Everything ssh exe.dev does, from Python code, sync or asyncio.

- **Software:** exe.dev Python SDK (https://pypi.org/project/exedev/)
- **Source:** https://github.com/boldsoftware/exe-sdk-python
- **License:** MIT
- **Machine-readable:** https://exe.dev/deploy/python-sdk/manifest.json

`exedev` is exe.dev's official Python SDK. It wraps exe.dev's
[HTTPS API](/docs/https-api), so everything you can do with `ssh exe.dev`
you can do from Python: create VMs, run commands in them, move files,
share what they serve, make API and VM tokens, attach integrations, and
manage teams, pools, and billing. It works from plain scripts and from
`asyncio`.

```python
import exedev

exe = exedev.Client()  # reads EXE_TOKEN

with exe.new() as vm:  # a new VM, deleted when the block ends
    print(vm.run("uname -sr", check=True).stdout, end="")
    print(vm.https_url)
```

```console
$ python first.py
Linux 6.12.115
https://platypus-and-baguette.exe.xyz
```

That round trip, a new VM, a command, and the VM deleted again, took
about three seconds in our tests. This page tours what you can automate,
with examples we ran against exe.dev with exedev 0.6.0, then puts them
together: a nightly copy of a VM, a preview VM for each pull request, a
cleanup job, and tools for an LLM agent.

## Install and get a token

The SDK is [`exedev` on PyPI](https://pypi.org/project/exedev/). It needs
Python 3.11 or later and depends only on
[HTTPX](https://www.python-httpx.org):

```bash
pip install exedev        # or: uv add exedev
```

Until 1.0, a minor release can change the API, so pin it in anything that
lasts: `uv add "exedev>=0.6,<0.7"`. `exedev.__version__` says which one
you have.

The SDK authenticates with an exe.dev API token. Make one on your computer,
with the commands your code needs and nothing else:

```bash
ssh exe.dev ssh-key generate-api-key --label=my-app --tag=my-app --exp=30d \
  '--cmds="new,ls,ssh,rm,cp,restart,resize,tag,comment,share show,share set-public,share set-private,share add-link"'
```

It prints a token that starts with `exe1.`. Give it to the SDK in
`EXE_TOKEN`, or pass `exedev.Client(token=...)`:

```bash
export EXE_TOKEN=exe1.…
```

- `--cmds` decides which methods work. Keep `ssh`: `run()` uses it, and
  so does `new()`, to wait until a VM accepts commands. Keep `rm`, which
  the `with` block needs to delete the VM. Without `--cmds`, a token gets a
  [default set](/docs/https-api#granular-permissions) that has neither.
  Keep the single quotes, so that names with spaces reach exe.dev intact.
- `--tag=my-app` limits the token to VMs tagged `my-app`. VMs it creates
  get the tag, so it can manage its own VMs and can't see or touch any
  other. Leave it out only for account-wide work (integrations, teams,
  billing), with a token you keep somewhere safer.
- `--exp=30d` makes it expire. To revoke it sooner, remove its key:
  `ssh exe.dev ssh-key remove my-app`.

You can also make tokens without a request, by signing them with an SSH
key on your account: see [Make tokens in code](#make-tokens-in-code).

## Your first script

```python
# first.py
import exedev

exe = exedev.Client()  # reads EXE_TOKEN

with exe.new(comment="first script") as vm:
    vm.write_file("site/index.html", "<h1>Hello from Python</h1>\n")
    vm.spawn("python3 -m http.server 8000", name="web", cwd="site")
    print(vm.run("curl -s --retry 9 --retry-connrefused localhost:8000").stdout)
    print("serving at", vm.https_url)
    input("Open it, then press Enter to delete the VM ")
```

`new()` returns once the VM accepts commands, so the first `run()` needs no
retry loop. If the VM doesn't become ready, or you press Ctrl-C while it's
being made, `new()` deletes it before it raises. The `with` block deletes
it at the end, even if the block raises; without `with`, call
`vm.delete()`.

The VM's address is private: only you, signed in to exe.dev, can open it
until you [share it](#share-a-vm-and-reach-it-from-code). Let `new()` pick
the name, since VM names are global across exe.dev, or pass `name=`.

The same script for `asyncio`: `exedev.AsyncClient` has the same methods
as `exedev.Client`, as coroutines, and `async with` deletes the VM.

```python
# first_async.py
import asyncio

import exedev


async def main() -> None:
    async with exedev.AsyncClient() as exe:  # reads EXE_TOKEN
        async with exe.new(comment="first script") as vm:
            result = await vm.run("uname -sr", check=True)
            print(result.stdout, end="")
            print(vm.https_url)


asyncio.run(main())
```

Note `async with exe.new()` without `await`; outside `async with`, it's
`vm = await exe.new()`. Every example below works the same way with
`await` in front of each call.

## Create and manage VMs

`new()` takes the flags of [`ssh exe.dev new`](/api?cmd=help+new) as
keyword arguments:

```python
vm = exe.new(
    cpu=2, memory="4GB", disk="25GB",
    env={"APP_ENV": "staging"},      # set for every command
    comment="staging for #1234",     # a note shown in ls
    tags=["staging"],
    setup_script="#!/bin/bash\nset -e\nsudo apt-get install -y -q jq\n",
    wait_until="setup",              # also wait for the setup script to succeed
)
print(vm.name, vm.status, vm.tags, vm.created_at)
```

- `image=` starts from another container image instead of the default
  Ubuntu 24.04 one, with `registry_auth=` for a
  [private registry](/docs/private-image). `integrations=` attaches
  [integrations](/docs/integrations) by name, `egress="integrations"`
  cuts the VM off from the internet, `prompt=` gives the VM's agent,
  [Shelley](/docs/shelley/intro), a task, and `standalone=True` makes a
  [standalone VM](/docs/standalone-vms) with capacity of its own.
- With `wait_until="setup"`, a failing setup script raises
  `exedev.VMSetupError` with its `exit_code` and `output`, and the VM is
  deleted. `keep_on_failure=True` keeps it, as `err.vm`, to debug.
- A token made with `--tag` tags every VM it creates, and can't add or
  remove tags; `tags=` needs a token without `--tag`.

Find VMs again, and change them:

```python
for vm in exe.vms():                 # or exe.vms("preview-*")
    print(vm.name, vm.status, vm.tags, vm.comment)

vm = exe.vm("my-app")                # exedev.NotFoundError if there is none
vm.tag("nightly"); vm.untag("nightly")  # not with a --tag token
vm.set_comment("kept for debugging")
vm.rename("my-app-old")              # vm.name and vm.https_url follow
vm.resize(cpu=4, memory="8GB", disk="50GB", restart=True)  # applies after a restart

copy = vm.copy()                     # a new VM with a copy of the disk, tags, and comment
vm.restart()                         # waits until it accepts commands again
vm.pause(); vm.resume()              # pausing frees CPU and memory; processes survive

vm.delete()                          # NotFoundError if it's already gone
exe.delete("old-1", "old-2", copy)   # several at once
```

A VM's attributes (`status`, `tags`, `comment`, `https_url`,
`created_at`, `egress`) are a snapshot from when the SDK last saw it;
`vm.refresh()` fetches them again. `copy()`, `pause()`, and `restart()`
first flush the VM's recent writes to disk, so the copy or the restarted
VM has them. Disks only grow, and new CPU, memory, and disk sizes apply
after a restart (`restart=True` does it; the result's `restart_required`
says whether one is needed). In our tests a copy took about 2 seconds, `restart()` 2.5,
`pause()` 2, and `resume()` 1. `exe.delete()` doesn't raise for VMs it
couldn't delete: it lists them in the result's `failed` and `not_found`.

## Run commands and stream output

`vm.run()` runs a command in a bash login shell on the VM, as the `exedev`
user with passwordless `sudo`, in the home directory, and waits for it:

```python
r = vm.run("echo $APP_ENV; echo oops >&2; exit 3")
r.stdout, r.stderr, r.exit_code, r.ok   # ('staging\n', 'oops\n', 3, False)

vm.run(["python3", "-c", code, "it's me"])  # a list is quoted for you
vm.run("make test", cwd="app", env={"CI": "1"}, check=True)  # raises CommandError if it fails
```

A string is a shell command line, with pipes and `&&`; a list is an
argument list that arrives intact, whatever quotes or newlines it holds.
As with `subprocess.run()`, a failing command is a result, not an
exception, unless you pass `check=True`.

To see output as it arrives, pass callbacks. `on_stdout` and `on_stderr`
get one line at a time; `on_stdout_bytes` and `on_stderr_bytes` (new in
0.6.0) get raw bytes, for output that isn't text:

```python
vm.run("cd app && make test", on_stdout=print, on_stderr=print)

with open("backup.tar.gz", "wb") as f:
    vm.run("tar czf - app", on_stdout_bytes=f.write, capture=False)
```

`run()` collects up to 8 MiB of output and raises `OutputLimitError` past
that; `capture=False` only streams.

> [!WARNING]
> In exedev 0.6.0, `run(timeout=...)` raises `CommandTimeoutError` when
> time runs out, but the command keeps running on the VM (a known issue in
> the [changelog](https://github.com/boldsoftware/exe-sdk-python/blob/main/CHANGELOG.md)).
> So does cancelling an `asyncio` task that waits on `run()`. To bound a
> command, bound it on the VM as well: `vm.run("timeout 60 make test")`
> exits with status 124 when time runs out.

`run()` lasts as long as its request. For servers and long jobs, use
`spawn()`, which starts a process that runs on its own, whatever happens
to your program:

```python
web = vm.spawn("python3 -m http.server 8000", name="web", cwd="site")
job = vm.spawn("./build.sh", name="build")

job.poll()                       # None while it runs, then its exit status
print(job.logs(tail=20).stdout)  # what it has printed so far
result = job.wait(timeout=3600, check=True)  # survives dropped connections

exe.vm(vm.name).process("web").terminate()  # from any program, later
```

Processes survive `pause()` and `resume()` but not `restart()`: after
one, `poll()` and `wait()` raise `ProcessLostError`. For a service that
should come back after a reboot, write a systemd unit
with `write_file()` instead.

## Move files

```python
vm.write_file("app/config.json", json.dumps(config))  # str or bytes; makes directories
vm.write_file("bin/run.sh", script, mode=0o755)
data = vm.read_file("app/out.csv")                    # bytes; FileNotFoundError if missing
vm.upload("./src", "app", exclude=[".git", ".venv", "__pycache__"])
vm.download("app/dist", "./dist")                     # a file or a directory
```

Paths on the VM are relative to the home directory unless absolute. Files
travel through the API in compressed pieces sent in parallel: expect a few
seconds per megabyte of random data, much less for text. For big files,
have the VM fetch them (`git clone`, `curl`), or use `scp`.

## Share a VM and reach it from code

exe.dev's [HTTPS proxy](/docs/proxy) serves port 8000 of every VM at
`vm.https_url`, and ports 3000 to 9999 at `vm.url(3000)`. They're private
until you share them:

```python
vm.share.set_public()                       # anyone with the URL; set_private() undoes it
vm.share.add("ana@example.com", message="Have a look")  # one person, by email
link = vm.share.add_link()["url"]           # https://<vm>.exe.xyz/?share=…, for whoever opens it
vm.share.port(3000)                         # serve port 3000 at https_url instead of 8000
print(vm.share.show())                      # who has access
```

`share.add()` emails the person an invitation. People you share with sign
in to exe.dev, and your app gets their address
in the `X-ExeDev-Email` header, so it needs no login of its own. See
[sharing](/docs/sharing).

Your own code can't sign in with a browser. To call an API served by a
private VM, make a [VM token](/docs/https-tokens-for-vms) for it and send
it in the `X-Exedev-Authorization` header:

```python
import httpx

vm_token = exe.ssh_key.generate_api_key(vm=vm.name, label="api-client", exp="7d")["token"]

r = httpx.get(vm.url(8000, "/health"),
              headers={"X-Exedev-Authorization": f"Bearer {vm_token}"})
print(r.status_code)  # 200, where a request without the token gets 401
```

A VM token opens that one VM's HTTPS endpoints and nothing else: it can't
run exe.dev commands. The proxy strips the header before the request
reaches the VM. Tools that only do Basic auth, like `git`, can send it as
the password with any username.

## SSH keys and API tokens

The `ssh-key` commands are `exe.ssh_key`. Use them to give a machine or a
person access to only what it needs:

```python
exe.ssh_key.list()

# A key that reaches two VMs and nothing else, over SSH and for signing VM tokens
exe.ssh_key.add(public_key, vm=["web", "db"])

# A key that works only from one network
exe.ssh_key.add(public_key, tag="ci", ips=["203.0.113.0/24"])

exe.ssh_key.remove("SHA256:…")       # by name, fingerprint, or public key
```

`vm=` (a list, new in 0.6.0) scopes a key to those VMs, and `ips=` to
client addresses, as CIDR ranges. A VM-scoped key can `ssh` into its VMs,
with `ssh_user=` to pick the Unix user, and sign VM tokens for them, but
can't run exe.dev commands. An empty `vm=[]` raises `ValueError` rather
than make a key that reaches every VM. See
[VM-scoped SSH keys](/docs/vm-scoped-ssh-keys).

API tokens are keys too. `generate_api_key()` takes the flags of
`ssh-key generate-api-key`, with the commands as a list:

```python
ci_token = exe.ssh_key.generate_api_key(
    label="ci", tag="ci", exp="30d",
    cmds=["new", "ls", "ssh", "rm", "share add-link"],
)["token"]
```

That's how a service gives each customer a token of its own: with
`tag=f"customer-{cid}"`, one customer's VMs are invisible to the next
one's token. The token that makes tokens needs `ssh-key generate-api-key`
in its own `--cmds`, so keep it apart from the tokens it makes. A token
can't hand out more than it has: one made with `--tag` can make tokens and
add keys only for its own tag.

### Make tokens in code

`exedev.sign_token()` (new in 0.6.0) makes a token on your machine, with no
request, by signing its permissions with an SSH key on your account, as
[local key creation](/docs/https-api-local-key) describes. It runs
`ssh-keygen -Y sign`, so `ssh-agent` and passphrases work:

```python
from datetime import datetime, timedelta, timezone

import exedev

in_an_hour = datetime.now(timezone.utc) + timedelta(hours=1)

# An API token
api_token = exedev.sign_token("~/.ssh/exe_dev_api", {"cmds": ["ls"], "exp": in_an_hour})

# A token for one VM's HTTPS endpoints
vm_token = exedev.sign_token("~/.ssh/exe_dev_api", {"exp": in_an_hour}, vm="my-app")
```

The token can do no more than its key: signed with a key added with
`tag="ci"`, it sees only VMs tagged `ci`. Removing the key revokes every
token it signed. Give tokens a short `exp`: there's no other replay
protection.

## Integrations

[Integrations](/docs/integrations) let code on a VM use a credential
without ever seeing it: exe.dev keeps the secret and adds it to requests
the VM makes to `https://<name>.int.exe.xyz`. Managing them takes a token
made without `--tag`: exe.dev refuses `integrations list` to tag-scoped
ones.

```python
for i in exe.integrations.list():
    print(i["name"], i["type"], i["attachments"])

exe.integrations.add(
    "http-proxy", name="stripe",
    target="https://api.stripe.com", bearer=os.environ["STRIPE_KEY"],
)
exe.integrations.attach("stripe", "tag:billing")               # every VM tagged billing
exe.integrations.attach("stripe", f"vm:{vm.name}", for_="2h")  # one VM, for two hours
print(exe.integrations.show("stripe"))  # the header shows as "Authorization:Bearer ***"
exe.integrations.detach("stripe", "tag:billing")
exe.integrations.remove("stripe")
```

Code on an attached VM then calls `https://stripe.int.exe.xyz/v1/...` with
no key, and the request reaches the target with the header added.
`exe.new(integrations=["stripe"])` attaches one as the VM is created. A
`for_=` attachment lapses on its own. Detaching isn't instant: in our
tests, VMs could still use the integration for 40 to 60 seconds. The
[HTTP proxy integration](/docs/integrations-http-proxy) works for any API
that takes a header; `integrations.list(available=True)` lists the other
kinds, such as GitHub repositories, S3, and the keyless
[LLM gateway](/docs/integrations-llm).

## Teams, pools, and billing

```python
u = exe.billing.usage()          # this billing cycle, against your plan
print(u["vm_count"], u["disk_used_bytes"], u["included_disk_bytes"], u["tx_bytes"])

by_vm = exe.billing.usage(group="vm", range="7d")  # disk and bandwidth per VM
for v in sorted(by_vm["vms"], key=lambda v: -v["disk_bytes"])[:5]:
    print(v["name"], v["disk_bytes"] // 2**30, "GiB")
```

`history=True` (new in 0.6.0, with `group="vm"`) adds compute, disk, and
network history over the range. Disk and bandwidth beyond your plan's
allowance are billed as [usage](/docs/billing/usage).

On a [team](/docs/teams/overview), the `team` and `pool` commands are
methods in the same way: `exe.team.members()`, `exe.team.settings()`,
`exe.team.settings.public_sharing(False)` and `vm_sharing("off")` (both
new in 0.6.0; see [sharing controls](/docs/teams/sharing-controls)),
`exe.pool.list()`, and `exe.new(pool="ci")` to place a VM in one of the
team's [pools](/docs/pools). On a Personal account they raise `APIError`
("command not available").

## Any other command

Every `ssh exe.dev` command is a method, grouped as on the command line,
and each method's docstring is the command's help. For a command that has
no method yet, `exe.exec()` runs a command line exactly as you'd type it
after `ssh exe.dev`, and returns its JSON:

```python
import shlex

info = exe.exec(f"stat {shlex.quote(vm.name)}")
```

Quote values with `shlex.quote()`. To run commands on a VM, use
`vm.run()`: `exec()` refuses `ssh`. The [API explorer](/api) lists
every command and its flags.

## Recipes

### Copy a VM every night

A copy is a whole VM with a copy of the disk, made in seconds. Copy a VM
you care about every night, pause the copy so it uses no CPU or memory,
and keep the last seven:

```python
# nightly.py: copy a VM every night, keep the last 7 copies, paused
from datetime import datetime, timezone

import exedev

SOURCE = "my-app"
KEEP = 7

exe = exedev.Client()
source = exe.vm(SOURCE)

stamp = datetime.now(timezone.utc).strftime("%Y%m%d-%H%M")
copy = source.copy(f"{SOURCE}-{stamp}")  # flushes the source's writes first
copy.pause()                             # keeps the disk, frees CPU and memory
print("copied", SOURCE, "to", copy.name)

copies = sorted(
    (vm for vm in exe.vms(f"{SOURCE}-*") if vm.name[len(SOURCE) + 1:][:8].isdigit()),
    key=lambda vm: vm.name,
)
for vm in copies[:-KEEP]:
    vm.delete()
    print("deleted", vm.name)
```

Its token needs `ls`, `cp`, `ssh` (to flush and wait), `pause`, and `rm`.
Run it from cron on a machine of yours, or from a scheduled CI job. To get
yesterday's VM back, `exe.vm("my-app-20261120-0300").resume()`, or copy
the copy. Copies count toward your plan's VM limit and use disk, so keep
`KEEP` small. For backups that leave exe.dev, see
[VM backups](/docs/vm-backups).

### A preview VM for every pull request

This GitHub Actions workflow gives each pull request a VM that serves the
branch, posts its link once, updates the VM on every push, and deletes it
when the pull request closes. The token lives in a repository secret and
is tagged, so the workflow can touch only preview VMs.

Make the token on your computer, and add it as the repository secret
`EXE_PREVIEW_TOKEN` (Settings → Secrets and variables → Actions):

```bash
ssh exe.dev ssh-key generate-api-key --label=previews --tag=preview --exp=90d \
  '--cmds="new,ls,ssh,rm,share add-link"'
```

The script finds a pull request's VM by its comment:

```python
# .github/preview.py
# /// script
# requires-python = ">=3.11"
# dependencies = ["exedev>=0.6,<0.7"]
# ///
"""Create, update, or delete the preview VM of a pull request."""
import os

import exedev

repo = os.environ["GITHUB_REPOSITORY"]          # owner/name
pr = os.environ["PR_NUMBER"]
comment = f"preview {repo}#{pr}"                # how we find this PR's VM again

exe = exedev.Client()                           # reads EXE_TOKEN
existing = [vm for vm in exe.vms() if vm.comment == comment]

if os.environ["PR_ACTION"] == "closed":
    exe.delete(*existing)
    raise SystemExit(0)

if existing:
    vm = existing[0]
    try:
        vm.process("app").kill()                # stop the old version
    except ProcessLookupError:
        pass
else:
    vm = exe.new(comment=comment)

vm.upload(".", "app", exclude=[".git", "node_modules", ".venv"])
vm.spawn("python3 -m http.server 8000", name="app", cwd="app")  # your app's start command
vm.run("curl -sf --retry 20 --retry-connrefused localhost:8000 >/dev/null", check=True)

if not existing:
    link = vm.share.add_link()["url"]
    with open(os.environ["GITHUB_OUTPUT"], "a") as out:
        print(f"url={link}", file=out)
print(vm.https_url)
```

```yaml
# .github/workflows/preview.yml
name: preview
on:
  pull_request:
    types: [opened, reopened, synchronize, closed]
permissions:
  contents: read
  pull-requests: write
concurrency: preview-${{ github.event.pull_request.number }}
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v7
      - id: preview
        run: uv run .github/preview.py
        env:
          EXE_TOKEN: ${{ secrets.EXE_PREVIEW_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          PR_ACTION: ${{ github.event.action }}
      - if: steps.preview.outputs.url
        run: gh pr comment "$PR_NUMBER" --body "Preview: $URL"
        env:
          GH_TOKEN: ${{ github.token }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
          URL: ${{ steps.preview.outputs.url }}
```

Replace the `spawn()` line with your app's start command, and install
what it needs first with `vm.run(..., check=True)`, or give `new()` a
`setup_script`. The preview is private: the share link lets whoever opens
it sign in to exe.dev and see it, and nobody else. A process started with
`spawn()` doesn't survive a restart of the VM; for previews that must,
start the app from a systemd unit.

Pull requests from forks don't get repository secrets, so they get no
preview, which is what you want: a fork's code would otherwise run with
your token.

### Clean up stale VMs by tag

Jobs crash and leave VMs behind. Sweep them up now and then, by tag and
age:

```python
# reap.py: delete VMs tagged preview that are more than three days old
from datetime import datetime, timedelta, timezone

import exedev

cutoff = datetime.now(timezone.utc) - timedelta(days=3)

exe = exedev.Client()
stale = [
    vm for vm in exe.vms()
    if "preview" in vm.tags and vm.created_at and vm.created_at < cutoff
]
for vm in stale:
    print("deleting", vm.name, vm.created_at.date(), vm.comment)
result = exe.delete(*stale)
print(f"deleted {len(result['deleted'])}, failed {len(result['failed'])}")
```

With a token made with `--tag=preview`, `exe.vms()` returns only preview
VMs anyway, so the script can't delete anything else. Run it from cron or a
scheduled workflow.

### Give an LLM agent tools

A model can drive the SDK through tools: each tool is a few lines that
call it. This agent gets a VM, writes and runs code on it, and starts a
server, using the [Anthropic SDK](https://github.com/anthropics/anthropic-sdk-python):

```python
# agent.py: a model that builds something on its own VM
import shlex

import anthropic
import exedev

claude = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
exe = exedev.Client()


def tool(name, description, **params):
    return {"name": name, "description": description, "input_schema": {
        "type": "object", "required": list(params),
        "properties": {p: {"type": "string", "description": d} for p, d in params.items()}}}


TOOLS = [
    tool("run", "Run a bash command on your Linux VM (Ubuntu, sudo, Python, uv, Docker).",
         command="the command line"),
    tool("write_file", "Write a file on your VM.", path="path relative to home", content="the file"),
    tool("start_server", "Start a long-running command in the background, such as a web server on port 8000.",
         command="the command line"),
]


def call(vm: exedev.VM, name: str, args: dict) -> str:
    if name == "run":
        r = vm.run(f"timeout 120 bash -c {shlex.quote(args['command'])}")
        return f"exit {r.exit_code}\n{(r.stdout + r.stderr)[-10_000:]}"
    if name == "write_file":
        vm.write_file(args["path"], args["content"])
        return "ok"
    if name == "start_server":
        p = vm.spawn(args["command"])
        return f"started {p.name}; it will be served at {vm.https_url}"
    return f"unknown tool {name}"


def build(task: str) -> None:
    vm = exe.new(comment="agent")
    messages = [{"role": "user", "content": task}]
    while True:
        reply = claude.messages.create(model="claude-sonnet-5-5", max_tokens=4096,
                                       tools=TOOLS, messages=messages)
        messages.append({"role": "assistant", "content": reply.content})
        if reply.stop_reason != "tool_use":
            break
        messages.append({"role": "user", "content": [
            {"type": "tool_result", "tool_use_id": b.id, "content": call(vm, b.name, b.input)}
            for b in reply.content if b.type == "tool_use"]})
    print(reply.content[-1].text)
    print("Open it at", vm.https_url, "and delete it with: ssh exe.dev rm", vm.name)


build("Make a one-page website on port 8000 that shows today's date in Tokyo.")
```

In our run, the model wrote a small Python server, started it, checked it
with `curl`, and answered with the VM's address. The commands it runs are
bounded on the VM with `timeout 120`, for the reason in
[the warning above](#run-commands-and-stream-output). Run on an exe.dev
VM, `anthropic.Anthropic(base_url="https://llm.int.exe.xyz",
api_key="unused")` uses the [LLM gateway](/docs/integrations-llm) with no
API key.

The model's code is code you don't trust: give the agent a token made with
`--tag`, and read [Run untrusted code](/deploy/python-sandboxes#run-untrusted-code).
For a model that should drive exe.dev itself, without tool code of your
own, use [exe.dev MCP](/deploy/exe-mcp); for many short-lived code
sandboxes, see [Create sandboxes from Python](/deploy/python-sandboxes).

## Errors, retries, and rate limits

Every exception the SDK raises is an `exedev.ExeError`:

```text
ExeError
├── APIError                   exe.dev refused the command: .status, .operation, .body
│   ├── AuthenticationError    401: the token is malformed, expired, or revoked
│   ├── PermissionDeniedError  403: the token may not run that command (--cmds)
│   ├── NotFoundError          404: no such VM, or not one the token can see
│   ├── RateLimitError         429: still too many requests after max_retries
│   └── VMNotRunningError      run() or spawn() on a paused or stopped VM
├── NetworkError               the request failed; whether it took effect is unknown
├── ProtocolError              a response the SDK didn't understand
├── CommandError               run(check=True) and the command failed: .result
├── CommandInterruptedError    the exit status is unknown
│   ├── OutputLimitError       more output than max_output
│   └── CommandTimeoutError    run(timeout=...) ran out; also a TimeoutError
├── ProcessLostError           a spawned process ended without an exit status
└── VMReadyError               a VM didn't become ready: .vm
    └── VMSetupError           its setup script failed: .exit_code, .output
```

- Requests refused for the rate limit (429) are retried with backoff, up
  to `max_retries` times (5), before `RateLimitError`. The limit is per
  SSH key, so give independent workloads tokens of their own. Set it with
  `exedev.Client(max_retries=...)`.
- Nothing else is retried for you, because not everything is safe to run
  twice. After a `NetworkError` from `new()`, the VM may or may not exist:
  look for it by its `comment`. After a `CommandInterruptedError`, the
  command may still be running.
- `NotFoundError` from a tagged token means the VM doesn't exist *or*
  doesn't have the tag.
- Other `APIError`s have `status` 422: the command ran and failed, for
  example a bad argument. The message says why.

Messages never include the token or the command line.

## Keep the token safe

Anyone who has a token can do what it allows, on your account, until it
expires or you remove its key.

- Give each program its own token, with the fewest `--cmds`, a `--tag`
  when it manages VMs, and an `--exp`. A token made with `--tag` can't see
  or touch any VM without that tag, and can't change tags.
- Keep it in your CI's secrets, a secret manager, or an environment
  variable on a machine only you use. Never commit it, and never put it on
  a VM you share with other people or that runs code you don't trust:
  anyone with a shell there can read it.
- `ips=[...]` limits a token to your network, for tokens used from
  outside exe.dev. Don't rely on it for tokens used from VMs: VMs share
  their outgoing addresses with other users' VMs.
- Revoke a token by removing its key: `exe.ssh_key.remove("my-app")` or
  `ssh exe.dev ssh-key remove my-app`. `exe.ssh_key.list()` shows each
  key's last use.

## Where to go next

- [Create sandboxes from Python](/deploy/python-sandboxes): throwaway VMs
  for code you run, in depth.
- [TypeScript sandboxes](/deploy/typescript-sandboxes): the TypeScript
  SDK, `@exedev/sdk`.
- [exe.dev MCP](/deploy/exe-mcp): the same commands for an agent, with no
  code.
- The [HTTPS API](/docs/https-api) the SDK calls, and the
  [API explorer](/api), where you can try every command. Each one also
  works over SSH: `ssh exe.dev help`.
- The [source and changelog](https://github.com/boldsoftware/exe-sdk-python).

## Frequently asked questions

### How do I install the exe.dev Python SDK?

`pip install exedev`, or `uv add exedev`. It needs Python 3.11 or later and depends only on [HTTPX](https://www.python-httpx.org). This page was tested with exedev 0.6.0; until 1.0 a minor release can change the API, so pin `exedev>=0.6,<0.7` in anything that lasts.

### Sync or asyncio?

Both, with the same methods. `exedev.Client` and `exedev.VM` block; `exedev.AsyncClient` and `exedev.AsyncVM` are the same API as coroutines, for FastAPI handlers, async agents, and anything that runs many VMs at once.

### What can it do that the sandbox page doesn't cover?

[Create sandboxes from Python](/deploy/python-sandboxes) goes deep on one use: throwaway VMs for code you run. This page is the whole SDK: every `ssh exe.dev` command is a method, so the same client manages sharing, SSH keys and API tokens, integrations, teams, pools, and billing, and `exe.exec()` runs any command that has no method yet.

### Is it the same API as ssh exe.dev?

Yes. The SDK is generated from exe.dev's command tree and calls the [HTTPS API](/docs/https-api), which is the SSH command line in a POST body. `ssh exe.dev team members` is `exe.team.members()`, and `--copy-tags=false` is `copy_tags=False`. Try a command over SSH first, then write it in Python.

### Should I use the SDK or MCP?

Use the SDK when your code decides what happens: CI jobs, cron, a web app that gives each user a VM. Use [exe.dev MCP](/deploy/exe-mcp) when a model decides, in Claude Code, Codex, or an agent you build; it needs no tool code on your side.

### Where should the token live?

In a CI secret, a secret manager, or an environment variable on a machine only you use. Never on a VM you share with other people. A token made with `--tag` touches only VMs with that tag, and one with `--exp` expires on its own. See [Keep the token safe](#keep-the-token-safe).

### Is there a TypeScript SDK?

Yes: `npm install @exedev/sdk`, with the same coverage. See [TypeScript sandboxes](/deploy/typescript-sandboxes).


## Related

- [Create sandboxes from Python](https://exe.dev/deploy/python-sandboxes.md): Full VMs as sandboxes. A with block creates one, runs your code, and deletes it.
- [Create sandboxes from TypeScript](https://exe.dev/deploy/typescript-sandboxes.md): Full VMs as sandboxes. Create, control, and destroy them from your code.
- [Give any agent a sandbox over MCP](https://exe.dev/deploy/exe-mcp.md): One URL gives your agent real VMs to run code on, host apps from, and hand work to.
- [Sandboxes on exe.dev](https://exe.dev/deploy/sandbox.md): A VM with its own CPU and memory, billed by the second while it runs.
- [Run GitHub Actions jobs on exe.dev, a fresh VM per job](https://exe.dev/deploy/github-actions.md): Every job on a fresh copy of a warm VM, billed by the second.
- [Run Claude Code on a remote server](https://exe.dev/deploy/claude-code.md): A computer for Claude. A breather for your laptop.
