Skip to main content

Exe Dev/vm

@webframp/exe-dev/vmv2026.11.03.1· Apache-2.0· 17d agoBEHAVIORS
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, then reference it with a vault.get expression. Never pass the literal token.

Quick Start

swamp extension pull @webframp/exe-dev/vm
swamp vault create local_encryption exe-dev   # once, if you have no vault yet
swamp model create @webframp/exe-dev/vm exe-dev
swamp model method run exe-dev setup \
  --input vaultName=exe-dev --input secretKey=API_TOKEN
# Then `swamp model edit exe-dev` and set:
#   token: ${{ vault.get("exe-dev", "API_TOKEN") }}
swamp model method run exe-dev sync
02Release Notes

2026.11.03.1

Changed: Bump zod 4.6.5 → 4.6.7

2026.10.22.1

Fixed: Existing definitions created against an earlier version were stranded on upgrade. The model shipped new versions without a corresponding upgrades chain, so swamp could not migrate a definition's typeVersion and logged a warning that global arguments would not be migrated. This release backfills the full upgrade chain through every shipped version and terminates it at the current version, so stale definitions migrate cleanly. The transform is identity — no stored global argument value changes.

Changed: The chain records that the token global argument became sensitive at 2026.10.21.1. This is a schema attribute, not a stored-value change, so the identity transform carries the existing token reference forward unchanged.

Upgrade note: No action required. On the next method run, each existing definition's typeVersion advances to 2026.10.22.1 with its global arguments preserved.

2026.10.21.1

Fixed: setup failed to store the generated token with current swamp releases, because it passed an unsupported --stdin flag to swamp vault put. The token is still piped on stdin, never on argv.

Fixed: setup error messages could echo the raw ssh exe.dev ssh-key generate-api-key output, which may contain the token. They now withhold the output, use stderr only on an ssh failure, and mask anything token-shaped.

Changed: The token global argument is marked sensitive, so swamp rejects a literal token and redacts the value. Supply it with ${{ vault.get("exe-dev", "API_TOKEN") }} (or your own vault and key).

Changed: README and manifest show the vault flow: create a vault, run setup with --input vaultName=… --input secretKey=…, then wire token with vault.get. The manual alternative pipes only the first generated token straight into swamp vault put --yes, so re-running it rotates the stored value. The setup defaults are unchanged (vault gitlab, key exe-dev-api-token); its argument descriptions, the missing-token error and the README now state them and recommend passing both inputs explicitly. The env argument of create now says to pass secret values as vault.get expressions.

Upgrade note: A model whose token is a literal string now fails validation. Store the token with setup (or swamp vault put) and replace it with a vault.get expression.

03Behaviors1
@webframp/exe-dev/vmv2026.11.03.1exe-dev/vm.ts

Global Arguments

ArgumentTypeDescription
token?stringexe.dev API bearer token. Supply it with a vault expression, e.g.
fn setup(expiry?: string, vaultName?: string, secretKey?: string)
Generate a fully-permissioned exe.dev API token and store it in the
ArgumentTypeDescription
expiry?stringToken lifetime (e.g. 7d, 30d, 90d)
vaultName?stringVault to store the token in. Defaults to "gitlab" for backward
secretKey?stringSecret key name within the vault. Defaults to "exe-dev-api-token"
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.
ArgumentTypeDescription
name?stringVM name (auto-generated if omitted)
image?stringContainer image (e.g. ubuntu:22.04)
cpu?numberNumber of CPUs (default 2)
memory?stringMemory allocation (e.g. 4GB, 8G)
disk?stringDisk size (e.g. 20GB, 50G)
tags?arrayTags to apply
comment?stringShort comment about the VM (max 200 bytes)
setupScript?stringSetup script to run on first boot (max 10KiB)
env?recordEnvironment variables as KEY=VALUE pairs. Supply secret values
integrations?arrayIntegration names to attach
fn destroy(names: array)
Delete one or more exe.dev VMs by name.
ArgumentTypeDescription
namesarrayVM name(s) to delete
fn restart(name: string)
Restart an exe.dev VM.
ArgumentTypeDescription
namestringVM name to restart
fn resize(name: string, cpu?: number, memory?: string, disk?: string)
Resize a VM's CPU, memory, or disk.
ArgumentTypeDescription
namestringVM name to resize
cpu?numberNew CPU count
memory?stringNew memory (e.g. 8GB)
disk?stringNew disk size (must be larger than current)
fn stat(name: string, range?: enum)
Fetch CPU, memory, disk, and IO metrics for a VM.
ArgumentTypeDescription
namestringVM name
range?enumTime range for metrics
fn tag(name: string, add?: array, remove?: array)
Add or remove tags on a VM.
ArgumentTypeDescription
namestringVM name
add?arrayTags to add
remove?arrayTags to remove
fn exec(name: string, command: string, timeout?: number)
Execute a shell command on a VM via SSH. Stores the output as
ArgumentTypeDescription
namestringVM name to execute on
commandstringShell command to run (max 64KB)
timeout?numberSSH command timeout in seconds (max 300)
fn comment(name: string, text: string)
Set or clear a short comment on a VM (max 200 bytes).
ArgumentTypeDescription
namestringVM name
textstringComment 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,
ArgumentTypeDescription
namestringVM name
actionenumSharing action to perform
email?stringEmail address (required for add/remove actions)
linkToken?stringShare link token (required for remove-link)
root?booleanGrant/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
ArgumentTypeDescription
filter?arrayVM 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
ArgumentTypeDescription
names?arrayVM 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 Versions13
2026.10.22.1Apache-2.0

2026.10.22.1

Fixed: Existing definitions created against an earlier version were stranded on upgrade. The model shipped new versions without a corresponding upgrades chain, so swamp could not migrate a definition's typeVersion and logged a warning that global arguments would not be migrated. This release backfills the full upgrade chain through every shipped version and terminates it at the current version, so stale definitions migrate cleanly. The transform is identity — no stored global argument value changes.

Changed: The chain records that the token global argument became sensitive at 2026.10.21.1. This is a schema attribute, not a stored-value change, so the identity transform carries the existing token reference forward unchanged.

Upgrade note: No action required. On the next method run, each existing definition's typeVersion advances to 2026.10.22.1 with its global arguments preserved.

2026.10.21.1

Fixed: setup failed to store the generated token with current swamp releases, because it passed an unsupported --stdin flag to swamp vault put. The token is still piped on stdin, never on argv.

Fixed: setup error messages could echo the raw ssh exe.dev ssh-key generate-api-key output, which may contain the token. They now withhold the output, use stderr only on an ssh failure, and mask anything token-shaped.

Changed: The token global argument is marked sensitive, so swamp rejects a literal token and redacts the value. Supply it with ${{ vault.get("exe-dev", "API_TOKEN") }} (or your own vault and key).

Changed: README and manifest show the vault flow: create a vault, run setup with --input vaultName=… --input secretKey=…, then wire token with vault.get. The manual alternative pipes only the first generated token straight into swamp vault put --yes, so re-running it rotates the stored value. The setup defaults are unchanged (vault gitlab, key exe-dev-api-token); its argument descriptions, the missing-token error and the README now state them and recommend passing both inputs explicitly. The env argument of create now says to pass secret values as vault.get expressions.

Upgrade note: A model whose token is a literal string now fails validation. Store the token with setup (or swamp vault put) and replace it with a vault.get expression.

2026.10.21.1Apache-2.0

2026.10.21.1

Fixed: setup failed to store the generated token with current swamp releases, because it passed an unsupported --stdin flag to swamp vault put. The token is still piped on stdin, never on argv.

Fixed: setup error messages could echo the raw ssh exe.dev ssh-key generate-api-key output, which may contain the token. They now withhold the output, use stderr only on an ssh failure, and mask anything token-shaped.

Changed: The token global argument is marked sensitive, so swamp rejects a literal token and redacts the value. Supply it with ${{ vault.get("exe-dev", "API_TOKEN") }} (or your own vault and key).

Changed: README and manifest show the vault flow: create a vault, run setup with --input vaultName=… --input secretKey=…, then wire token with vault.get. The manual alternative pipes only the first generated token straight into swamp vault put --yes, so re-running it rotates the stored value. The setup defaults are unchanged (vault gitlab, key exe-dev-api-token); its argument descriptions, the missing-token error and the README now state them and recommend passing both inputs explicitly. The env argument of create now says to pass secret values as vault.get expressions.

Upgrade note: A model whose token is a literal string now fails validation. Store the token with setup (or swamp vault put) and replace it with a vault.get expression.

2026.10.14.1Apache-2.0(was none)

2026.10.14.1

Added: The manifest now declares license: Apache-2.0 (SPDX). The registry quality rubric scores a declared license separately from the bundled LICENSE.md.

Upgrade note: Metadata only. No code, schema, or behavioral changes.

2026.09.18.1

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

2026.09.18.1

2026.09.18.1

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

2026.09.15.1

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.1

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.26.3

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.26.1

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.2

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.1

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.2

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.1

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.04.1

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.

05Stats
A
100 / 100
Downloads
138
Archive size
30.5 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
  • Docs keep secrets in a vault1/1earned
  • Has description1/1earned
  • Platform support declared (or universal)2/2earned
  • License2/2earned
  • Verified public repository2/2earned
06Platforms
07Labels