Skip to content

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, then bun first.ts.
  • Deno: import npm:@exedev/sdk@0.6.0 and run with deno 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=scripts scopes it: VMs it creates are tagged scripts, and it can see and change no other VM.
  • --cmds lists the commands it may run. Keep ssh: besides running commands, new uses it to wait until a VM is ready. The single quotes matter, because ssh passes 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
  • cp copies the disk, with the source's tags and comment. Run sync first, 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 in failed, with reasons in errors; missing ones are also in not_found. vm.rm() throws an ExeAPIError instead, with status 404 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. --tag so it touches only its own VMs, the fewest --cmds that work, an --exp, and --ips when 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, and ssh exe.dev ssh-key list shows 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