---
title: "Create a computer"
description: "Creates a computer with its own VM, an always-on Ubuntu machine with sudo, and waits until it runs."
canonical: "https://www.cool.computer/docs/api-reference/computers/create-a-computer"
---
# Create a computer

> Creates a computer with its own VM, an always-on Ubuntu machine with sudo, and waits until it runs.

```http
POST https://api.cool.computer/api/computers
```

Creates a computer with its own VM, an always-on Ubuntu machine with sudo, and waits until it runs. Its URL serves nothing until a program does, and nothing is published to it. The response has status running. The request body is optional; omitting it assigns a random available name. Starting a program is a separate POST /api/computers/{id}/service/run request. The VM uses 1 of the account's 20 VMs and memory from the account's 8 GiB, which all its VMs share (one VM can use most of it while the others are idle); VM quota, compute access and host capacity apply. To publish a page or a site instead, use POST /api/publish. A definite failure to give the computer its VM rolls the new computer back. An unknown outcome keeps the resource and its Idempotency-Key binding for recovery. 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

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

Optional.

- `application/json` (object)
  - `name` (string, pattern `^[a-z0-9]+(?:-[a-z0-9]+)*$`, at most 63 characters, not "abuse", "admin", "admin-api", "api", "edge-api", "hostmaster", "mail", "mailer-daemon", "no-reply", "noreply", "postmaster", "root", "security", "signup", "support", "webmaster", "www"): Optional stable name, such as agent-atlas. A name that breaks the pattern answers 400 invalid_slug with the nearest valid name as a suggestion; a name the service holds answers 400 reserved_slug.
  - `visibility` ("private" or "public", default "public")
  - `auto_delete_after` (string): Positive Go duration such as 24h.
  - `network_policy` (object): Outbound access policy. open allows public destinations, none blocks outbound access, and allowlist permits only the named public hosts. Private and reserved addresses remain blocked.
    - `mode` ("open" or "none" or "allowlist", required)
    - `allowed_hosts` (array of string, at most 100 items): Required and non-empty only when mode is allowlist. Each value is a hostname, public IP, or leading wildcard such as \*.example.com, without a scheme, port, path, or CIDR.

## Responses

- `201`: The computer, running on its own VM.
  - `application/json` (object)
    - `id` (string, required)
    - `hostname` (string, required)
    - `name` (string, required)
    - `ip` (string, required)
    - `status` (string, required): artifact (no VM), creating, running, stopped while its account's Pro has lapsed (its VM is stopped and deleted at auto_delete_at unless Pro returns; once Pro returns it can show running briefly until the reconciler has started its VM), or deleting from when its deletion begins until it is gone.
    - `url` (string, uri)
    - `email_address` (string, email)
    - `visibility` ("private" or "public", required)
    - `access` ("owner" or "can_use" or "claim_key", required): What the caller holds: owner, can_use for a computer shared with them, or claim_key in the response to a publish without an account, whose claim key republishes to the computer and claims it.
    - `copy_enabled` (boolean, required): People other than the owner may copy the computer into their own accounts (PUT /api/computers/{id}/copy-settings).
    - `site` (boolean, required): The URL serves the computer's published files: from the edge, or from its VM's built-in site server until a port is first exposed, when the program on it takes every path but the functions' for good.
    - `network_policy` (object, required): Outbound access policy. open allows public destinations, none blocks outbound access, and allowlist permits only the named public hosts. Private and reserved addresses remain blocked.
      - `mode` ("open" or "none" or "allowlist", required)
      - `allowed_hosts` (array of string, at most 100 items): Required and non-empty only when mode is allowlist. Each value is a hostname, public IP, or leading wildcard such as \*.example.com, without a scheme, port, path, or CIDR.
    - `created_at` (string, date-time, required)
    - `auto_delete_at` (string or null, date-time): When the computer is deleted by itself: its own auto-delete deadline, or, for a VM of an account whose Pro lapsed, when its stopped VMs are deleted, whichever comes first.
    - `creation_mode` (string)
- `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.
- `409`: Conflict. `name_taken`: another account holds the name (names are shared by everyone on Cool Computers); send one of the free names in suggestions instead. `name_is_yours`: one of your computers already has the name; use it, or choose another name. `name_releasing`: one of your own computers holds the name while it is still being created or deleted; wait for Retry-After seconds, then retry. Otherwise inspect the problem code, context, and resolution.
- `413`: Payload Too Large.
- `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. Retry the identical create with the same Idempotency-Key after Retry-After seconds.
- `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" \
  -H "authorization: Bearer $TOKEN"
```
