Exe Dev/vm

@webframp/exe-dev/vmv2026.09.18.1· 17d agoMODELS

01README

exe.dev VM lifecycle model. Wraps the exe.dev HTTPS API to manage VMs as typed swamp resources — create, destroy, restart, resize, observe fleet state, execute commands, manage sharing, and track Shelley versions.

Authentication

Uses a bearer token generated via ssh exe.dev ssh-key generate-api-key. Run the setup method to generate a token with the correct permissions and store it in your vault automatically.

Quick Start

swamp extension pull @webframp/exe-dev/vm
swamp model create @webframp/exe-dev/vm exe-dev
# Edit model YAML to set: token: '${{ vault.get("vault-name", "exe-dev-api-token") }}'
swamp model method run exe-dev setup
swamp model method run exe-dev sync

02Release Notes

2026.09.18.1

Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the repo. No behavioral changes in this extension.

03Models1

@webframp/exe-dev/vmv2026.09.18.1exe-dev/vm.ts

Global Arguments

Argument	Type	Required	Description
token?	string	no	exe.dev API bearer token (use vault reference). Generate with the

fn setup(expiry: string, vaultName: string, secretKey: string)

Generate a fully-permissioned exe.dev API token and store it in the

Argument	Type	Required	Description
expiry	string	yes	Token lifetime (e.g. 7d, 30d, 90d)
vaultName	string	yes	Vault to store the token in
secretKey	string	yes	Secret key name within the vault

fn sync()

List all VMs and store as a fleet snapshot. The adopt/observe pattern

fn create(name?: string, image?: string, cpu?: number, memory?: string, disk?: string, tags?: array, comment?: string, setupScript?: string, env?: record, integrations?: array)

Provision a new exe.dev VM. Returns the created VM details.

Argument	Type	Required	Description
name?	string	no	VM name (auto-generated if omitted)
image?	string	no	Container image (e.g. ubuntu:22.04)
cpu?	number	no	Number of CPUs (default 2)
memory?	string	no	Memory allocation (e.g. 4GB, 8G)
disk?	string	no	Disk size (e.g. 20GB, 50G)
tags?	array	no	Tags to apply
comment?	string	no	Short comment about the VM (max 200 bytes)
setupScript?	string	no	Setup script to run on first boot (max 10KiB)
env?	record	no	Environment variables as KEY=VALUE pairs
integrations?	array	no	Integration names to attach

fn destroy(names: array)

Delete one or more exe.dev VMs by name.

Argument	Type	Required	Description
names	array	yes	VM name(s) to delete

fn restart(name: string)

Restart an exe.dev VM.

Argument	Type	Required	Description
name	string	yes	VM name to restart

fn resize(name: string, cpu?: number, memory?: string, disk?: string)

Resize a VM's CPU, memory, or disk.

Argument	Type	Required	Description
name	string	yes	VM name to resize
cpu?	number	no	New CPU count
memory?	string	no	New memory (e.g. 8GB)
disk?	string	no	New disk size (must be larger than current)

fn stat(name: string, range: enum)

Fetch CPU, memory, disk, and IO metrics for a VM.

Argument	Type	Required	Description
name	string	yes	VM name
range	enum	yes	Time range for metrics

fn tag(name: string, add?: array, remove?: array)

Add or remove tags on a VM.

Argument	Type	Required	Description
name	string	yes	VM name
add?	array	no	Tags to add
remove?	array	no	Tags to remove

fn exec(name: string, command: string, timeout: number)

Execute a shell command on a VM via SSH. Stores the output as

Argument	Type	Required	Description
name	string	yes	VM name to execute on
command	string	yes	Shell command to run (max 64KB)
timeout	number	yes	SSH command timeout in seconds (max 300)

fn comment(name: string, text: string)

Set or clear a short comment on a VM (max 200 bytes).

Argument	Type	Required	Description
name	string	yes	VM name
text	string	yes	Comment text (empty string to clear)

fn share(name: string, action: enum, email?: string, linkToken?: string, root?: boolean)

Manage sharing on a VM: set public/private, add/remove users,

Argument	Type	Required	Description
name	string	yes	VM name
action	enum	yes	Sharing action to perform
email?	string	no	Email address (required for add/remove actions)
linkToken?	string	no	Share link token (required for remove-link)
root?	boolean	no	Grant/revoke shell (SSH) access instead of web-only (for add/remove)

fn shelley_versions(filter?: array)

Fan out across all VMs (or a filtered subset) and check the

Argument	Type	Required	Description
filter?	array	no	VM names to check (default: all VMs from latest fleet sync)

fn shelley_upgrade(names?: array)

Upgrade Shelley on one or more VMs via the exe.dev API

Argument	Type	Required	Description
names?	array	no	VM names to upgrade. Default: all VMs where shelley_versions

Resources

fleet(infinite)— Snapshot of all exe.dev VMs visible to the authenticated account.

vm(infinite)— Individual VM state after create/restart/resize operations.

stat(infinite)— VM resource metrics (CPU, memory, disk, IO).

exec(infinite)— Output of a command executed on a VM via SSH.

shelleyVersions(infinite)— Shelley/Claude Code version observed on each VM in the fleet.

shelleyUpgrade(infinite)— Result of a Shelley upgrade operation per VM.

04Previous Versions9

2026.09.15.1Sep 15, 2026

2026.09.15.1

Changed: Bump zod 4.4.3 → 4.6.5

2026.08.28.1

Changed: Normalized the extension license to Apache-2.0 and corrected the copyright holder to "Sean Escriva". Extensions that previously shipped an MIT LICENSE.md are now Apache-2.0, consistent with the repository root and every other extension. No code or behavioral changes.

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.26.3

Fixed: Restored inline npm:zod@4.4.3 import specifiers so the registry quality scorer can resolve dependencies and score the extension. An earlier release used a bare "zod" import-map specifier, which published but scored as unscored.

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.28.1Aug 28, 2026

2026.08.28.1

Upgrade note: License text only. No API, schema, or runtime behavior changed.

2026.08.26.3

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.3Aug 27, 2026

2026.08.26.3

Changed: Retained explicit compilerOptions.strict in deno.json. No behavioral or schema changes.

2026.08.26.1Aug 27, 2026

2026.08.26.1

Changed: Normalized deno.json configuration for repo-wide consistency: added explicit compilerOptions.strict and migrated zod dependency to the import map (bare "zod" specifier instead of inline npm:zod@4.4.3). No behavioral changes — runtime resolution is identical.

2026.08.24.2Aug 24, 2026

2026.08.24.2

Added: Output metadata attributes for observability.

durationMs: Method execution duration in milliseconds.
collectedBy: Extension name that produced the data.
fetchedAt: ISO 8601 timestamp when data was fetched (added to resources that previously lacked it).

2026.08.24.1Aug 24, 2026

2026.08.24.1

Added Troubleshooting section documenting requireToken setup dependency, 30s API timeout, per-VM partial results in fleet operations, 10MB SSH output cap, and shelley_upgrade limitation.

2026.08.21.2Aug 22, 2026

2026.08.21.2

Changed: exe.dev API request failures (network errors, DNS failures, connection resets) now raise an error that names the exe.dev command that was being attempted, instead of surfacing the raw fetch error with no context. The timeout error message also now includes the command that timed out. A malformed/non-JSON response from the exe.dev API now raises a clear "returned malformed JSON for command ..." error (including a snippet of the raw response) instead of a bare JSON.parse SyntaxError.

2026.08.21.1

Changed: Added .describe() documentation to every previously undocumented field in the resource schemas (SharingSchema, VmSchema, FleetSchema, StatSchema, ExecResultSchema, ShelleyVersionSchema, ShelleyVersionsSchema, ShelleyUpgradeResultSchema, and the inline shelleyUpgrade resource schema). No behavioral change — method argument schemas were already fully documented and are untouched.

2026.08.04.1

Added: Initial release of the exe.dev VM lifecycle model. Methods: setup, sync, create, destroy, restart, resize, stat, tag, exec, comment, share, shelley_versions, shelley_upgrade. Full fleet observation with typed resources, pre-flight existence checks on destructive operations, and actionable 403 diagnostics guiding token permission fixes.

2026.08.21.1Aug 21, 2026

2026.08.21.1

2026.08.04.1

2026.08.04.1Aug 4, 2026

2026.08.04.1

05Stats

100 / 100

Downloads

Archive size

28.0 KB

Has README or module doc2/2earned
README has a code example1/1earned
README is substantive1/1earned
Most symbols documented1/1earned
No slow types (deprecated)1/1earned
Dependencies pass trust audit2/2earned
Has description1/1earned
Platform support declared (or universal)2/2earned
License declared1/1earned
Verified public repository2/2earned

Repository

https://github.com/webframp/swamp-extensions

06Platforms

linux · x86_64 linux · aarch64 macOS · x86_64 macOS · aarch64

07Labels

#exe-dev #vm #cloud #infrastructure #ssh