Skip to content

exe.dev Python SDK

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

exedev is exe.dev's official Python SDK. It wraps exe.dev's 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.

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)
$ 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. It needs Python 3.11 or later and depends only on HTTPX:

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:

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

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

Your first script#

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

# 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 as keyword arguments:

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. integrations= attaches integrations by name, egress="integrations" cuts the VM off from the internet, prompt= gives the VM's agent, Shelley, a task, and standalone=True makes a standalone VM 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:

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:

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:

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

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#

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 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:

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.

Your own code can't sign in with a browser. To call an API served by a private VM, make a VM token for it and send it in the X-Exedev-Authorization header:

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:

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.

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

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 describes. It runs ssh-keygen -Y sign, so ssh-agent and passphrases work:

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

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

Teams, pools, and billing#

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.

On a team, 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), exe.pool.list(), and exe.new(pool="ci") to place a VM in one of the team's 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:

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 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:

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

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

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:

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

# 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:

# 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 on an exe.dev VM, anthropic.Anthropic(base_url="https://llm.int.exe.xyz", api_key="unused") uses the LLM gateway 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. For a model that should drive exe.dev itself, without tool code of your own, use exe.dev MCP; for many short-lived code sandboxes, see Create sandboxes from Python.

Errors, retries, and rate limits#

Every exception the SDK raises is an exedev.ExeError:

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 APIErrors 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#

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

Is there a TypeScript SDK?

Yes: npm install @exedev/sdk, with the same coverage. See TypeScript sandboxes.

Published Nov 21, 2026 · Updated Nov 21, 2026 · tested end to end Nov 21, 2026 · Markdown · manifest.json · Something wrong? Tell us