DOCS / API & CLI

API & CLI access

Programmatic access lets you automate fleets of sessions — for CI runners, browser-automation farms, security training labs, dynamic dev environments, anything that benefits from spinning up and tearing down VMs from code. This page is the design + roadmap; the actual API isn't live yet.

Status: design phase. We're shipping API + CLI in v1.1 once core dashboard features stabilize. Want early access? Email us.

REST API

A JSON-over-HTTPS API at https://api.deskboot.store/v1/. Authenticated via personal access tokens (PATs) you'll generate in /dashboard/settings/api-tokens.

Authentication

Authorization: Bearer rs_pat_<your-token>

Tokens are scoped (read-only / sessions / billing / admin) and revocable. Lost tokens can't be recovered — rotate. We'll log every API call to your audit trail.

Endpoints (planned)

Method	Path	Description
GET	/v1/sessions	List your sessions
POST	/v1/sessions	Launch a session
GET	/v1/sessions/:id	Session detail
POST	/v1/sessions/:id/start	Start a stopped session
POST	/v1/sessions/:id/stop	Stop a running session
POST	/v1/sessions/:id/reboot	Reboot
DELETE	/v1/sessions/:id	Terminate
GET	/v1/sessions/:id/credentials	Decrypt password (view-once)
GET	/v1/sessions/:id/rdp	Download .rdp
GET	/v1/sessions/:id/ssh-key	Download SSH private key
GET	/v1/sessions/:id/rules	List firewall rules
POST	/v1/sessions/:id/rules	Open a port
DELETE	/v1/sessions/:id/rules/:ruleId	Close a port
GET	/v1/elastic-ips	List Elastic IPs
POST	/v1/elastic-ips	Allocate ($5)
POST	/v1/elastic-ips/:id/attach	Attach to a session
POST	/v1/elastic-ips/:id/detach	Detach
DELETE	/v1/elastic-ips/:id	Release
GET	/v1/balance	Current balance + recent transactions
POST	/v1/balance/topup	Initiate a top-up
GET	/v1/account	Account info, trust level

Example: launch a session

POST /v1/sessions
Authorization: Bearer rs_pat_abc123
Content-Type: application/json

{
  "os": "ubuntu-24-04",
  "size": "standard",
  "region": "us-east-1",
  "linuxUsername": "ci",
  "elasticIp": { "kind": "none" }
}

→ 201 Created
{
  "id": "cmp...",
  "status": "PROVISIONING",
  "createdAt": "2026-05-25T12:34:56Z"
}

Rate limits & quotas

Default: 60 requests/min per token, 1000/hour
Mutating endpoints (POST/DELETE) limited to 30/min
Max 50 concurrent sessions per account (raise via support)
Standard 429 response with Retry-After header

Webhooks

Configure HTTPS endpoints to receive events like session.running, session.terminated, balance.low, balance.exhausted. HMAC-signed with your webhook secret.

CLI (deskboot)

Thin wrapper over the REST API. One binary, native to your platform. Install via Homebrew/Scoop/curl. Stores your PAT in your OS keychain.

Install (planned)

# macOS / Linux (Homebrew)
brew install deskboot

# Windows (Scoop)
scoop install deskboot

# Or any platform (curl)
curl -fsSL https://get.deskboot.store | sh

Common commands

deskboot login                                     # opens browser to authorize

deskboot session launch \
  --os ubuntu-24-04 \
  --size standard \
  --region us-east-1 \
  --eip auto                                           # allocate + attach a fresh EIP

deskboot session list
deskboot session stop  <id>
deskboot session start <id>
deskboot session terminate <id>

deskboot ssh <id>                                  # opens an SSH session using the stored key
deskboot rdp <id>                                  # opens your local RDP client with the .rdp

deskboot port open 8080 --to 0.0.0.0/0 <id>        # open a custom port
deskboot port close 8080 <id>

deskboot balance                                   # show balance + recent transactions
deskboot balance topup --amount 25

Use cases we're building for

CI runners: ephemeral Windows builders for cross-platform CI
Browser farms: scripted Chrome instances for scraping or testing
Training labs: spin up N identical sessions for a class, terminate at end
Pen-test engagements: ephemeral Kali sessions with fresh IPs per target
Disposable dev envs: full IDE in a session per branch/PR

Want this sooner?

We're prioritizing API + CLI based on early-access interest. Email us with your use case to get a heads-up when v1.1 lands.