---
title: "Run the computer's service"
description: "Saves and starts the computer's one long-running program, replacing any previous one, and keeps it running."
canonical: "https://www.cool.computer/docs/api-reference/services/run-the-computers-service"
---
# Run the computer's service

> Saves and starts the computer's one long-running program, replacing any previous one, and keeps it running.

```http
POST https://api.cool.computer/api/computers/{id}/service/run
```

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. A nonempty secrets value requires an unshared computer: an active share or live pending invitation answers 409 computer_shared before checking set existence. Run without secrets or use an unshared computer. 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.

## Authorization

- 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.

## Parameters

- `id` (path, string, at least 1 characters, required): The computer's name, such as agent-atlas, or its id (cmp_…). Every caller may use either, the computer's own runtime token included.
- `Idempotency-Key` (header, string, pattern `^[!-~]+$`, 1 to 128 characters): 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.

## Request body

Required.

- `application/json` (object)
  - `command` (string, at least 1 characters, required): Shell line that starts the long-running program. It runs again on every restart, so install dependencies with a one-shot exec first.
  - `cwd` (string): 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` (integer, 1 to 65535, not 3129, 18080, 18088): 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.
  - `secrets` (string, 1 to 63 characters): 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` (object): Plain environment variables for the program; names are letters, digits and _, not starting with RUNTIME_. Keep keys and tokens in a secret set instead.
    - `*` (string): Each value, under a name of the caller's.

## Responses

- `200`: The configured service and current process state.
  - `application/json` (object)
    - `configured` (boolean, required)
    - `status` (string, required): 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` (boolean, required): With a port, the port accepts connections; without one, the program has stayed up 5 s.
    - `url` (string, uri)
    - `command` (string)
    - `cwd` (string)
    - `port` (integer, 1 to 65535): Absent for a program that serves no port.
    - `exec_id` (string)
    - `pid` (integer, at least 1)
    - `started_at` (string, date-time)
    - `ended_at` (string, date-time)
    - `exit_code` (integer)
    - `signal` (string)
    - `restarts` (integer, at least 0, required): How often the program was started again after a crash since the service was last started.
    - `last_exit` (object): The last crash it was restarted after.
      - `code` (integer, required)
      - `at` (string, date-time, required)
    - `last_output` (string): The program's last line of output, while it is not ready.
    - `logs` (object)
      - `retention` ("disk_ring", required)
      - `bytes_written` (integer, int64, at least 0, required)
      - `bytes_dropped` (integer, int64, at least 0, required)
      - `dropped_frames` (integer, at least 0, required)
      - `next_id` (integer, int64, at least 0, required)
- `202`: 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.
  - `application/json` (object)
    - `configured` (boolean, required)
    - `status` (string, required): 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` (boolean, required): With a port, the port accepts connections; without one, the program has stayed up 5 s.
    - `url` (string, uri)
    - `command` (string)
    - `cwd` (string)
    - `port` (integer, 1 to 65535): Absent for a program that serves no port.
    - `exec_id` (string)
    - `pid` (integer, at least 1)
    - `started_at` (string, date-time)
    - `ended_at` (string, date-time)
    - `exit_code` (integer)
    - `signal` (string)
    - `restarts` (integer, at least 0, required): How often the program was started again after a crash since the service was last started.
    - `last_exit` (object): The last crash it was restarted after.
      - `code` (integer, required)
      - `at` (string, date-time, required)
    - `last_output` (string): The program's last line of output, while it is not ready.
    - `logs` (object)
      - `retention` ("disk_ring", required)
      - `bytes_written` (integer, int64, at least 0, required)
      - `bytes_dropped` (integer, int64, at least 0, required)
      - `dropped_frames` (integer, at least 0, required)
      - `next_id` (integer, int64, at least 0, required)
    - `detail` (string, required)
- `400`: Bad Request.
- `401`: Unauthorized.
- `402`: Payment Required. `pro_required`: VMs need Pro; start Pro with cool billing upgrade, or fix a lapsed subscription with cool billing portal, or use the Account page.
- `403`: Forbidden.
- `404`: Not Found. `computer_not_found`: the computer does not exist or is not yours.
- `409`: Conflict.
- `413`: Payload Too Large.
- `422`: Unprocessable Entity: secrets names a secret set the account does not have (secret_set_not_found).
- `429`: Too Many Requests. If the problem code is api_request_rate_exceeded, wait for Retry-After seconds; other problem codes describe a separate limit.
- `500`: Internal Server Error.
- `503`: 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.
- `default`: A machine-readable API error with a stable code and recovery instruction.

An error is an `application/problem+json` document with a stable `code`; [API errors](/docs/api-reference/errors) says how to handle one.

## Example

```sh
curl -X POST "https://api.cool.computer/api/computers/$PARAM_ID/service/run" \
  -H "authorization: Bearer $TOKEN" \
  -H "content-type: application/json" \
  --data '{"command":"node server.js","port":3000}'
```
