REST API
Call the Subshell REST API from an external integration.
Before you start
Use the server's reachable address and an appropriate credential. Review API keys before assuming a system key can access a human-owned session.
Discover the interface
Open /docs on the running server to inspect the generated OpenAPI documentation. Route schemas describe current request bodies and response shapes; prefer them over guessing from a browser screenshot.
For an agent or local tool, fetch /openapi.json from the same server. It returns the live schema without requiring a login or an external documentation service. The previous /docs/json URL redirects there. The schema defines bearer authentication, request bodies, response shapes, and the x-api-key-permission grant required by each operation available to scoped keys.
curl --fail-with-body "$SUBSHELL_URL/openapi.json" -o subshell-openapi.jsonResource families include subshells, workspaces, presets, prompts, nodes, channels, and devices. Administrative families have additional cookie-only gates.
Send a bearer request
Set SUBSHELL_URL and SUBSHELL_API_KEY securely in the integration's runtime environment. These belong to your integration, rather than the server's config.env; Files and paths explains the configuration locations. Then send a request without printing the credential:
curl --fail-with-body \
-H "Authorization: Bearer $SUBSHELL_API_KEY" \
"$SUBSHELL_URL/api/subshells"This example needs subshells:read. The list is scoped to the authenticated identity. Empty results don't prove the instance contains no sessions.
Automate node enrollment
Ask an administrator to create a system API key with nodes:enroll, nodes:read, and nodes:directories selected under Settings → Server Settings → API keys. Set the environment variables described above, then:
-
Request a setup key. No request body is needed:
curl --fail-with-body -X POST \ -H "Authorization: Bearer $SUBSHELL_API_KEY" \ "$SUBSHELL_URL/api/nodes/setup-keys"The response contains
id,key, andexpiresAt. Treatkeyas a secret. Each setup key expires after 24 hours and can enroll one node; request a separate key for each machine. -
On the target machine, use the returned
keywith node setup:subshell setup --server https://server.example.com --key nsk_REPLACE_ME --name worker-01The node exchanges the setup key through
POST /api/nodes/enroll. That endpoint takes a setup key and the machine's public identity, not your system API key as an enrollment credential. Let the CLI generate and store that identity. -
Find the node through
GET /api/nodes. Alternatively,GET /api/nodes/setup-keysreturnsconsumedNodeIdfor the redeemed key. Configure it using the returned node ID:curl --fail-with-body -X PUT \ -H "Authorization: Bearer $SUBSHELL_API_KEY" \ -H "Content-Type: application/json" \ --data '{"dirs":["/srv/work"]}' \ "$SUBSHELL_URL/api/nodes/NODE_ID/allowed-dirs"Directory rules replace the entire list. An empty list removes the restriction. Read the node back with
GET /api/nodes/NODE_IDto check the saved configuration.
Use the live schema for the remaining configuration endpoints. Revoke an unused setup key with DELETE /api/nodes/setup-keys/KEY_ID. After a timeout, inspect the setup-key list before creating another key.
Terminal and channel operations
Terminal WebSockets use short-lived, single-use tokens obtained through the API. A bearer-minted token is bound to one subshell.
Channel posts carry encrypted envelopes and recipient data, not plaintext text. Use MCP when you want its built-in sealing, pinning, and decryption workflow.
Saved app services
Use these endpoints for services started outside a subshell. A virtual display isn't required; the subshell must be running to open the connection.
| Action | Endpoint | Body |
|---|---|---|
| List saved connections | GET /api/subshells/:id/services | None |
| Save a connection | POST /api/subshells/:id/services | port, protocol (http or https), optional name and host |
| Open a saved connection | POST /api/subshells/:id/views/open | { "serviceId": "saved-service-uuid" } |
| Remove a saved connection | DELETE /api/subshells/:id/services/:serviceId | None |
Host defaults to localhost on the subshell's node. HTTPS certificates must be
trusted by that node. Reading requires subshell view access; saving, opening,
and removing require edit access and subshells:execute for a scoped system key.
Pane credentials can access only their owner's subshells. Removing a saved
connection disconnects its open previews without stopping the service.
The returned proxyBase is a private access link: anyone holding it can use it
while it's valid. Keep it out of logs and public links.
See Web previews & screens for the UI flow.
Handle failures
Check both HTTP status and the structured response. After an ambiguous create timeout, inspect the list before retrying.
Next steps
Read Build an API integration and Access model.
Edit on GitHubLast updated on
