Exe Dev/vm
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 sync2026.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.
Global Arguments
| Argument | Type | Description |
|---|---|---|
| token? | string | exe.dev API bearer token. Supply it with a vault expression, e.g. |
| Argument | Type | Description |
|---|---|---|
| expiry? | string | Token lifetime (e.g. 7d, 30d, 90d) |
| vaultName? | string | Vault to store the token in. Defaults to "gitlab" for backward |
| secretKey? | string | Secret key name within the vault. Defaults to "exe-dev-api-token" |
| Argument | Type | Description |
|---|---|---|
| name? | string | VM name (auto-generated if omitted) |
| image? | string | Container image (e.g. ubuntu:22.04) |
| cpu? | number | Number of CPUs (default 2) |
| memory? | string | Memory allocation (e.g. 4GB, 8G) |
| disk? | string | Disk size (e.g. 20GB, 50G) |
| tags? | array | Tags to apply |
| comment? | string | Short comment about the VM (max 200 bytes) |
| setupScript? | string | Setup script to run on first boot (max 10KiB) |
| env? | record | Environment variables as KEY=VALUE pairs. Supply secret values |
| integrations? | array | Integration names to attach |
| Argument | Type | Description |
|---|---|---|
| names | array | VM name(s) to delete |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name to restart |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name to resize |
| cpu? | number | New CPU count |
| memory? | string | New memory (e.g. 8GB) |
| disk? | string | New disk size (must be larger than current) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| range? | enum | Time range for metrics |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| add? | array | Tags to add |
| remove? | array | Tags to remove |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name to execute on |
| command | string | Shell command to run (max 64KB) |
| timeout? | number | SSH command timeout in seconds (max 300) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| text | string | Comment text (empty string to clear) |
| Argument | Type | Description |
|---|---|---|
| name | string | VM name |
| action | enum | Sharing action to perform |
| email? | string | Email address (required for add/remove actions) |
| linkToken? | string | Share link token (required for remove-link) |
| root? | boolean | Grant/revoke shell (SSH) access instead of web-only (for add/remove) |
| Argument | Type | Description |
|---|---|---|
| filter? | array | VM names to check (default: all VMs from latest fleet sync) |
| Argument | Type | Description |
|---|---|---|
| names? | array | VM names to upgrade. Default: all VMs where shelley_versions |
Resources
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.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.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
Upgrade note: Normalized npm:zod dependency version to 4.6.5 across the
repo. No behavioral changes in this extension.
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
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
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
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
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
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
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
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
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.
- 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