exe.dev TypeScript and JavaScript SDK
Everything ssh exe.dev does, from TypeScript or JavaScript, on Node.js, Bun, or Deno.
@exedev/sdk is the official
TypeScript and JavaScript SDK for exe.dev. It wraps the
HTTPS API, which takes the same commands as
ssh exe.dev, so anything you can do there you can do from code: create,
copy, and delete VMs, run commands in them, move files, share them, and
manage SSH keys, API tokens, and integrations. Every command has a method,
with the server's help text as its documentation and a typed result.
It is one ES module with no dependencies that uses the runtime's fetch,
so it runs on Node.js 18 or later (18 is past its end of life; prefer 22
or later), Bun, and Deno. This page was tested with
@exedev/sdk 0.6.0 on Node.js 18.19, 20.19, 22.18, and 26.13, Bun 1.4.5, and Deno 2.9.8.
The SDK is before 1.0, and a minor release can change the API, so pin
@exedev/sdk@~0.6.0 in anything that lasts. To run a sandbox for an
agent's code, see Create sandboxes from TypeScript;
for Python, the Python SDK.
Install and get a token#
In a new project:
mkdir exe-scripts && cd exe-scripts
npm init -y && npm pkg set type=module
npm install @exedev/sdk
The package is ESM only. To run TypeScript files, use Node.js 22.18 or
later, which runs .ts files directly, or tsx on older
versions (npm install -D tsx, then npx tsx first.ts). Top-level
await needs "module": "nodenext" (or "esnext") and "target": "es2022" in tsconfig.json. From CommonJS, load it with
await import("@exedev/sdk"), or require() on Node.js 20.19+ or 22.12+.
- Bun:
bun add @exedev/sdk, thenbun first.ts. - Deno: import
npm:@exedev/sdk@0.6.0and run withdeno run --allow-env=EXE_TOKEN --allow-net=exe.dev first.ts. Those two permissions are all it needs.
The SDK authenticates with an API token. Make one that can touch only the VMs your code creates. On your computer:
ssh exe.dev ssh-key generate-api-key --label=scripts --tag=scripts --exp=30d \
'--cmds="new,ls,ssh,rm,cp,restart,stat"'
It prints a token that starts with exe1..
--tag=scriptsscopes it: VMs it creates are taggedscripts, and it can see and change no other VM.--cmdslists the commands it may run. Keepssh: besides running commands,newuses it to wait until a VM is ready. The single quotes matter, becausesshpasses the line to exe.dev as one string.- It expires in 30 days. To revoke it sooner:
ssh exe.dev ssh-key remove scripts.
The SDK reads the token from EXE_TOKEN, or you pass it:
exedev({ token }).
export EXE_TOKEN=exe1.โฆ
Your first script#
Create a VM, run a command in it, print its address, delete it:
// first.ts
import exedev from "@exedev/sdk";
const exe = exedev(); // reads EXE_TOKEN
const vm = await exe.new({ "no-email": true });
try {
const r = await vm.ssh("uname -sr && python3 --version");
console.log(r.stdout.trim());
console.log(vm.httpsUrl);
} finally {
await vm.rm();
}
$ node first.ts
Linux 6.12.115
Python 3.12.3
https://pelican-scholar.exe.xyz
The whole run takes about three seconds. new returns once the VM accepts
commands, so there is no retry loop to write. Let it pick the name: VM
names are global across exe.dev. "no-email": true skips the email
exe.dev otherwise sends for every new VM.
Options are the command's flags, spelled the same way ("no-email",
"setup-script"), and every method's documentation comment is the
server's help for it. The API explorer shows the same.
Create and manage VMs#
new takes the flags of new:
const vm = await exe.new({
cpu: 2, memory: "4GB", disk: "20GB",
comment: "nightly report", // shown in ls; handy for finding it again
env: ["GREETING=hello"], // set for every command
"setup-script": "#!/bin/bash\nset -e\nsudo apt-get install -y -q jq\n",
waitUntil: "setup", // wait for the setup script too
"no-email": true,
});
console.log(vm.name, vm.httpsUrl, vm.tags, vm.info.createdAt);
That VM, with its setup script, was ready in under six seconds. Other
options: name (leave it out for a free random one), image (a container image instead of the default Ubuntu 24.04
image), integration (attach integrations by name),
tag (one or a list: tag: ["preview", "web"], then in vm.tags),
egress: "integrations" (no internet, only attached
integrations), prompt (a first task for Shelley,
the agent on the VM), and sandbox: true (a
standalone VM with capacity of its own, billed by
the second).
If the setup script fails, new throws a VMReadyError whose cause is a
VMSetupError with the script's exitCode and the end of its log in
details().output. The VM is left for you to inspect; err.vm.rm()
deletes it.
Find and refer to VMs:
const all = await exe.ls(); // every VM the token can see
const reports = await exe.ls("report-*"); // names matching a pattern
const web = exe.vm("my-web"); // a reference, no request yet
await web.refresh(); // fetch its tags, status, comment
console.log(web.info.status, web.tags, web.info.comment);
The rest are methods on the VM:
await vm.ssh("sync"); // flush writes before copying
const copy = await vm.cp(); // ready for commands, like new; name optional
await copy.restart(); // waits until it's back
await copy.rename(`${vm.name}-old`); // copy.name and copy.httpsUrl follow
const { deleted, failed } = await exe.rm([copy, "some-other-vm"]); // several in one request
await vm.rm(); // throws if it wasn't deleted
cpcopies the disk, with the source's tags and comment. Runsyncfirst, or writes still in memory are left out of the copy.exe.rm(list)doesn't throw for VMs it couldn't delete: they are infailed, with reasons inerrors; missing ones are also innot_found.vm.rm()throws anExeAPIErrorinstead, withstatus404 if the VM was already gone.
Pause a VM you'll want again later. Its memory goes to disk and its CPU
and memory are freed; resume brings it back with its processes still
running:
await vm.pause(); // about 3 seconds
const { cold_booted } = await vm.resume(); // about 1 second, ready for commands
cold_booted is "true" if the VM booted afresh and lost its memory.
While a VM is paused, ssh throws an ExeAPIError with status 422.
Other changes, each one call:
await vm.comment("serves the docs"); // vm.info.comment follows
await vm.egress("integrations"); // no internet, only its integrations
await vm.egress("all"); // back to the default
A token made with --tag can't change tags (422 SSH key scoped to tag "โฆ" cannot modify tags): give VMs their tags in new.
Run commands and stream output#
vm.ssh() runs a bash script on the VM, as the exedev user in its home
directory, and waits for it:
const r = await vm.ssh("echo $GREETING; jq --version; echo oops >&2; exit 3");
r.exitCode; // 3
r.stdout; // "hello\njq-1.7\n"
r.stderr; // "oops\n"
A failing command is a result, not an exception: check exitCode. Each
call is a new non-login shell, so cd and variables don't carry over, but
the env given to new is set. There is no stdin or terminal. Quote
anything you put into a command with quote:
import { quote } from "@exedev/sdk";
await vm.ssh(`grep -c ERROR ${quote(logPath)}`);
To see output as it arrives, pass callbacks:
await vm.ssh("cd app && make test", {
onStdout: (text) => { process.stdout.write(text); },
onStderr: (text) => { process.stderr.write(text); },
});
Output is also collected for the result, up to 8 MiB in all
(maxOutputBytes changes it; past it, an SSHStreamError). Pass
capture: false to stream any amount without keeping it.
onStdoutBytes and onStderrBytes get raw bytes, for binary output.
Warning
In 0.6.0, aborting a call (
signal: AbortSignal.timeout(60_000)) makes it throw, but the command keeps running on the VM. To limit how long a command runs, limit it on the VM:vm.ssh("timeout 60 make test")stops it and its children and exits 124.
ssh has no time limit of its own, and commands survive a dropped
connection. For a job you want to check on later, start it in the
background with its output in a file, and poll:
await vm.ssh("setsid nohup bash -c './build.sh; echo $? > build.exit' > build.log 2>&1 < /dev/null &");
while ((await vm.ssh("test -f build.exit")).exitCode !== 0) {
await new Promise((r) => setTimeout(r, 5000));
}
console.log((await vm.ssh("cat build.exit; tail -n 20 build.log")).stdout);
Redirect all three of the job's streams, as above, or ssh waits for the
job to finish.
Move files#
await vm.writeFile("app/config.json", JSON.stringify({ debug: true })); // makes app/
await vm.writeFile("bin/run.sh", "#!/bin/sh\necho ran\n", { mode: 0o755 });
const data = await vm.readFile("app/config.json"); // a Uint8Array
console.log(new TextDecoder().decode(data));
await vm.upload("./site", "site", { exclude: [".git", "node_modules"] });
await vm.download("logs", "./logs");
Relative paths are in the VM's home directory. The API has no stdin and
takes at most 64 KB a request, so files travel as compressed base64 in
parts, several at a time: in our tests a 1 MB file of random bytes took
about 2 seconds to write, 1 MB of text 0.4 seconds, and reading 1 MB back
0.6 seconds. For hundreds of megabytes, have the VM fetch them
(git clone, curl) or use scp to <vm>.exe.xyz.
A missing path throws a VMFileError with code "ENOENT" (or
"EISDIR"). upload and download need node:fs, which Node.js, Bun,
and Deno all have.
Share a VM and reach it from code#
exe.dev's HTTPS proxy serves port 8000 of every VM at
vm.httpsUrl, with TLS, private until you share it. Start a server and
open it to anyone with the link:
await vm.writeFile("www/index.html", "<h1>hello</h1>\n");
await vm.ssh("setsid nohup python3 -m http.server 8000 --directory www > http.log 2>&1 < /dev/null &");
await vm.shareSetPublic();
console.log(vm.httpsUrl); // anyone can open it now
await vm.shareSetPrivate(); // and now only you again
console.log(await vm.shareShow()); // { status: "private", port: 8000, users: [], links: [], ... }
Start servers as one command with all three streams redirected, as above.
cd www && setsid nohup ... & puts the whole && list in the
background, still holding the command's output, and ssh waits for the
server to exit, which is never.
A private VM sends browsers to exe.dev's login, and answers other clients
with 401. For your own code (a script, a webhook sender, another
server) to reach a private VM, give it a
VM token, which works only for that VM's
HTTPS address:
const { token } = await exe.sshKeyGenerateApiKey({ vm: vm.name, label: "reporter", exp: "30d" });
const res = await fetch(`${vm.httpsUrl}/api/report`, {
headers: { "X-Exedev-Authorization": `Bearer ${token}` },
});
The proxy strips the header and passes the request on with
X-ExeDev-Email and X-ExeDev-UserID set to yours, as for a signed-in
browser. Tools that only do Basic auth, like git, can send the token as
the password, with any username. Revoke it with
exe.sshKeyRemove("reporter"). A tag-scoped token can make VM tokens
only for VMs with its tag.
SSH keys and API tokens#
Code can make the narrower tokens other code needs. This one can only run
ls and whoami, for an hour, from one address range:
const key = await exe.sshKeyGenerateApiKey({
label: "ci-report",
tag: "ci", // only VMs tagged ci
cmds: "ls,whoami",
exp: "1h",
ips: "203.0.113.0/24", // 0.6.0: limit where it can be used from
});
key.token; // exe1.โฆ
key.expires_at; // "2026-11-21T17:14:35Z"
Used from anywhere else, it gets 403 token not allowed from <address>;
running a command it doesn't have gets 403 command not allowed by token permissions. A token made by a tag-scoped token keeps that tag, and can't
ask for another.
sshKeyAdd puts a public key on your account. New in 0.6.0, it can be
scoped to VMs (vm, one name or several) and to address ranges (ips),
so the key can ssh to those VMs and nothing else, not even
ssh exe.dev. With a key made by
ssh-keygen -t ed25519 -N '' -C deploy-key -f deploy_key:
import { readFile } from "node:fs/promises";
const pub = await readFile("deploy_key.pub", "utf8");
await exe.sshKeyAdd(pub.trim(), { vm: ["my-web"] }); // named after the key's comment
console.log(await exe.sshKeyList());
await exe.sshKeyRemove("deploy-key"); // revokes it and its tokens
signToken makes tokens from a key on your account without asking
exe.dev: the local signing recipe, in code.
It takes an OpenSSH private key (Ed25519, ECDSA, or RSA) without a
passphrase. With vm, it makes a VM token, and ctx reaches the VM's
server as the X-ExeDev-Token-Ctx header:
import { signToken } from "@exedev/sdk";
const token = await signToken({
privateKey: await readFile("deploy_key", "utf8"),
vm: "my-web",
permissions: { exp: new Date(Date.now() + 3600_000), ctx: { job: 42 } },
});
// X-Exedev-Authorization: Bearer <token>; the server sees X-ExeDev-Token-Ctx: {"job":42}
Without vm, it signs an API token (exe0.โฆ) for exedev({ token }),
with permissions such as { exp, cmds: ["whoami"] }. The token can do
no more than its key: a key added by a tag-scoped token keeps the tag, and
a key scoped to VMs can't use the API at all (403 VM-scoped SSH keys cannot access /exec).
Removing the key revokes every token it signed. On Node.js 18, signing
with Ed25519 prints an "experimental" warning; it works.
Integrations#
Integrations let code on a VM use an outside service
without its credentials ever being on the VM. These commands are
account-wide, so they need a token without --tag: exe.dev refuses
integrations list to tag-scoped ones.
const mine = await exe.integrationsList(); // yours, with their attachments
const kinds = await exe.integrationsList({ available: true }); // what you can add
await exe.integrationsAdd("http-proxy", {
name: "httpbin",
target: "https://httpbin.org",
bearer: process.env.HTTPBIN_TOKEN, // stored by exe.dev, never on the VM
comment: "for the report job",
});
await exe.integrationsAttach("httpbin", `vm:${vm.name}`, { for: "1h" }); // or tag:NAME, auto:all
console.log(await exe.integrationsShow("httpbin")); // the header shows as "Authorization:Bearer ***"
From the VM, https://httpbin.int.exe.xyz/ now reaches httpbin.org with
the Authorization header added on the way. In our test, the header
arrived at httpbin.org and the token was nowhere on the VM. attach
also takes until (an RFC 3339 time) instead of for; the attachment
then lapses by itself, and shows as vm:NAME@<time>. integrationsAdd
takes attach too, to do both at once. integrationsDetach cuts a VM
off, though in our test it took about 40 seconds to take effect.
integrationsAdd,
integrationsAttach, integrationsDetach, and integrationsRemove
return an empty string on success and throw on failure.
new({ integration: "httpbin" }) attaches integrations when it creates
the VM. See the http-proxy integration
for header and path options, and GitHub for
repositories.
Teams, pools, and billing#
billingUsage reports your account's compute, disk, and bandwidth for
the current billing cycle or a range:
const usage = await exe.billingUsage({ range: "24h" }) as {
vm_count: number; disk_used_bytes: number; disk_overage_bytes: number; tx_bytes: number;
};
console.log(`${usage.vm_count} VMs, ${(usage.disk_used_bytes / 1e9).toFixed(0)} GB of disk`);
const byVM = await exe.billingUsage({ range: "7d", group: "vm" }); // per VM, with estimated cents
Account commands like these return JSON typed as unknown, so cast them
to the fields you use. The team commands (team, teamMembers,
teamSettings, teamSettingsPublicSharing, teamSettingsVmSharing) and
pool commands (poolList, poolNew, poolResize) mirror
ssh exe.dev team and ssh exe.dev pool for a team with
pools. We tested them only on a Personal account, where
team() returns an empty string and the others fail with
422 command not available.
Any other command#
exe.exec() runs a command line exactly as you would type it after
ssh exe.dev, for anything without a method, or to paste a line from the
docs. It returns the command's JSON:
import { quote } from "@exedev/sdk";
const me = (await exe.exec("whoami")) as { email: string };
const found = await exe.exec(`ls ${quote("ts-*")}`);
Quote values you put into the line with quote, as for ssh. The
token's --cmds still apply: a command it may not run throws an
ExeAPIError with status 403.
Recipes#
A nightly copy of a VM#
Copy a VM every night to <name>-<date>, pause the copy so it uses no CPU
or memory, and keep the newest seven:
// nightly-copy.ts: run as `node nightly-copy.ts my-web`
import exedev from "@exedev/sdk";
const exe = exedev();
const source = exe.vm(process.argv[2]);
const keep = 7;
const day = new Date().toISOString().slice(0, 10).replaceAll("-", "");
await source.ssh("sync"); // flush writes to disk first
const copy = await source.cp({ name: `${source.name}-${day}`, waitUntil: "created" });
await copy.pause();
console.log(`copied ${source.name} to ${copy.name}`);
const copies = (await exe.ls(`${source.name}-*`))
.filter((vm) => /-\d{8}$/.test(vm.name))
.sort((a, b) => a.name.localeCompare(b.name));
const old = copies.slice(0, -keep);
if (old.length) {
const { deleted } = await exe.rm(old);
console.log(`deleted ${deleted.join(" ")}`);
}
Each run took under five seconds. It needs a token with ssh, cp,
pause, ls, and rm; run it from cron or a scheduled CI job. To get
files back, resume() a copy and readFile or download from it, or
cp it to a new VM. Copies are whole disks, so disk beyond your plan's
allowance is billed as usage. For backups of
specific data to another place, see Back up to exe.dev.
A preview VM for each pull request#
A GitHub Actions workflow that puts each pull request on its own VM, keeps
the address while the PR is updated, comments it on the PR once, and
deletes the VM when the PR closes. The token, in the repository's secrets
as EXE_TOKEN, needs only its own tag:
ssh exe.dev ssh-key generate-api-key --label=previews --tag=preview --exp=90d \
'--cmds="new,ls,ssh,rm,share set-public"'
# .github/workflows/preview.yml
name: Preview
on:
pull_request:
types: [opened, synchronize, reopened, closed]
concurrency: preview-${{ github.event.pull_request.number }}
jobs:
preview:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 24
- run: npm install --no-save @exedev/sdk@0.6.0
- id: preview
run: node .github/exe-preview.mjs
env:
EXE_TOKEN: ${{ secrets.EXE_TOKEN }}
PR: ${{ github.event.pull_request.number }}
PR_ACTION: ${{ github.event.action }}
- if: steps.preview.outputs.new == 'true'
run: gh pr comment "$PR" --body "Preview: $URL"
env:
GH_TOKEN: ${{ github.token }}
PR: ${{ github.event.pull_request.number }}
URL: ${{ steps.preview.outputs.url }}
// .github/exe-preview.mjs: one preview VM per pull request
import { appendFileSync } from "node:fs";
import exedev from "@exedev/sdk";
const exe = exedev(); // EXE_TOKEN
const { PR, PR_ACTION, GITHUB_REPOSITORY, GITHUB_OUTPUT } = process.env;
const comment = `preview ${GITHUB_REPOSITORY}#${PR}`;
const existing = (await exe.ls()).find((vm) => vm.info.comment === comment);
if (PR_ACTION === "closed") {
if (existing) await existing.rm();
process.exit(0);
}
const vm = existing ?? (await exe.new({ comment, "no-email": true }));
await vm.ssh("test -f server.pid && kill $(cat server.pid); rm -rf app");
await vm.upload(".", "app", { exclude: [".git", "node_modules"] });
// Start your app on port 8000; this one is static files.
await vm.ssh("setsid nohup python3 -m http.server 8000 --directory app > server.log 2>&1 < /dev/null & echo $! > server.pid");
await vm.shareSetPublic();
appendFileSync(GITHUB_OUTPUT, `url=${vm.httpsUrl}\nnew=${!existing}\n`);
console.log(`preview: ${vm.httpsUrl}`);
The PR is found again by the VM's comment, so the address stays the same
across pushes. The checkout is uploaded rather than cloned, so the VM
needs no GitHub credentials. For a real app, replace the http.server
line with your build and start commands, or run the app as a systemd
service. To keep previews private, leave out shareSetPublic and
share the VMs with your reviewers instead. Pull requests
from forks don't get repository secrets, so they get no preview.
Note
We ran the script against exe.dev with the same environment variables Actions sets (opened, a second push, closed), but not inside GitHub Actions itself.
For CI that runs whole jobs on exe.dev VMs, see GitHub Actions.
Clean up stale VMs by tag#
Scripts crash, and VMs get left behind. Sweep them by tag and age:
// reap.ts: delete VMs tagged "preview" that are more than 3 days old
import exedev from "@exedev/sdk";
const exe = exedev();
const maxAge = 3 * 24 * 3600_000;
const stale = (await exe.ls()).filter((vm) =>
vm.tags.includes("preview") && Date.now() - Date.parse(vm.info.createdAt ?? "") > maxAge);
const { deleted, failed, errors } = await exe.rm(stale);
console.log(`deleted ${deleted.length}: ${deleted.join(" ")}`);
if (failed.length) console.error("failed:", errors);
With a token made with --tag=preview, ls returns only those VMs, so
the sweep can't reach anything else, whatever the filter says.
Tools for an LLM agent#
Give a model a VM to work in: a run tool backed by vm.ssh. This uses
the Anthropic SDK through exe.dev's LLM gateway,
so on an exe.dev VM it needs no API key; elsewhere, use your own key and
leave out baseURL.
// agent.ts
import Anthropic from "@anthropic-ai/sdk";
import exedev, { quote } from "@exedev/sdk";
const exe = exedev();
const llm = new Anthropic({ baseURL: "https://llm.int.exe.xyz/anthropic", apiKey: "exe-gateway" });
const tools: Anthropic.Tool[] = [{
name: "run",
description: "Run a bash command on a fresh Ubuntu 24.04 VM; returns exit code, stdout and stderr.",
input_schema: { type: "object", properties: { command: { type: "string" } }, required: ["command"] },
}];
const vm = await exe.new({ "no-email": true, comment: "agent sandbox" });
try {
const messages: Anthropic.MessageParam[] = [
{ role: "user", content: "How many CPUs and how much memory does your machine have? Use the run tool." },
];
for (let turn = 0; turn < 10; turn++) {
const res = await llm.messages.create({ model: "claude-sonnet-5-5", max_tokens: 1024, tools, messages });
messages.push({ role: "assistant", content: res.content });
if (res.stop_reason !== "tool_use") {
for (const b of res.content) if (b.type === "text") console.log(b.text);
break;
}
const results: Anthropic.ToolResultBlockParam[] = [];
for (const b of res.content) {
if (b.type !== "tool_use") continue;
const { command } = b.input as { command: string };
console.log(`$ ${command}`);
const r = await vm.ssh(`timeout 120 bash -c ${quote(command)}`);
results.push({ type: "tool_result", tool_use_id: b.id,
content: `exit ${r.exitCode}\n${r.stdout.slice(-10000)}\n${r.stderr.slice(-2000)}` });
}
messages.push({ role: "user", content: results });
}
} finally {
await vm.rm();
}
$ node agent.ts
$ nproc; free -h
$ lscpu | head -20; grep MemTotal /proc/meminfo
The machine has **2 CPUs** and about **7.7 GiB of memory** ...
timeout 120 bounds each command on the VM, and the VM is deleted at the
end. Add writeFile and readFile tools the same way. To hand an agent
all of exe.dev instead (creating and sharing VMs itself) with no tool code
of your own, connect it to exe.dev's MCP server. For
code an agent writes that you don't trust, read
Run untrusted code first.
Errors, retries and rate limits#
Every error is a subclass of Error you can test with instanceof:
| Error | When |
|---|---|
ExeAPIError |
exe.dev refused the request. status is the HTTP status, and the message says why: exe.dev API error (422) during ssh: VM "x" is not running. |
ExeNetworkError |
The request failed on the way. Whether it took effect is unknown: new may have created a VM, so give it a name or comment to find it by. |
SSHStreamError |
A command's output was cut off (code "interrupted" or "output_limit"). The command may still be running. |
VMReadyError |
A VM was created, copied, restarted, or resumed but didn't accept commands within 60 seconds (timeoutMs), or its setup script failed. vm is the VM. |
VMFileError, CommandError |
A file operation found no such path, or its helper command failed on the VM. |
The statuses you'll meet: 401 (token malformed, expired, or revoked),
403 (command not in the token's cmds, or wrong address), 413 (a
request over 64 KB), 422 (the command failed: no such VM, a bad flag,
not allowed for this token's tag), 429 (too many requests from this
token's SSH key), and 504 (a command over its time limit; most get 30
seconds, new 9 minutes, cp 5ยฝ). The HTTPS API
docs have the full list.
The SDK never retries on its own, except while waiting for a VM to be
ready. Retry what is safe to repeat (ls, stat, whoami, readFile)
when exe.dev is busy or the connection failed:
import { ExeAPIError, ExeNetworkError } from "@exedev/sdk";
export async function retry<T>(fn: () => Promise<T>, tries = 5): Promise<T> {
for (let i = 1; ; i++) {
try {
return await fn();
} catch (err) {
const again = err instanceof ExeNetworkError ||
(err instanceof ExeAPIError && (err.status === 429 || err.status >= 500));
if (!again || i >= tries) throw err;
await new Promise((r) => setTimeout(r, 500 * 2 ** i + Math.random() * 500));
}
}
}
const vms = await retry(() => exe.ls());
Don't wrap new, cp, rm, or ssh this way: after a network error
they may have happened. Check first (find the VM by name or comment, test
for the file the command writes), then decide. The rate limit is per SSH
key, so give independent workloads their own tokens.
Keep the token safe#
Anyone with the token can do whatever its --cmds allow, from anywhere
its --ips allow, until it expires.
- Scope it.
--tagso it touches only its own VMs, the fewest--cmdsthat work, an--exp, and--ipswhen it's used from fixed addresses (not from VMs, whose addresses are shared). - Keep it in a secret store: CI secrets, your server's environment or secret manager. Never in the repository or in client-side code: a browser bundle hands it to every visitor.
- Don't put it on shared VMs, or on VMs that run code you don't trust. Code on an exe.dev VM that needs an outside API can call it through an http-proxy integration, which adds the credential on the way out so it never touches the VM.
- One token per job. Each is a separate SSH key on your account, so
ssh exe.dev ssh-key remove <label>revokes one without touching the others, andssh exe.dev ssh-key listshows when each was last used.
Frequently asked questions#
How do I install the exe.dev TypeScript SDK?
npm install @exedev/sdk (or bun add @exedev/sdk; in Deno, import npm:@exedev/sdk). It is ESM only, with no dependencies, for Node.js 18 or later. This page was tested with 0.6.0; until 1.0 a minor release can change the API, so pin @exedev/sdk@~0.6.0.
Does it work with Bun, Deno, and CommonJS?
Yes. We ran the same script on Node.js 18.19, 20.19, 22.18, and 26.13, Bun 1.4.5, and Deno 2.9.8 (with --allow-env=EXE_TOKEN --allow-net=exe.dev). From CommonJS, use await import("@exedev/sdk"), or require() on Node.js 20.19+ or 22.12+.
Can I call it from a browser?
Don't: anyone who can read the token can use it until it expires. Keep the token on a server and have the browser ask that server.
Should I use the SDK, the MCP server, or ssh exe.dev?
All three run the same commands. Use the SDK when your own code decides what to do, exe.dev's MCP server when a model should decide with no tool code of yours, and ssh exe.dev by hand or from shell scripts. exe.exec() takes any ssh exe.dev command line as it is.
Is there a Python SDK?
Yes, pip install exedev, with the same commands and the same structure; see the Python SDK.
What does it cost?
The SDK is free and MIT licensed. VMs it creates are ordinary VMs on your plan: they share its CPU and memory and count toward its VM limit, and disk and bandwidth beyond the allowance are billed as usage. new({ sandbox: true }) makes a VM with capacity of its own, billed by the second while it runs. See pricing.
Published Nov 21, 2026 · Updated Nov 21, 2026 · tested end to end Nov 21, 2026 · Markdown · manifest.json · Something wrong? Tell us