# Tireless API Tireless provides cloud dev computers: ready-to-use virtual servers in the cloud for building with AI coding agents. This document is the complete, self-contained reference for the Tireless HTTP API — the dashboard's day-to-day surface (virtual servers, tools, ports, monitoring, marketplace browsing) over plain HTTPS. - Canonical URL of this document: https://tirelesscode.com/docs/api.md - Human-readable version: https://tirelesscode.com/docs/api - Last updated: 2026-07-20 - Base URL: https://app.tirelesscode.com/api - Authentication: send `Authorization: Bearer tl_...` with every request — an API key minted at https://app.tirelesscode.com/dashboard/api - Naming: the dashboard calls your computer a virtual server; the API's resource name for a virtual server is `workspace`. That is why every path says `/workspaces`. - All requests and responses are ordinary JSON over HTTPS. ## Getting started 1. **Create a key.** On the dashboard API page, create a key. It starts with tl_ and is shown exactly once — store it like a password. You can revoke it there at any time. 2. **Send it with every request.** Put the key in an Authorization header: Bearer tl_… — that is the only authentication step. There are no OAuth dances or signing schemes. 3. **Speak JSON to one base URL.** Every endpoint lives under https://app.tirelesscode.com/api. Requests and responses are ordinary JSON over HTTPS. ## Authentication Create your first key on the dashboard API page: https://app.tirelesscode.com/dashboard/api. Keys start with `tl_` and are shown exactly once. **Quick start — list your virtual servers** ```bash curl https://app.tirelesscode.com/api/workspaces \ -H "Authorization: Bearer tl_YOUR_KEY" ``` A 200 response with a `workspaces` array means your key works. ## Endpoint reference These are the calls day-to-day scripts and agents actually make — drawn from the same allow-list the agent connector uses. Every request needs the `Authorization` header, and `{id}` is a virtual server's UUID from the list endpoint. ## Virtual servers - `GET /api/workspaces` — List every virtual server you can access, with state and health. - `POST /api/workspaces` — Create a virtual server. Returns a checkout link when the size is not covered by a subscription yet. - `GET /api/workspaces/{id}` — Full detail for one virtual server: state, detected ports, links, and the latest heartbeat. - `POST /api/workspaces/{id}/actions` — Restart, pause (action name “suspend”), or resume a virtual server. Resizing is dashboard-only — keys get a 403. ## Ports & sharing - `POST /api/workspaces/{id}/shares` — Turn public sharing of an HTTP port on or off. - `POST /api/workspaces/{id}/exposures` — Open or close the game server port (allow-listed TCP ports only). - `GET /api/me/exposures` — Everything currently open to the internet, across all your virtual servers. ## Tools & installs - `GET /api/recipes` — The catalog of tools Tireless can install, with parameters and requirements. - `GET /api/workspaces/{id}/installs` — Installs on one virtual server, newest first. Secret parameters come back masked. - `POST /api/workspaces/{id}/installs` — Install a tool from the catalog on a running virtual server. - `POST /api/workspaces/{id}/installs/{installId}/cancel` — Cancel a queued or running install. - `POST /api/workspaces/{id}/installs/{installId}/uninstall` — Uninstall a tool that supports uninstalling. - `GET /api/workspaces/{id}/installs/{installId}/log` — The tail of an install’s log output. ## Marketplace Browsing is fully available over the API. Renting a listing completes in the browser. - `GET /api/marketplace/listings` — Browse every published Marketplace listing. - `GET /api/marketplace/listings/{slug}` — One listing in full: description, included tools, sizes, and media. ## Files - `POST /api/workspaces/{id}/files/list` — List directories on the virtual server. Send an etag per directory to skip unchanged ones. - `POST /api/workspaces/{id}/files/mkdir` — Create a folder. - `POST /api/workspaces/{id}/files/rename` — Move or rename a file or folder. - `POST /api/workspaces/{id}/files/delete` — Delete a file or folder (recursive deletes must be explicit). - `POST /api/workspaces/{id}/files/uploads` — Request pre-signed upload URLs for a batch of files. - `POST /api/workspaces/{id}/files/uploads/{sessionId}/complete` — Finish an upload session so the files land on the server. ## Monitoring - `GET /api/workspaces/{id}/health` — The current health score, the bottleneck, and a recommendation. - `GET /api/workspaces/{id}/metrics` — CPU, memory, disk, and network history (?range=24h or 7d). - `GET /api/workspaces/{id}/heartbeats` — Fine-grained resource samples from the last three hours. - `GET /api/workspaces/{id}/backups` — Recent backups with sizes and expiry dates. - `GET /api/workspaces/{id}/events` — The audit trail: what happened on the server and who did it. - `GET /api/workspaces/{id}/stream` — Server-sent events — a live stream that emits on every state change. - `GET /api/events` — Account-wide server-sent events — one stream that emits whenever any of your virtual servers changes state. - `POST /api/workspaces/{id}/connect` — Optional telemetry ping that records a client connecting to the server. ## Account & context - `GET /api/me/entitlements` — What your subscription allows you to create right now. - `GET /api/me/ssh-keys` — Your SSH public keys — read-only. Adding or removing keys happens in the dashboard. - `GET /api/me/ssh-setup` — Ready-made SSH and editor connection commands for every region. - `GET /api/plans` — Available computer sizes and their specs. - `GET /api/regions` — Active regions and the sizes they support. ## Worked examples ### List virtual servers The response includes every virtual server your account can access, each with its current state and latest health score. **Request** ```bash curl https://app.tirelesscode.com/api/workspaces \ -H "Authorization: Bearer tl_YOUR_KEY" ``` **Response — 200 (abridged)** ```json { "workspaces": [ { "id": "0b6f3d2e-8a41-4c2f-9d15-6e7a1b2c3d4e", "name": "side-project", "regionId": "eu-central", "planId": "pro", "desiredState": "ready", "observedState": "ready", "health": { "score": 92, "band": "healthy" }, "ownerName": "Ada" } ] } ``` ### Create a virtual server Name, region, and size are required. When the size is already covered by a subscription the build is queued immediately; otherwise the response carries a checkoutUrl to complete in the browser. **Request** ```bash curl -X POST https://app.tirelesscode.com/api/workspaces \ -H "Authorization: Bearer tl_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"name": "side-project", "region_id": "eu-central", "tier": "starter"}' ``` **Response — 201 (abridged)** ```json { "workspace": { "id": "0b6f3d2e-8a41-4c2f-9d15-6e7a1b2c3d4e", "name": "side-project", "desiredState": "ready", "observedState": "requested" }, "enqueued": true, "jobId": "a3d51c77-4b2e-4f8a-9c60-1e2f3a4b5c6d" } ``` ### Restart a virtual server Lifecycle changes go through the actions endpoint. The same call with “suspend” pauses the server and “resume” wakes it. Resizing changes what you pay, so it stays in the dashboard — the API answers 403. **Request** ```bash curl -X POST https://app.tirelesscode.com/api/workspaces/{id}/actions \ -H "Authorization: Bearer tl_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"action": "restart"}' ``` **Response — 200** ```json { "ok": true, "desiredState": "ready", "jobId": "f9e8d7c6-b5a4-4321-9876-543210fedcba" } ``` ### Install a tool Pick a recipe id from the catalog and install it on a running server. Watch the install’s status flip from queued to succeeded via the installs list or the log endpoint. **Request** ```bash curl -X POST https://app.tirelesscode.com/api/workspaces/{id}/installs \ -H "Authorization: Bearer tl_YOUR_KEY" \ -H "Content-Type: application/json" \ -d '{"recipe_id": "google-chrome"}' ``` **Response — 201 (abridged)** ```json { "install": { "id": "7c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f", "recipeId": "google-chrome", "version": "1.0.0", "mode": "install", "status": "queued", "requestedAt": "2026-07-18T09:30:00.000Z" }, "revealedParams": {} } ``` ## What keys can't do Some things stay in the dashboard on purpose: a leaked key must not be able to spend your money or destroy your servers. A key can never charge your card, change what you pay — resizing included — delete a virtual server, or touch account security, SSH keys, or the keys themselves. Purchases and plan changes finish in the browser. These are dashboard-only, and the API answers 403 no matter what key you send: - Billing and subscriptions - Resizing virtual servers — it changes what you pay - Deleting virtual servers - Account security settings - Adding or removing SSH keys - Admin surfaces - Referrals and payouts - Managing API keys themselves ### Rate limits Mutating endpoints and sensitive reads are rate limited. When you exceed a limit, the API answers 429 with a `Retry-After` header telling you how long to wait. Defaults are generous for scripts — just don't design tight polling loops around mutations. ### Errors Every error has the same JSON shape: a stable machine-readable code, a human-readable message, and optional details. ```json { "error": "not_found", "message": "no such virtual server", "details": null } ``` ## AI agents (MCP) The Tireless agent connector is an MCP plugin for Claude Code that speaks this exact same API with the same permissions — nothing more. Whatever a key can do here, your agent can do from a chat. **Install the connector** ```bash claude plugin marketplace add Tireless-Coder/agent && claude plugin install tireless@tireless ``` **Every tool the MCP provides** ### Connect & diagnose - `tireless_connect_workspace` — Sets everything up end to end — helper app, sign-in, SSH, clipboard — and connects to a server. - `tireless_status` — Checks the connection: sign-in state, helper health, and your servers' states. - `tireless_login` — Signs in to Tireless — you approve once in your browser, no tokens in the chat. - `tireless_doctor` — Runs the full diagnostic chain and returns a concrete fix for each failure. - `tireless_clipboard_status` — Checks the image-paste bridge between this computer and your server. ### Your virtual servers - `tireless_list_workspaces` — Lists your virtual servers with plan and running state. - `tireless_get_workspace` — Full detail for one server: state, deep links, detected ports and shares. - `tireless_workspace_action` — Restarts, pauses, or resumes a server. Deleting is dashboard-only. - `tireless_create_workspace` — Creates a new server — always shows the plan and price first, and only proceeds after you approve. - `tireless_watch_state` — Waits until a server reaches a state (usually ready), reporting progress. - `tireless_workspace_health` — Health score plus CPU, memory, disk, and network charts for the last day or week. ### Open & share - `tireless_open_editor` — Opens a server in Claude Code, VS Code, Cursor, or the browser terminal and desktop. - `tireless_share_port` — Makes a dev-server port publicly previewable — or takes the preview offline again. - `tireless_game_port` — Opens or closes a raw game-server port to the internet (like Minecraft's 25565). - `tireless_exposure_overview` — Everything of yours that's reachable from the internet right now, in one view. ### Apps & marketplace - `tireless_recipes_catalog` — Browses the catalog of apps that can be installed on a server. - `tireless_install_app` — Installs an app on a server, handing you any generated passwords right away. - `tireless_install_status` — Install history for a server, with the log tail for any single install. - `tireless_marketplace_browse` — Browses marketplace listings. Renting happens on the dashboard, never from the agent. - `tireless_marketplace_listing` — Full detail for one marketplace listing — tiers, prices, included tools. The connector is open source: https://github.com/Tireless-Coder/agent Tireless is an independent product and is not affiliated with or endorsed by Anthropic. ## FAQ ### Do API keys expire? No. A key stays valid until you revoke it on the dashboard API page. Revoking takes effect immediately. ### What can an API key access? Your account, with the same permissions as the agent connector: virtual servers, ports, tools, files, monitoring, and Marketplace browsing. It can never charge your card, change what you pay, delete a virtual server, or alter account security — purchases and plan changes finish in the browser. ### I lost my key. Can I see it again? No. The full key is shown exactly once, when you create it. If you lose it, revoke it on the dashboard and create a new one. ### Can I rent Marketplace servers through the API? Browsing, yes — every published listing is readable over the API. Renting is browser-only: a key cannot start or complete a checkout. ### Is there an SDK? Not yet — the API is plain HTTPS and JSON on purpose, so any language with an HTTP client already works. The curl examples on this page translate directly. ### How many keys can I create? Up to 20 per account. Use a separate key per script or machine, so you can revoke one without breaking the rest. --- Note for AI agents: this document is the canonical machine-readable reference for the Tireless API. The human version lives at https://tirelesscode.com/docs/api.