# Create a Computer

URL: https://heaven.dev/docs/reference/computers/create
Updated: 2026-11-21

Create persistent Linux Computers with root access in a pool. A fresh Computer starts with a private website. A copy can inherit a public website from its source. Use `copy.computer` to start from an existing disk or `copy.snapshot` with `copy.computer` to use a saved disk. A request for `new_pool: true` can buy capacity. Read the returned operation with `operation view` to check whether creation is complete.

`POST /v1/computer/create`

## Parameters

- `name` (string): New Computer name of 3 to 63 lowercase letters, digits and hyphens. Start and end with a letter or digit. Omit to generate a name.
- `pool` (string): Destination pool name or ID. Omit if there is only one usable pool. With `new_pool: true`, this field names the new pool.
- `image` (string): Image for the Computer's starting disk. Give an available image or a container registry reference. The default is heaven-ubuntu.
- `template` (string): Template returned by `template view`. Give it in place of `image`.
- `registry_auth` (string): Private registry credential in USERNAME:PASSWORD form. Treated as a secret and never included in errors.
- `integrations` (string[]): Name of an integration to attach to the new Computer.
- `github` (object)
  - `repo` (string, required): GitHub repository to clone in OWNER/REPO form. The Computer must have access through a GitHub integration.
- `setup_script` (string): Shell script for first boot. Runs as the image's login user, which is heaven with passwordless sudo on heaven-ubuntu. Defaults to your saved setup script. Treated as a secret and never included in errors.
- `env` (string[]): Environment variable for the setup script in KEY=VALUE form. Each key can be set once. The variables are removed after setup runs. Treated as a secret and never included in errors.
- `tags` (string[]): Tag for the new Computer.
- `comment` (string): Computer comment, one line of at most 200 bytes.
- `domain` (string): Full name under a domain connected to your organization, such as app.example.com. DNS must point to your organization. For several Computers, set the domain with `pool defaults set`.
- `cpu` (string): CPU size in whole vCPUs, up to the pool's allocation. A copy inherits the source's setting. A fresh Computer uses the pool's default or follows the pool's CPU size.
- `memory` (string): Memory size up to the pool's allocation, such as 8GiB. G, GB and GiB mean GiB for memory. A copy inherits the source's setting. A fresh Computer follows the pool's memory size.
- `disk` (string): Disk size up to the pool's storage allocation, such as 20GB. GB is decimal and GiB is binary. A copy inherits the source's setting. A fresh Computer uses the pool's disk default or follows the pool's storage size.
- `copy` (object)
  - `computer` (string, required): Source Computer name or ID. Omit `copy.snapshot` to copy its current disk.
  - `snapshot` (string): Name or ID of a disk snapshot of the Computer named with `copy.computer`.
- `copy_tags` (boolean): Copy the source Computer's tags. Defaults to true.
- `count` (string): Number of Computers with identical settings. The pool's simultaneous create limit applies. Use `names` to choose the names.
- `names` (string[]): Names for new Computers with identical settings. Each name creates one Computer.
- `new_pool` (boolean): Create a pool for these Computers. Use `pool` to name it. Omission uses default or an available numbered variant.
- `units` (string): Size with `new_pool: true` in units of 2 vCPUs and 8 GiB of RAM, from 1 to 64. Defaults to 1. Uses unused capacity first, then buys the remainder.
- `hourly` (boolean): With `new_pool: true`, pay from your wallet by the minute, with a one-hour minimum (default).
- `monthly` (boolean): With `new_pool: true`, pay for new capacity through your monthly subscription.
- `dry_run` (boolean): Preview the Computers and whether they fit. With `new_pool: true`, includes the pool and its cost.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.
- `wait` (boolean or string): Wait for the operation to finish. Use true for up to 10m or give a shorter duration such as 2m. Accepted work continues after the wait ends.

## Returns

- `data` (object, always present): An operation for one Computer, or individual creation results and any new pool.
  - `alternative-1` (object): An operation and its request ID.
    - `name` (string): Computer's name after creation, copying or reset. May be omitted.
    - `notes` (string[]): Other effects, including settings or integrations excluded from a copy. May be omitted.
    - `operation` (object, always present): Current operation state.
      - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
      - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
      - `computer_id` (string, always present): Computer's stable ID.
      - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
      - `error_code` (string): Recorded failure code. May be omitted.
      - `id` (string, always present): Operation ID for `operation view`.
      - `kind` (string, always present): Change being tracked.
      - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
      - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
    - `pool_note` (string): How stopping this Computer affects its pool. May be omitted.
    - `renamed` (object): Addresses affected by a rename. May be omitted.
      - `https` (string, always present): Website URL using the new name.
      - `mail` (string, always present): Domain under which the Computer receives mail.
      - `names` (object[]): Custom names created with the Computer and whether they followed its rename. May be omitted.
        - `items` (object): A custom name affected by a Computer rename.
          - `from` (string, always present): Previous custom name.
          - `moved` (boolean, always present): Whether the name moved. False means the destination was occupied and the old custom name was retained.
          - `to` (string, always present): Name corresponding to the Computer's new name.
      - `note` (string, always present): What happened to old addresses and when the guest hostname changes.
      - `ports` (string[]): Published port addresses that use the new name. May be omitted.
      - `ssh` (string, always present): SSH command using the new name.
    - `request_id` (string, always present): Request ID identifying this change across retries.
    - `ssh_dest` (string): SSH destination in `NAME@DOMAIN` form. May be omitted.
    - `url` (string): Computer's website address. May be omitted.
  - `alternative-2` (object): The result or preview of creating Computers and any new pool.
    - `computers` (object[] | null, always present): Computers in request order, each with its operation or error. Previews and pending payments can have neither.
      - `items` (object): One Computer in a create request.
        - `error` (object): Reason this Computer could not be created. May be omitted.
          - `action` (object): A suggested command addressing the problem. May be omitted.
            - `command` (string, always present): Command's catalog name.
            - `line` (string, always present): Complete suggested command line.
          - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
          - `message` (string, always present): What happened and any action needed from you.
          - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
          - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
          - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
          - `url` (string): Payment page for a payment-required response. May be omitted.
        - `name` (string): Chosen Computer name. A count-only preview has no name yet. May be omitted.
        - `operation` (object): Create operation. May be omitted.
          - `by` (string): Requester's email address, or user ID if no email is recorded. Omitted for your own requests. May be omitted.
          - `completed_at` (string (date-time)): When the operation reached its final state. Absent while unfinished. May be omitted.
          - `computer_id` (string, always present): Computer's stable ID.
          - `created_at` (string (date-time)): When Heaven accepted the change. May be omitted.
          - `error_code` (string): Recorded failure code. May be omitted.
          - `id` (string, always present): Operation ID for `operation view`.
          - `kind` (string, always present): Change being tracked.
          - `message` (string): An explanation of the recorded failure and any next action. May be omitted.
          - `state` (string, always present): `accepted` means saved and unfinished. `complete` means the change finished. `failed` means it could not finish. `superseded` means a newer change replaced it before completion. Values: `"accepted"`, `"complete"`, `"failed"`, `"superseded"`.
        - `ssh_dest` (string): SSH destination in `NAME@DOMAIN` form. May be omitted.
        - `url` (string): Website URL. May be omitted.
    - `dry_run` (boolean): Whether this is a preview and no Computers were created. May be omitted.
    - `error` (object): Creation refusal found by a dry run. May be omitted.
      - `action` (object): A suggested command addressing the problem. May be omitted.
        - `command` (string, always present): Command's catalog name.
        - `line` (string, always present): Complete suggested command line.
      - `kind` (string, always present): Error category. `unknown` means the effect is uncertain; reconcile before retrying.
      - `message` (string, always present): What happened and any action needed from you.
      - `operation_id` (string): Operation to read before repeating uncertain work. May be omitted.
      - `request_id` (string): Request ID identifying the change during reconciliation. May be omitted.
      - `retry_after` (integer): Seconds before retrying a rate-limited request or a refused wait. May be omitted.
      - `url` (string): Payment page for a payment-required response. May be omitted.
    - `pool` (object): New pool, or the pool a dry run would create. May be omitted.
      - `bought` (object, always present): Capacity purchased for the remaining size.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `charged_cents` (integer): Charge now, or its dry-run estimate, in cents. May be omitted.
      - `from_unused` (object, always present): Existing purchased capacity assigned to the pool.
        - `memory_bytes` (integer, always present): RAM allocation in bytes.
        - `storage_bytes` (integer, always present): Included storage in bytes.
        - `units` (integer, always present): Number of units.
        - `vcpus` (integer, always present): vCPU allocation.
      - `id` (string): Created pool's ID. Absent for a preview or while payment is pending. May be omitted.
      - `kind` (string): Billing model for new purchases. May be omitted.
      - `memory_bytes` (integer, always present): Pool's RAM allocation, in bytes.
      - `name` (string, always present): New pool's name.
      - `plans` (object[]): Plans bought and any payment steps still required. May be omitted.
        - `items` (object): A plan purchased or proposed for a pool.
          - `charged_cents` (integer): Amount charged now, or its preview, in cents. May be omitted.
          - `checkout_url` (string): Checkout page when payment is required. May be omitted.
          - `invoice_url` (string): Invoice page when payment needs your action. May be omitted.
          - `plan` (integer, always present): Plan number.
          - `price_micros` (integer, always present): Price per billing period, in millionths of a dollar. The enclosing result specifies the billing model.
          - `purchase` (string): Capacity purchase ID. May be omitted.
          - `units` (integer, always present): Capacity units supplied by the plan.
          - `unknown` (boolean): Whether the payment outcome is uncertain. Read capacity before buying again. May be omitted.
      - `price_micros` (integer, always present): Combined price of new purchases per billing period, in millionths of a dollar.
      - `region` (string): Pool's region. May be omitted.
      - `storage_bytes` (integer, always present): Pool's included storage, in bytes.
      - `units` (integer, always present): Pool's capacity in units.
      - `vcpus` (integer, always present): Pool's vCPU allocation.
    - `request_id` (string, always present): Request ID for this creation.
    - `room` (object): Request's capacity check, when available. May be omitted.
      - `computers` (integer, always present): Number of Computers requested.
      - `fits` (boolean, always present): Whether the request fits the pool's available storage and creation limits.
      - `needs_bytes` (integer, always present): Estimated additional storage needed by the request, in bytes.
      - `pool` (string, always present): Pool checked.
      - `storage_bytes` (integer, always present): Pool's included storage, in bytes.
      - `stored_bytes` (integer, always present): Storage already occupied in the pool, in bytes.
      - `waiting_for_memory` (integer, always present): Of the Computers the pool is creating, how many are waiting for memory in the pool.
    - `waiting` (boolean): Whether purchases await payment. Heaven creates the pool and Computers once payment is confirmed. May be omitted.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `payment_required` | 402 | Payment or credit is required. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- CLI: `heaven login` with `HEAVEN_API_KEY` unset. MCP: Heaven sign-in. cURL: `HEAVEN_SIGN_IN_KEY` from approved device sign-in (`POST /v1/auth/create`). Some inputs require sign-in.
- API key permission: `create`.
- For retries, reuse the original `Idempotency-Key` and inputs.
- **One:** Create one Computer from an image or template. Optional: `name`, `domain`, `image`, `template`, `registry_auth`, `integrations`, `github`, `setup_script`, `env`, `tags`, `comment`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.
- **By count:** Create the requested number of Computers with generated names. Required: `count`. Optional: `image`, `template`, `registry_auth`, `integrations`, `github`, `setup_script`, `env`, `tags`, `comment`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.
- **By name:** Create a Computer for each supplied name. Required: `names`. Optional: `image`, `template`, `registry_auth`, `integrations`, `github`, `setup_script`, `env`, `tags`, `comment`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.
- **Copy:** Copy a Computer from its current disk or a snapshot. Required: `copy`. Optional: `name`, `copy_tags`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.
- **Copies by count:** Create the requested number of copies with generated names. Required: `copy`, `count`. Optional: `copy_tags`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.
- **Copies by name:** Create a copy for each supplied name. Required: `copy`, `names`. Optional: `copy_tags`, `pool`, `cpu`, `memory`, `disk`, `new_pool`, `units`, `hourly`, `monthly`, `dry_run`, `organization`, `wait`.

## Examples

```sh tab="heaven CLI"
heaven create [NAME]
  [--pool POOL]
  [--image IMAGE]
  [--template NAME]
  [--registry-auth USER:PASSWORD]
  [--integration INTEGRATION ...]
  [--github REPO]
  [--setup-script SCRIPT]
  [--env KEY=VALUE ...]
  [--tag TAG ...]
  [--comment COMMENT]
  [--domain DOMAIN]
  [--cpu N]
  [--memory SIZE]
  [--disk SIZE]
  [--copy COMPUTER]
  [--snapshot SNAPSHOT]
  [--copy-tags true|false]
  [--count N]
  [--names NAMES ...]
  [--new-pool]
  [--units N]
  [--hourly]
  [--monthly]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
  [--wait[=DURATION]]
```

```sh tab="SSH"
ssh cli@heaven.dev create [NAME]
  [--pool POOL]
  [--image IMAGE]
  [--template NAME]
  [--registry-auth USER:PASSWORD]
  [--integration INTEGRATION ...]
  [--github REPO]
  [--setup-script SCRIPT]
  [--env KEY=VALUE ...]
  [--tag TAG ...]
  [--comment COMMENT]
  [--domain DOMAIN]
  [--cpu N]
  [--memory SIZE]
  [--disk SIZE]
  [--copy COMPUTER]
  [--snapshot SNAPSHOT]
  [--copy-tags true|false]
  [--count N]
  [--names NAMES ...]
  [--new-pool]
  [--units N]
  [--hourly]
  [--monthly]
  [--dry-run]
  [--request-id ID]
  [--organization ORGANIZATION]
  [--wait[=DURATION]]
```

```sh tab="cURL"
curl https://heaven.dev/v1/computer/create \
  -H "Authorization: Bearer $HEAVEN_SIGN_IN_KEY" \
  -H "Idempotency-Key: create-my-site" \
  --json '{"name": "my-site", "pool": "web"}'
```

```json tab="MCP"
{ "tool": "create",
  "arguments": { "name": "my-site", "pool": "web", "request_id": "create-my-site" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "name": "my-site",
    "operation": {
      "computer_id": "d2f29c29-7e7a-4106-a67d-4f3b80b8b493",
      "created_at": "2026-11-16T12:00:00Z",
      "id": "76ca564a-861b-46fa-aea6-9157162e8659",
      "kind": "create",
      "state": "accepted"
    },
    "request_id": "create-my-site",
    "ssh_dest": "my-site@heaven.dev",
    "url": "https://my-site.heaven.dev"
  }
}
```
