---
title: "exe.dev TypeScript and JavaScript SDK"
description: "npm install @exedev/sdk: the official exe.dev TypeScript and JavaScript SDK for Node.js, Bun, and Deno. Create VMs, run commands, and manage keys and tokens."
url: https://exe-staging.dev/deploy/typescript-sdk
category: "AI agents"
published: 2026-11-21
updated: 2026-11-21
---

# exe.dev TypeScript and JavaScript SDK

Everything ssh exe.dev does, from TypeScript or JavaScript, on Node.js, Bun, or Deno.

- **Software:** exe.dev TypeScript SDK (https://www.npmjs.com/package/@exedev/sdk)
- **Source:** https://github.com/boldsoftware/exe-sdk-js
- **License:** MIT
- **Machine-readable:** https://exe-staging.dev/deploy/typescript-sdk/manifest.json

[`@exedev/sdk`](https://www.npmjs.com/package/@exedev/sdk) is the official
TypeScript and JavaScript SDK for exe.dev. It wraps the
[HTTPS API](/docs/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](/deploy/typescript-sandboxes);
for Python, the [Python SDK](/deploy/python-sdk).

## Install and get a token

In a new project:

```bash
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`](https://tsx.is) 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:

```bash
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 })`.

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

## Your first script

Create a VM, run a command in it, print its address, delete it:

```ts
// 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();
}
```

```console
$ 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](/api?cmd=help+new) shows the same.

## Create and manage VMs

`new` takes the flags of [`new`](/api?cmd=help+new):

```ts
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](#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](/docs/shelley/intro),
the agent on the VM), and `sandbox: true` (a
[standalone VM](/docs/standalone-vms) 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:

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

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

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

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

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

```ts
import { quote } from "@exedev/sdk";
await vm.ssh(`grep -c ERROR ${quote(logPath)}`);
```

To see output as it arrives, pass callbacks:

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

```ts
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

```ts
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](/docs/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:

```ts
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](/docs/https-tokens-for-vms), which works only for that VM's
HTTPS address:

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

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

```ts
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](/docs/https-api-local-key) 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:

```ts
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](/docs/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.

```ts
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](/docs/integrations-http-proxy)
for header and path options, and [GitHub](/docs/integrations-github) for
repositories.

## Teams, pools, and billing

`billingUsage` reports your account's compute, disk, and bandwidth for
the current billing cycle or a range:

```ts
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](/docs/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:

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

```ts
// 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](/docs/billing/usage). For backups of
specific data to another place, see [Back up to exe.dev](/deploy/backup-to-exe).

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

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

```yaml
# .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 }}
```

```js
// .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](/docs/sharing) 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](/deploy/github-actions).

### Clean up stale VMs by tag

Scripts crash, and VMs get left behind. Sweep them by tag and age:

```ts
// 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](/docs/integrations-llm),
so on an exe.dev VM it needs no API key; elsewhere, use your own key and
leave out `baseURL`.

```ts
// 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();
}
```

```console
$ 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](/deploy/exe-mcp). For
code an agent writes that you don't trust, read
[Run untrusted code](/deploy/typescript-sandboxes#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/https-api#troubleshooting)
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:

```ts
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](/docs/integrations-http-proxy), 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](/deploy/exe-mcp) 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](/deploy/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](/docs/billing/usage). `new({ sandbox: true })` makes a VM with capacity of its own, billed by the second while it runs. See [pricing](https://exe.dev/pricing).


## Related

- [exe.dev Python SDK](https://exe-staging.dev/deploy/python-sdk.md): Everything ssh exe.dev does, from Python code, sync or asyncio.
- [Create sandboxes from TypeScript](https://exe-staging.dev/deploy/typescript-sandboxes.md): Full VMs as sandboxes. Create, control, and destroy them from your code.
- [Give any agent a sandbox over MCP](https://exe-staging.dev/deploy/exe-mcp.md): One URL gives your agent real VMs to run code on, host apps from, and hand work to.
- [Sandboxes on exe.dev](https://exe-staging.dev/deploy/sandbox.md): A VM with its own CPU and memory, billed by the second while it runs.
- [Run GitHub Actions jobs on exe.dev, a fresh VM per job](https://exe-staging.dev/deploy/github-actions.md): Every job on a fresh copy of a warm VM, billed by the second.
- [Run CI on exe.dev, a fresh VM for every job](https://exe-staging.dev/deploy/ci.md): A warm base VM, a fresh copy per job, deleted when the job ends.
