Instances Flows

The Instances view is the operational dashboard for deployments that were created from constitutions.

Page and Data Source

Route: /instances
Server query: loads deployments for the current user where status is not DESTROYED.
Includes linked constitution title and id for quick navigation.

Status Flow

Instance cards display these lifecycle states:

PROVISIONING — Droplet creation in progress.
CONFIGURING — Cloud-init installation and readiness checks in progress.
ACTIVE — Ready for desktop launch.
ERROR — Provisioning/configuration failed.
DESTROYING — Reserved status in enum (not currently emitted by destroy route).

DESTROYED records are excluded from the page.

Access Flow (Active Instances)

Open Desktop links to GET /api/deployments/[id]/launch.
Launch route enforces ownership and ACTIVE status, then redirects with a short-lived secure token.
Direct IP button appears when a gateway host is configured and uses /api/deployments/[id]/launch?target=ip.

Destroy Flow

Click Destroy on an instance card.
Confirm in the dialog.
Client sends DELETE /api/deployments/[id].
Server attempts to destroy the DigitalOcean droplet, then marks the deployment as DESTROYED.
The page refreshes and removes the card from the list.

Polling and State Transitions

Deployment status updates are handled by GET /api/deployments/[id]:

PROVISIONING transitions to CONFIGURING when the droplet becomes active and has a public IP.
CONFIGURING transitions to ACTIVE when https://[ip]/guacamole/ is reachable.
Instance progress UI polls every 5 seconds and requests a page refresh when status becomes terminal.

Troubleshooting Notes

Active actions appearing late is typically poll cadence (up to ~5s delay).
If launch returns 409 Deployment is not ready yet, wait for status to settle on ACTIVE.
If launch returns 500 Deployment credentials are unavailable, confirm deployment has both public IP and VNC password metadata.

Related Pages