> ## Documentation Index > Fetch the complete documentation index at: https://cool.computer/docs/llms.txt > Use this file to discover all available pages before exploring further. # Run the computer's service > Saves and starts the computer's one long-running program, replacing any previous one, and keeps it running. The command is a shell line, as for exec. A program that exits with a failure or is killed after it was ready starts again after 1 s, doubling up to 60 s, and restarts counts it. With port, the program is ready once the port accepts connections, and then the computer's URL reaches it; without port (a bot or a worker), it is ready once it has stayed up 5 s, and the URL is unchanged. A program that ends before it is ready answers 409 with its exit and last stderr; one not ready after 60 seconds is kept, keeps starting in the background and answers 202. Install dependencies with a one-shot exec first: the command runs again on every restart. secrets names a secret set whose keys the program gets as environment variables when it starts, a key delivered by proxy as its stand-in; env adds plain values. On a site with no VM it gives the site its own VM first, which cannot be undone: its published files move to /home/runtime/app, and publishing to it stops. Once a port is exposed, the service answers every path but a site's functions (/api), and a site's files in /home/runtime/app are never served as files again, even after the port is removed. A later explicit exposure selection is independent of this process. Send an Idempotency-Key when a network failure might cause a retry. ## OpenAPI ````yaml https://www.cool.computer/openapi.json post /api/computers/{id}/service/run openapi: 3.1.0 info: title: Cool Computers API version: 1.0.0 description: >- Create and operate reachable computers. Each computer keeps a stable name.cool.computer address, persistent files, and agent-ready command execution. REST requests use UTC-aligned one-minute limits: 600 requests per account identified by a recognized valid account bearer credential, a separate 600-request budget per computer-scoped credential, or 60 requests per source IP otherwise. Read-only GETs answered from API state spend a separate read budget reported as account-read or computer-read, so status polling cannot exhaust the budget that protects work and mutations. To bound authentication-provider traffic, at most 60 first-seen bearer values are checked per source IP in a minute; recognized valid credentials use their account or computer policy. Successful bearer authentication is reused for at most five seconds; transient provider failures are not cached. Revoking a credential through this API (POST /api/auth/logout or DELETE /api/api-keys/{id}) drops that reuse in every serving process, so the revoked credential is refused from the next request on; only if that announcement fails does another process keep admitting it, for at most five seconds. JSON request bodies must be sent with Content-Type: application/json; any other body answers 415 unsupported_media_type. A request that gives a published site its own VM (POST /api/computers/{id}/vm, POST /api/computers/{id}/service/run, or a publish whose cool.json declares run) answers with a Cool-Notice header saying that the site now runs there and cool.json no longer applies; exec, terminals, the port proxy and exposure never give one and answer 409 needs_vm on a site with no VM. Every error is an application/problem+json object whose type links to https://cool.computer/docs/api-reference/errors; a malformed body names the unknown field, the wrong type, or the byte where the JSON breaks. Non-exempt API responses include the structured RateLimit and RateLimit-Policy fields; request admission 429 responses use code api_request_rate_exceeded and also include Retry-After. Health, OpenAPI, webhooks, callbacks, SSE, and WebSocket endpoints are exempt from the REST request budget. Authenticated SSE connection attempts remain subject to the authentication safeguards and can receive the same typed 429 response. servers: - url: https://api.cool.computer description: Canonical API origin security: [] tags: - name: Authentication description: Obtain and manage bearer credentials. - name: Billing description: Inspect and manage the account's no-card trial or Pro plan. - name: Computers description: Create, inspect, and delete resident computers. - name: Execution description: Run commands on a computer. - name: Files description: Read and change a computer's persistent files. - name: Publishing description: >- Publish files to a computer's URL as immutable releases, with no VM. To show something, publish the files; to run something, give the site its own VM with POST /api/computers/{id}/vm or start a service with POST /api/computers/{id}/service/run, then use exec, terminals and services. - name: Services description: >- Manage processes and select the HTTP port exposed at a computer's stable address. - name: Email description: Read and send mail through a computer's inbox. - name: Comments description: >- Comments people leave on a computer's page, unless its owner switched comments off: the owner, the people it is shared with and, when the computer is public, any signed-in person. A comment is content; the owner's agents (Operator, or any agent with the owner's credential) pull the open comments and answer them, and the owner hands chosen comments as a job with POST /api/computers/{id}/comments/ask to Operator, or to the owner's own coding agent while it listens on the site with POST /api/computers/{id}/comments/watch (one listening session per site; it claims the job by pulling it, and Operator takes the job over when it goes quiet). - name: Network description: Control a computer's public visibility and outbound network policy. - name: Sharing description: Invite people to use a computer without granting owner controls. - name: Domains description: >- Serve a computer at a hostname you control, such as app.example.com, beside its own address. - name: Public description: Unauthenticated discovery endpoints. - name: Secrets description: Inspect secret sets and their audit history; values are never returned. - name: Integrations description: Connect, inspect and revoke outside service accounts. - name: GitHub description: Work with repository workspaces using the connected user account. - name: Messaging description: >- Connect Telegram, Slack or WhatsApp so direct messages, and mentions of the Slack app in a channel, become chat turns. - name: Terminals description: Inspect a computer's terminal sessions. - name: Operator description: Read the operator agent's conversations, turns, and events. - name: Feedback description: >- Tell the Cool Computers team what works and what does not, with or without an account. externalDocs: description: Cool Computers agent registration guide url: https://www.cool.computer/auth.md paths: /api/computers/{id}/service/run: post: tags: - Services summary: Run the computer's service description: >- Saves and starts the computer's one long-running program, replacing any previous one, and keeps it running. The command is a shell line, as for exec. A program that exits with a failure or is killed after it was ready starts again after 1 s, doubling up to 60 s, and restarts counts it. With port, the program is ready once the port accepts connections, and then the computer's URL reaches it; without port (a bot or a worker), it is ready once it has stayed up 5 s, and the URL is unchanged. A program that ends before it is ready answers 409 with its exit and last stderr; one not ready after 60 seconds is kept, keeps starting in the background and answers 202. Install dependencies with a one-shot exec first: the command runs again on every restart. secrets names a secret set whose keys the program gets as environment variables when it starts, a key delivered by proxy as its stand-in; env adds plain values. On a site with no VM it gives the site its own VM first, which cannot be undone: its published files move to /home/runtime/app, and publishing to it stops. Once a port is exposed, the service answers every path but a site's functions (/api), and a site's files in /home/runtime/app are never served as files again, even after the port is removed. A later explicit exposure selection is independent of this process. Send an Idempotency-Key when a network failure might cause a retry. operationId: runComputerService parameters: - $ref: '#/components/parameters/ComputerID' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ServiceRunRequest' responses: '200': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: The configured service and current process state. content: application/json: schema: $ref: '#/components/schemas/Service' '202': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- The service is still starting in the background: its program runs, but was not ready within 60 seconds. It is kept, and its port, if it has one, is exposed once it is ready; detail says what happens next. content: application/json: schema: allOf: - $ref: '#/components/schemas/Service' - type: object required: - detail properties: detail: type: string '400': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Bad Request. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': $ref: '#/components/responses/Unauthorized' '402': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- Payment Required. The trial expired or Pro is inactive; inspect the problem code and resolution. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Forbidden. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Not Found. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Conflict. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '413': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Payload Too Large. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- Unprocessable Entity: secrets names a secret set the account does not have (secret_set_not_found). content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': $ref: '#/components/responses/TooManyRequests' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ComputerStarting' default: $ref: '#/components/responses/Problem' security: - bearerAuth: [] components: parameters: ComputerID: name: id in: path required: true description: >- The computer's name, such as agent-atlas, or its id (cmp_…). Every caller may use either, the computer's own runtime token included. schema: type: string minLength: 1 example: agent-atlas IdempotencyKey: name: Idempotency-Key in: header required: false description: >- A caller-generated key for safely retrying this side effect. The server retains the key and response for 24 hours. Reusing it with the same request replays the original response, except after a failure that proves nothing happened: that is kept for one minute, and one that sets Retry-After is not kept, so a retry after it runs the request again; reusing it with different input returns 409. schema: type: string minLength: 1 maxLength: 128 pattern: ^[!-~]+$ example: req_01J6M6Y9TF9Q9QF6M1ZP8K4R2A schemas: ServiceRunRequest: type: object additionalProperties: false required: - command example: command: node server.js port: 3000 properties: command: type: string minLength: 1 description: >- Shell line that starts the long-running program. It runs again on every restart, so install dependencies with a one-shot exec first. cwd: type: string description: >- Absolute path to an existing directory, reached without symlinks, used to start the program; anything else answers 400 invalid_cwd. Omit it to use /home/runtime/app (created if missing) with a port, and /home/runtime without one, so a worker's files stay out of the published folder; status reports it. / and /home are refused with 400. /home/runtime is allowed: every credential file in it is under a hidden path, which the computer's URL never serves. port: type: integer description: >- Port the program listens on; it is ready once the port accepts connections, and the computer's URL then reaches it. Omit it for a program that serves no port, such as a bot or a worker. Platform ports 3129, 18080 and 18088 are reserved. minimum: 1 maximum: 65535 not: enum: - 3129 - 18080 - 18088 secrets: type: string minLength: 1 maxLength: 63 description: >- Secret set (PUT /api/secrets/{secret_set}) whose keys the program gets as environment variables each time the service starts; a key delivered by proxy arrives as its stand-in. A changed set reaches the program at its next restart (POST .../service/restart). env: type: object description: >- Plain environment variables for the program; names are letters, digits and _, not starting with RUNTIME_. Keep keys and tokens in a secret set instead. additionalProperties: type: string Service: type: object additionalProperties: false required: - configured - status - ready - restarts properties: configured: type: boolean status: type: string description: >- unconfigured; starting (the program runs but is not ready yet); running (ready); restarting (waiting to start the program again after a crash); stopped; exited (the program ended with code 0); failed; unknown or unavailable when the VM cannot say; or the computer's status while it is not running. ready: type: boolean description: >- With a port, the port accepts connections; without one, the program has stayed up 5 s. url: type: string format: uri command: type: string cwd: type: string port: type: integer minimum: 1 maximum: 65535 description: Absent for a program that serves no port. exec_id: type: string pid: type: integer minimum: 1 started_at: type: string format: date-time ended_at: type: string format: date-time exit_code: type: integer signal: type: string restarts: type: integer minimum: 0 description: >- How often the program was started again after a crash since the service was last started. last_exit: type: object additionalProperties: false required: - code - at description: The last crash it was restarted after. properties: code: type: integer at: type: string format: date-time last_output: type: string description: The program's last line of output, while it is not ready. logs: $ref: '#/components/schemas/ServiceLogState' Problem: type: object additionalProperties: false required: - type - title - status - code - detail properties: type: type: string format: uri description: >- https://cool.computer/docs/api-reference/errors, the page that explains every code. title: type: string status: type: integer minimum: 400 maximum: 599 code: type: string pattern: ^[a-z0-9_]+$ detail: type: string resolution: type: string context: type: object additionalProperties: true suggestions: type: array items: type: string maxItems: 3 description: >- Values to send instead. With name_taken: up to three free names made from the requested one, the first with a random suffix; each was free when the answer was made. ServiceLogState: type: object additionalProperties: false required: - retention - bytes_written - bytes_dropped - dropped_frames - next_id properties: retention: type: string const: disk_ring bytes_written: type: integer format: int64 minimum: 0 bytes_dropped: type: integer format: int64 minimum: 0 dropped_frames: type: integer minimum: 0 next_id: type: integer format: int64 minimum: 0 headers: RateLimit: description: >- The applied policy name, requests remaining after this request, and whole seconds until the current UTC-aligned window resets. schema: type: string pattern: >- ^"(account|account-read|computer|computer-read|source|comment-board|comment-live)";r=[0-9]+;t=([1-9]|[1-5][0-9]|60)$ examples: - '"account";r=599;t=42' - '"computer-read";r=598;t=42' RateLimit-Policy: description: >- The selected policy name, quota, and window in seconds. Valid account credentials use account or account-read with q=600, computer credentials use computer or computer-read with q=600, unauthenticated or unrecognized requests use source with q=60 for their source IP, a browser session's read of a comment board uses comment-board with q=300 for its source IP, and its handshake of a comment live channel uses comment-live with q=60 for its source IP. schema: type: string pattern: >- ^("(account|account-read|computer|computer-read)";q=600|"source";q=60|"comment-board";q=300|"comment-live";q=60);w=60$ examples: - '"account";q=600;w=60' - '"computer-read";q=600;w=60' Retry-After: description: >- Whole seconds to wait after an api_request_rate_exceeded, comment_rate_exceeded, comment_site_rate_exceeded, comment_live_full or computer_starting response before retrying (up to 3600 for comment_site_rate_exceeded, whose window is an hour). Other 429 problem codes describe separate resource or provider limits and do not inherit this retry value. schema: type: integer minimum: 1 maximum: 3600 examples: - 42 responses: Unauthorized: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Unauthorized. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' TooManyRequests: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' description: >- Too Many Requests. If the problem code is api_request_rate_exceeded, wait for Retry-After seconds; other problem codes describe a separate limit. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' InternalServerError: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: Internal Server Error. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' ComputerStarting: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' Retry-After: $ref: '#/components/headers/Retry-After' description: >- Service Unavailable. `computer_starting` means the computer is starting, or stopped and being started again; wait for Retry-After seconds, then retry. Otherwise inspect the problem code and resolution. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Problem: headers: RateLimit: $ref: '#/components/headers/RateLimit' RateLimit-Policy: $ref: '#/components/headers/RateLimit-Policy' description: >- A machine-readable API error with a stable code and recovery instruction. content: application/problem+json: schema: $ref: '#/components/schemas/Problem' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: WorkOS user or agent access token, or Cool Computers API key description: >- A Cool Computers API key, user access token, or claimed agent access token in the Authorization header. Follow https://www.cool.computer/auth.md for agent registration and https://www.cool.computer/authentication.md for direct user credentials. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.