Skip to content

About

exe.dev SDK

Resources

Stars

3 stars

Watchers

0 watching

Forks

Latest commit

 

History

28 Commits

Folders and files

Repository files navigation

@exedev/sdk

Official JavaScript/TypeScript SDK for the exe.dev HTTPS API.

npm install @exedev/sdk

The package is ESM only, with no dependencies, and uses the runtime's fetch. It runs on Node 18 and later, Bun, and Deno. From CommonJS, use await import("@exedev/sdk"), or require() on Node 20.19+ or 22.12+, which load ES modules synchronously. You need an exe.dev API token: see Authentication.

Quick start

import exedev from "@exedev/sdk";

const exe = exedev(); // the token is $EXE_TOKEN; or pass { token }
const vm = await exe.new({ image: "ubuntu:24.04" });
// new waits for SSH by default. No create-then-ssh retry loop is needed.
try {
  console.log(vm.name, vm.httpsUrl);
  const result = await vm.ssh("uname -a");
  console.log(result.exitCode, result.stdout, result.stderr);
} finally {
  await vm.rm();
}

Client and VM API

exedev({ token?, baseURL?, fetch?, userAgent? }) creates a client. token defaults to the EXE_TOKEN environment variable (Node, Bun, Deno). baseURL defaults to https://exe.dev; fetch defaults to the global implementation. Named imports of exedev, ExedevClient, and VM are also available.

A tool built on the SDK names itself with userAgent, a product that goes before the SDK's own in every request's User-Agent. It must be visible ASCII, with spaces between products; anything else throws a TypeError at once.

const exe = exedev({ userAgent: "mytool/1.2" }); // User-Agent: mytool/1.2 exedev-js/0.7.0
  • exe.new(options?) creates a VM and returns a VM object.
  • exe.ls(nameOrPattern?, options?) returns VM[].
  • exe.vm(name) references an existing VM without making a request.
  • vm.refresh(options?) refreshes its metadata and returns the same object.
  • vm.ssh(command, options?) runs a shell command on that VM.
  • vm.cp({ name?, ...options }) copies it and returns a new VM object.
  • exe.rm(vms) deletes an array of VMs or names in one request; the server deletes several at a time. It resolves to { deleted, failed, not_found, errors } rather than throwing for VMs it could not delete.
  • Lifecycle and VM-scoped commands are methods on the VM: vm.rm(), vm.pause(), vm.resume() (its result's cold_booted is "true" when the VM booted afresh and lost its memory), vm.restart(), vm.rename(newName), vm.resize(options), vm.stat(options), vm.tag(tags), vm.comment(text), vm.shareShow(), vm.sharePort(port), and the other generated VM commands.
  • Account commands remain on the client: exe.whoami(), exe.sshKeyList(), exe.integrationsList(), exe.billingPlan(), etc.

exe.exec(line) runs a command line as you would type it after ssh exe.dev, for anything that has no method yet: it returns the JSON result, or text if there is none. Quote interpolated values with quote. There is no client-level ssh or cp: those are VM methods. vm.rm() throws ExeAPIError if the VM is not deleted, with status 404 if it does not exist. Options for generated commands retain CLI flag names (for example, { "no-email": true }); each method carries the server's help text. Every VM command except grantSupportRoot, and whoami, has a known JSON response: its method rejects anything else and resolves to the response's type. The wire types (VMRecord, NewResponse, ShareShowResponse, ...) are exported. A few report a problem in the result rather than as an error: domainAdd when DNS does not point at exe.dev yet and shelleyInstall when Shelley is missing; narrow with "error" in result. Other account commands may return JSON or text and are typed as unknown.

vm.name is the current name. vm.httpsUrl, vm.sshDest, and vm.tags expose common metadata. vm.info is a read-only snapshot with status, region, comment, createdAt, egressPolicy, and promptError (why new's prompt did not reach Shelley) when available. A reference from exe.vm(name) initially knows only its name, with no tags; call refresh() to fetch the rest. A copy from cp() has the tags and web URL the server reports for it. The SDK's own operations update the snapshot: a VM that passed a readiness wait is running, and pause(), resume(), comment(), tag(), and egress() record what they changed. A successful rename() updates the same object, with the new SSH destination and web URL the server reports. Other references, and changes made elsewhere, need refresh().

Egress

A VM may reach all of the internet ("all", the default), or only exe.dev's metadata service and the integrations attached to it ("integrations"). Set it at creation, so the VM never has a window with internet access, or later:

const vm = await exe.new({ egress: "integrations" });
const copy = await vm.cp({ egress: "all" }); // a copy keeps its source's unless told otherwise
await vm.egress("all");                        // change it; vm.egress() alone reports it
console.log(vm.info.egressPolicy);

Readiness and cancellation

new, cp, restart, and resume wait for SSH by default. Pass { waitUntil: "created" } to return without probing, including when the token has no ssh permission. vm.waitUntilReady({ waitUntil?, timeoutMs?, signal? }) explicitly waits later. The default readiness deadline is 60 seconds after creation or the lifecycle operation returns, including probe requests and backoff.

Readiness runs only the harmless command true, retrying transient connection failures. It never retries a user command or the creation request, and it does not wait for application servers.

{ waitUntil: "setup" } also waits for the VM's setup script (new's "setup-script", run by exeuntu's exe-setup.service) to finish, polling the unit over SSH with a default deadline of 10 minutes. If the script failed, the VMReadyError's cause is a VMSetupError with exitCode (or signal) and systemd's result; details().output has the end of its journal. Only exeuntu, the default image, and images built on it run setup scripts: on others, such as ubuntu:24.04, the script is not run, and waiting for it is a VMSetupError with result "unsupported". Without a script there is nothing to wait for, and once a script has run, a later restart does not wait for it.

const vm = await exe.new({ "setup-script": "#!/bin/sh\nsudo apt-get install -y jq", waitUntil: "setup" });

If waiting fails, VMReadyError.vm gives you the VM for inspection or cleanup; it is not automatically deleted. That includes a token without ssh permission: the probe is refused, and the error says to use waitUntil: "created". All operations accept an AbortSignal. Caller cancellation preserves signal.reason, including during streaming and callbacks, rather than wrapping it in another error. An aborted creation may still have created a VM; use an explicit name or ls() to recover it. Aborting vm.ssh() closes its connection but does not stop the command on the VM: one that is quiet, or writes only to files, keeps running. To bound a command's run time, bound it on the VM too, for example with timeout 60 make.

Running commands

vm.ssh() resolves to { exitCode, stdout, stderr, stdoutBytes, stderrBytes, captured }. A nonzero exit code is a result, not an exception; a command killed by signal N exits 128+N, as in a shell. Byte arrays preserve binary output; strings are decoded as UTF-8. The command is a shell script: quote any untrusted values you interpolate into it with quote.

import { quote } from "@exedev/sdk";
await vm.ssh(`cat ${quote(path)}`);

Commands run in a non-login shell. Variables from new's env are set for them. Long silent commands are fine: unlike other commands, ssh has no 30-second limit, and the server keeps the response alive.

await vm.ssh("make", {
  capture: false,
  onStdout: (chunk) => { process.stdout.write(chunk); },
  onStderr: (chunk) => { process.stderr.write(chunk); },
});

onStdoutBytes and onStderrBytes receive the raw bytes instead, for binary output; they may be given alongside the text callbacks. Callbacks are awaited serially, with incremental UTF-8 decoding per stream. Their cross-stream order is approximate. Throwing from a callback cancels the response and rejects with that error.

Output is captured by default, with an 8 MiB combined limit on stdout and stderr. Change it with maxOutputBytes; exceeding it cancels the response and throws SSHStreamError with code output_limit. Set capture: false for bounded-memory streaming of arbitrarily long output: callbacks still receive it, but result/error output is empty and captured is false. The capture limit is ignored in this mode. Invalid or oversized NDJSON frames are always rejected.

Files

await vm.writeFile("app/config.json", JSON.stringify(config)); // relative to the home directory
const data = await vm.readFile("/etc/os-release");              // a Uint8Array
await vm.upload("./site", "site", { exclude: [".git", "node_modules"] });
await vm.download("logs", "./logs");

Requests carry at most 64 KB and ssh has no stdin, so files travel as base64 in parts, several at a time. The VM needs base64, and gzip and tar for large files and directories, which exeuntu has. writeFile replaces the file and makes its directory; mode sets its permissions. A missing path is a VMFileError (code ENOENT or EISDIR); a failed helper command is a CommandError. upload and download need node:fs (Node, Bun, Deno).

Errors

  • ExeAPIError: operation and HTTP status. The message includes the server's error text, on one line, without terminal escapes or other control characters, and shortened to 200 characters, for example exe.dev API error (422) during ssh: VM "web" is not running. It never includes the request, but the server's text can mention values you sent. error.details().body has the full response; this may contain secrets.
  • ExeNetworkError: the request failed before a complete response arrived, such as a network error or a connection lost while reading the response. operation names the command, and the message the system error code when there is one. Whether the operation took effect is unknown: new may have created a VM, so pass a name if you need to find it again. details().cause has the transport's error.
  • ExeProtocolError: an incompatible response, including malformed JSON or a server that does not support NDJSON SSH output.
  • SSHStreamError: interrupted/invalid output or a capture limit. code is interrupted, protocol, or output_limit; getters provide captured partial output. The exit status is unknown. A request that fails before a response (for example, a network error) is interrupted too, since the command may have started. details() exposes opt-in diagnostics: the server's message or the transport's error.
  • VMReadyError: readiness failed; vm and cause are available.
  • VMSetupError: the setup script failed or did not run; the cause of a VMReadyError.

Errors do not establish that an operation never ran. Do not blindly retry a mutation or remote command after a transport failure.

Authentication

Generate a token via SSH:

ssh exe.dev ssh-key generate-api-key --label=my-app --exp=30d '--cmds="new,ls,ssh,rm"'

Keep the single quotes around --cmds: ssh passes the command to exe.dev as one line, so a list with spaces (such as "share add") must stay quoted there. --cmds lists the commands the token may run: include ssh, which new's readiness wait uses, or create VMs with waitUntil: "created". For automation, prefer a token scoped to a tag (--tag=my-app): it can see and manage only the VMs with that tag, and VMs it creates get the tag. A token can also be limited to client addresses (--ips=203.0.113.0/24), or signed locally from an SSH key you added to your account. See the HTTPS API docs for permissions and scoping.

signToken signs a token locally, with no request, from an OpenSSH private key whose public key is on your account (ssh exe.dev ssh-key add); removing the key revokes every token it signed. It takes Ed25519, ECDSA, and RSA keys without a passphrase.

import exedev, { signToken } from "@exedev/sdk";
const token = await signToken({
  privateKey: await readFile(`${homedir()}/.ssh/exe_dev_api`, "utf8"),
  permissions: { exp: Math.floor(Date.now() / 1000) + 3600, cmds: ["new", "ls", "ssh", "rm"] },
});
const exe = exedev({ token });

Development

All of src/ is generated. Edit cmd/gensdkjs and its TypeScript templates in the exe.dev repository, then run go run ./cmd/gensdkjs there. The one exception is src/version.ts, which npm run build, npm version, and npm run sync-commands write from package.json, the version's only source. Copy the outputs into this checkout and test:

npm install
npm run sync-commands -- ../exe
npm test

npm test builds the package, checks the public TypeScript API, and runs unit and live integration tests. Live tests require a tag-scoped token and create, copy, execute commands on, restart, rename, and delete their own test VMs. They read $EXE_TOKEN, or $EXE_TOKEN_FILE (a bare token or JSON containing token), or ~/.config/exedev/sdk-test-token. The expected tag is sdk-test (override with $EXE_TEST_TAG). Set $EXE_BASE_URL to test another deployment, such as https://exe-staging.dev. To create a test token:

ssh exe.dev 'ssh-key generate-api-key --label=sdk-test --tag=sdk-test --exp=30d --cmds="ls,new,whoami,stat,rm,restart,rename,cp,ssh,ssh-key list,share show" --json'

Set EXE_SKIP_INTEGRATION=1 to run without live access. Set EXE_SKIP_SSH_INTEGRATION=1 to exercise only the live control plane when the server has not yet deployed NDJSON SSH support; this explicitly skips live SSH and readiness assertions, not the corresponding unit tests. The full live suite requires that protocol and does not silently fall back to raw SSH output.

The generator's Go tests check regeneration and command grammar assumptions. Server-side wire-contract tests exercise creation, listing, copying, and SSH. To run the generated SDK end-to-end against the local Go HTTP/SSH fixture:

# In the exe.dev checkout, with this SDK's npm dependencies installed:
EXE_SDK_JS_DIR=/absolute/path/to/exe-sdk-js go test ./execore -run TestSDKJSHTTP

License

MIT

About

exe.dev SDK

Resources

Stars

3 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages