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.โฆ
--cmdsdecides which methods work. Keepssh:run()uses it, and so doesnew(), to wait until a VM accepts commands. Keeprm, which thewithblock 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-applimits the token to VMs taggedmy-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=30dmakes 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, withregistry_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, andstandalone=Truemakes a standalone VM with capacity of its own.- With
wait_until="setup", a failing setup script raisesexedev.VMSetupErrorwith itsexit_codeandoutput, and the VM is deleted.keep_on_failure=Truekeeps it, aserr.vm, to debug. - A token made with
--tagtags 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=...)raisesCommandTimeoutErrorwhen time runs out, but the command keeps running on the VM (a known issue in the changelog). So does cancelling anasynciotask that waits onrun(). 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_retriestimes (5), beforeRateLimitError. The limit is per SSH key, so give independent workloads tokens of their own. Set it withexedev.Client(max_retries=...). - Nothing else is retried for you, because not everything is safe to run
twice. After a
NetworkErrorfromnew(), the VM may or may not exist: look for it by itscomment. After aCommandInterruptedError, the command may still be running. NotFoundErrorfrom a tagged token means the VM doesn't exist or doesn't have the tag.- Other
APIErrors havestatus422: 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--tagwhen it manages VMs, and an--exp. A token made with--tagcan'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")orssh 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: throwaway VMs for code you run, in depth.
- TypeScript sandboxes: the TypeScript
SDK,
@exedev/sdk. - exe.dev MCP: the same commands for an agent, with no code.
- The HTTPS API the SDK calls, and the
API explorer, where you can try every command. Each one also
works over SSH:
ssh exe.dev help. - The source and changelog.
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