Skip to main content
← back to extensions

Cherry Servers

@randybias/cherry-serversv2026.10.16.3beta· 15d agoBEHAVIORSWORKFLOWSACCEPTED WARNINGS
01README

Order, inspect, wait for and delete Cherry Servers bare-metal and VPS servers, with their projects, SSH keys and live plan stock. One model type per API resource; a server is ready only when the API reports it deployed and it answers SSH with the expected host keys.

02Release Notes

Fixes: the wait-ready and delete workflows did not work in 2026.10.16.1 or 2026.10.16.2 (they read definition inputs that were never set); upgrade to this version before using them. Every delete (server, SSH key, project) is now an action, so deleting one record no longer marks every record of a shared definition as deleted. On bare metal, wait_ready now waits until the API reports the server deployed and active, because the public IP and host keys can change during deploy; read the address from state after wait_ready, never from create. New: project delete (refuses a project that still holds servers); the create workflow takes os_partition_size, spot_market, tags, and vault key names for user data and the marker-check key. Security: pass ssh_private_key and user_data as vault references only; the swamp CLI currently prints literal sensitive arguments, including from --stdin (swamp-club lab 3555). Every method and both workflows were run live end to end on VPS and bare metal; the annually billing cycle was not.

03Behaviors4
@randybias/cherry-servers/serversv2026.10.16.3servers.ts
fn create()
Order the server, or adopt an existing one with the same hostname in the project. Idempotent: a re-run never places a second order. Returns as soon as the order is accepted; use wait_ready to wait for SSH.
fn get(id: number)
READ-ONLY. Fetch a server by ID and store its state. Fails if the server does not exist.
ArgumentTypeDescription
idnumberServer ID.
fn sync()
READ-ONLY. Refresh stored state from the API; records status not_found instead of failing when the server is gone.
fn list()
READ-ONLY. List every server in the project and store one state record per hostname.
fn wait_ready(host_key_policy: enum, known_hosts?: string, port?: number, marker_path?: string, ssh_user?: string, ssh_private_key?: string, timeout_seconds?: number, poll_interval_seconds?: number)
Wait until the API reports the server deployed and active, it answers SSH on that address with acceptable host keys and, if marker_path is set, the marker file exists. The API alone is not trusted (it can report active before setup finishes) and neither is SSH alone (during deploy it can be the provisioning environment, and the address can still change). Stores readiness evidence.
ArgumentTypeDescription
host_key_policyenumstrict: keys must match known_hosts; accept-new: trust on first use, then enforce the recorded keys; insecure: record without enforcing.
known_hosts?stringExpected host keys in known_hosts or ssh-keyscan format; required for strict.
port?numberSSH port.
marker_path?stringAbsolute path of a file whose existence marks first-boot setup as finished.
ssh_user?stringUser for the marker check.
ssh_private_key?stringPrivate key for the marker check, loaded into a temporary ssh-agent over stdin.
timeout_seconds?numberGive up after this many seconds.
poll_interval_seconds?numberSeconds between polls.
fn delete(id?: number, confirm_hostname: string)
DESTRUCTIVE. Delete this model's recorded server and confirm the API no longer returns it. Refuses unless the live server's hostname and its recorded project both match, and refuses an id other than the recorded one; an already-deleted recorded server is stored as not_found.
ArgumentTypeDescription
id?numberServer ID; defaults to the recorded server and must match it when both exist.
confirm_hostnamestringMust equal the server's hostname; guards against deleting the wrong server.

Resources

state(infinite)— Server state: id, addresses, status, plan and billing cycle
readiness(infinite)— Evidence that the server answers SSH, with its host keys
@randybias/cherry-servers/projectsv2026.10.16.3projects.ts
fn create()
Create the project, or adopt an existing one in the team with the same name. Idempotent. Fails if several projects share the name.
fn get(id: number)
READ-ONLY. Fetch a project by ID and store its state.
ArgumentTypeDescription
idnumberProject ID.
fn sync()
READ-ONLY. Refresh stored state; records not_found instead of failing when the project is gone.
fn list()
READ-ONLY. List every project in the team and store one state record per name.
fn delete(id?: number, confirm_name: string)
DESTRUCTIVE. Delete this model's recorded project and confirm the API no longer returns it. Refuses unless the live project's name matches and it holds no servers, and refuses an id other than the recorded one; an already-deleted recorded project is stored as not_found.
ArgumentTypeDescription
id?numberProject ID; defaults to the recorded project and must match it when both exist.
confirm_namestringMust equal the project's name.

Resources

state(infinite)— Project id and name
@randybias/cherry-servers/ssh-keysv2026.10.16.3ssh_keys.ts
fn create()
Upload the key, or adopt an existing key with the same material. Idempotent. Fails if the label is used by a different key.
fn sync()
READ-ONLY. Refresh stored state; records not_found instead of failing when the key is gone.
fn list()
READ-ONLY. List every SSH key on the account and store one record per label.
fn delete(id?: number, confirm_label: string)
DESTRUCTIVE. Delete this model's recorded key after checking its label matches, and refuse an id other than the recorded one; an already-deleted recorded key is stored as not_found.
ArgumentTypeDescription
id?numberSSH key ID; defaults to the recorded key and must match it when both exist.
confirm_labelstringMust equal the key's label.

Resources

state(infinite)— SSH key id, label and fingerprint
@randybias/cherry-servers/plansv2026.10.16.3plans.ts
fn list(type?: enum, region?: string, min_ram_gb?: number, max_hourly_price?: number, in_stock_only?: boolean)
READ-ONLY. Fetch plans with live stock, filter them, and store one record per matching plan, cheapest hourly first. Stock is a snapshot.
ArgumentTypeDescription
type?enumOnly plans of this type.
region?stringOnly consider stock in this region.
min_ram_gb?numberMinimum RAM in GB.
max_hourly_price?numberMaximum hourly price, in the listed currency.
in_stock_only?booleanDrop plans with no stock (in the region, if given).

Resources

plan(1d)— A plan's specs, prices per billing unit and stock per region
04Workflows2
@randybias/cherry-servers-create-serverf2244add-07a2-4285-9cb6-260073f790ea

Order a server or adopt an existing one, then wait until SSH answers

provisionOrder the server and wait for it to answer SSH
1.create${{ inputs.server_model }}.create— Order or adopt the server via the Cherry Servers API
2.wait-ready${{ inputs.server_model }}.wait_ready— Wait for an SSH banner and acceptable host keys
@randybias/cherry-servers-delete-server51317e42-18f5-45bb-9f9c-6fb03973c383

Delete a model's recorded server after checking its hostname and project match

teardownRefresh state, then delete the server and confirm it is gone
1.sync${{ inputs.server_model }}.sync— Refresh stored server state from the API
2.delete${{ inputs.server_model }}.delete— Delete the server and confirm the API returns 404
05Previous Versions2
2026.10.16.2
2026.10.16.1

First release (beta). Servers, projects, SSH keys and plan stock for Cherry Servers; create adopts instead of re-ordering; readiness judged by SSH. Live-tested: list calls, create, wait_ready, adopt on re-run. Not yet live-tested: delete.

06Stats
A
93 / 100
Downloads
2
Archive size
46.6 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
  • License1/2partial

    no SPDX license declared

  • Verified public repository2/2earned
Repository
https://github.com/randybias/swamp-extensions

08Platforms
09Labels
#cherry-servers#bare-metal#vps#cloud#infrastructure#provisioning