# Branch a computer

> Branch a computer into a new computer from its current disks, leaving the source running.

> Nevia is in beta and open to selected teams. Public launch in Dec 2026. The CLI installs with `curl -fsSL https://get.nevia.cloud | sh`, and the MCP server is at https://api.nevia.cloud/mcp. A person signs in once in the browser.
> Setup, sign-in and requesting access: [SKILL.md](https://nevia.cloud/SKILL.md). When Nevia fits and when it doesn't: [why.md](https://nevia.cloud/why.md).

> For the complete documentation index, see [llms.txt](https://nevia.cloud/llms.txt). This page's HTML version: https://nevia.cloud/docs/reference/api/computers/branchComputer

`POST https://api.nevia.cloud/v1/computers/{cmp}/branch`

## Authorization

- `bearerAuth`: HTTP bearer in the Authorization header

Send the token in the `Authorization: Bearer <token>` header. See [Authenticate](https://nevia.cloud/docs/reference/api.md#authenticate).

## Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `cmp` | path | string | yes | Computer id: 27 lowercase letters and digits. Match `^[A-Za-z0-9_-]{1,64}$`. |
| `Idempotency-Key` | header | string | no | Optional retry key, kept 24 hours. Length `1 <= length <= 255`. |

## Request body

Content type: `application/json`

Schema: `ComputerBranchRequest`

Settings for a branch

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | no | Unique within the workspace per resource kind. Match `^[a-z0-9]([a-z0-9-]*[a-z0-9])?$`. Length `1 <= length <= 63`. |
| `protected` | boolean | no | Default `false`. |

## Behavior

The clone gets private copies of the source's disks. It gets the same image, env and ports, under its own hostname. It keeps the source's stored env, resolved at each exec. `parent` names the source.

Without a `name`, the clone takes the source's name and the next free branch number, like `bright-anchovy-1`.

The `computer.branch` operation finishes in the `200` response. If the clone does not come up in the short wait, the response is `202`, and the operation keeps running.

## Example request

### cURL

```bash
curl -X POST "https://api.nevia.cloud/v1/computers/01d4cnjk3xg90y576w8y6t4gdwm/branch" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-feature-x"
  }'
```

### JavaScript

```js
const body = JSON.stringify({
  "name": "api-feature-x"
})

fetch("https://api.nevia.cloud/v1/computers/01d4cnjk3xg90y576w8y6t4gdwm/branch", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.TOKEN}`
  },
  body
})
```

### Python

```python
import os
import requests

url = "https://api.nevia.cloud/v1/computers/01d4cnjk3xg90y576w8y6t4gdwm/branch"
body = """{
  "name": "api-feature-x"
}"""
response = requests.request("POST", url, data = body, headers = {
  "Content-Type": "application/json", 
  "Authorization": f"Bearer {os.environ['TOKEN']}"
})

print(response.text)
```

## Responses

### 200

The new computer, `ready` or `failed`, when the clone came up in time.

Content type: `application/json`

Schema: `ComputerResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `computer` | Computer | yes | Computer running an OCI image. |
| `operations` | array<OperationId> | yes | Operations this request started. |

Example:

```json
{
  "computer": {
    "id": "01d4cnjk3xg90y576w8y6t4gdwm",
    "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
    "name": "api-staging",
    "state": "ready",
    "pending": null,
    "image": "docker.io/library/python:3.13-slim",
    "image_digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "ports": [
      {
        "published": 8080,
        "target": 8080,
        "protocol": "http1",
        "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example:8080"
      }
    ],
    "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example",
    "env_keys": [
      "LOG_LEVEL",
      "OPENAI_KEY"
    ],
    "env_vars": [
      {
        "name": "LOG_LEVEL",
        "source": "literal",
        "missing": false
      },
      {
        "name": "OPENAI_KEY",
        "source": "secret",
        "missing": false
      }
    ],
    "generation": 1,
    "protected": false,
    "parent": null,
    "from_checkpoint": null,
    "error": null,
    "created_at": "2026-09-10T12:34:56Z",
    "last_started_at": "2026-09-10T12:35:12Z",
    "last_active_at": "2026-09-10T12:40:03Z",
    "deleted_at": null
  },
  "operations": [
    "01d4cnjm89yk0r3xtv80dy0x7by"
  ]
}
```

### 202

The new computer in `creating`, when the clone did not come up in time.

Content type: `application/json`

Schema: `ComputerResponse`

| Field | Type | Required | Description |
|---|---|---|---|
| `computer` | Computer | yes | Computer running an OCI image. |
| `operations` | array<OperationId> | yes | Operations this request started. |

Example:

```json
{
  "computer": {
    "id": "01d4cnjk3xg90y576w8y6t4gdwm",
    "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
    "name": "api-staging",
    "state": "ready",
    "pending": null,
    "image": "docker.io/library/python:3.13-slim",
    "image_digest": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "ports": [
      {
        "published": 8080,
        "target": 8080,
        "protocol": "http1",
        "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example:8080"
      }
    ],
    "url": "https://01d4cnjk3xg90y576w8y6t4gdwm.machines.example",
    "env_keys": [
      "LOG_LEVEL",
      "OPENAI_KEY"
    ],
    "env_vars": [
      {
        "name": "LOG_LEVEL",
        "source": "literal",
        "missing": false
      },
      {
        "name": "OPENAI_KEY",
        "source": "secret",
        "missing": false
      }
    ],
    "generation": 1,
    "protected": false,
    "parent": null,
    "from_checkpoint": null,
    "error": null,
    "created_at": "2026-09-10T12:34:56Z",
    "last_started_at": "2026-09-10T12:35:12Z",
    "last_active_at": "2026-09-10T12:40:03Z",
    "deleted_at": null
  },
  "operations": [
    "01d4cnjm89yk0r3xtv80dy0x7by"
  ]
}
```

### 400

`validation_failed`: malformed body, unknown field, or invalid id or name. Fix `details.field` and retry.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `validation_failed`:

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Unknown field `colour` in the request body. Remove it; request bodies are strict.",
    "details": {
      "field": "colour",
      "in": "body"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 401

`unauthorized`: the credential is missing, malformed, expired, or revoked. Send a valid bearer token.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `unauthorized`:

```json
{
  "error": {
    "code": "unauthorized",
    "message": "Missing credential. Send `Authorization: Bearer <token>` with an access token.",
    "details": {},
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 403

`forbidden`: the `env` references a secret or variable the caller may not reference. Secrets need the `editor` role or higher in the workspace, variables any role.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `forbidden`:

```json
{
  "error": {
    "code": "forbidden",
    "message": "Referencing workspace secrets needs workspace#edit on workspace 01d4cnjjq40hnnh0nwmkg35nv2h. Ask a workspace admin to change your role.",
    "details": {
      "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
      "permission": "workspace#edit"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 404

`not_found`: the computer does not exist, or you cannot see it. Both return the same response.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `not_found`:

```json
{
  "error": {
    "code": "not_found",
    "message": "Computer 01d4cnjk3xg90y576w8y6t4gdwm was not found. List the computers you can access with GET /v1/computers?workspace=<ws>.",
    "details": {
      "computer": "01d4cnjk3xg90y576w8y6t4gdwm"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 409

`invalid_state`: the source is not `ready` or `sleeping`, a transition on it is pending, or the platform no longer has it. `name_conflict`: `name` is taken in the workspace. `limit_exceeded`: the beta cap on live computers is reached. `idempotency_conflict`: the `Idempotency-Key` was already used with a different body.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `invalid_state`:

```json
{
  "error": {
    "code": "invalid_state",
    "message": "Computer 01d4cnjk3xg90y576w8y6t4gdwm is ready with a sleeping transition pending and cannot be branched. Wait for the pending transition (GET /v1/computers/01d4cnjk3xg90y576w8y6t4gdwm shows `pending: null` once it ends), then retry.",
    "details": {
      "computer": "01d4cnjk3xg90y576w8y6t4gdwm",
      "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
      "state": "ready",
      "pending": "sleeping"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

Example `name_conflict`:

```json
{
  "error": {
    "code": "name_conflict",
    "message": "A computer named api-staging already exists in workspace 01d4cnjjq40hnnh0nwmkg35nv2h. Pick another name, or find it with GET /v1/computers?workspace=01d4cnjjq40hnnh0nwmkg35nv2h&name=api-staging.",
    "details": {
      "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h",
      "name": "api-staging",
      "list_route": "GET /v1/computers?workspace=01d4cnjjq40hnnh0nwmkg35nv2h"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

Example `limit_exceeded`:

```json
{
  "error": {
    "code": "limit_exceeded",
    "message": "Beta limit reached: 10 of 10 computers. Delete one to create another.",
    "details": {
      "kind": "computer",
      "scope": "user",
      "count": 10,
      "limit": 10
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

Example `idempotency_conflict`:

```json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "Idempotency-Key 8f1c2a7e-3b4d-4c5e-9f0a-1b2c3d4e5f60 was already used for a different POST /v1/computers/{cmp}/branch request. Use a new key for a new request.",
    "details": {
      "idempotency_key": "8f1c2a7e-3b4d-4c5e-9f0a-1b2c3d4e5f60"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 422

`not_supported`: the platform cannot branch this computer.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `not_supported`:

```json
{
  "error": {
    "code": "not_supported",
    "message": "This request is not supported for computer 01d4cnjk3xg90y576w8y6t4gdwm. Quote request_id when reporting.",
    "details": {
      "computer": "01d4cnjk3xg90y576w8y6t4gdwm",
      "workspace": "01d4cnjjq40hnnh0nwmkg35nv2h"
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 423

`operation_in_progress`: a conflicting operation runs. Retry after `Retry-After`, or poll `details.operation_id` for completion.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `operation_in_progress`:

```json
{
  "error": {
    "code": "operation_in_progress",
    "message": "Computer 01d4cnjk3xg90y576w8y6t4gdwm has an operation in progress. Poll GET /v1/operations/01d4cnjm89yk0r3xtv80dy0x7by until it finishes, then retry.",
    "details": {
      "computer": "01d4cnjk3xg90y576w8y6t4gdwm",
      "operation_id": "01d4cnjm89yk0r3xtv80dy0x7by",
      "retry_after_seconds": 2
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 429

`rate_limited`: slow down. Retry after `Retry-After`.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `rate_limited`:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Retry after 2 seconds.",
    "details": {
      "retry_after_seconds": 2
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 500

`request_failed`, or the failed action's own code, such as `creation_failed`, `authorization_failed` or `command_execution_failed`. Quote `request_id` when reporting. The diagnostic stays in server logs.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `request_failed`:

```json
{
  "error": {
    "code": "request_failed",
    "message": "request failed",
    "details": {},
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```

### 503

The action is temporarily unavailable, named by its code (`creation_failed`, `wake_failed`, ...). Wait at least `Retry-After` seconds (60 by default). `details.retryable` says whether repeating the request is safe. Keep the original `Idempotency-Key`. Signing in again does not help.

Content type: `application/json`

Schema: `ErrorEnvelope`

Body of every error response

| Field | Type | Required | Description |
|---|---|---|---|
| `error` | Error | yes |  |

Example `creation_failed`:

```json
{
  "error": {
    "code": "creation_failed",
    "message": "The computer could not be created. Try again later, and quote request_id if it persists.",
    "details": {
      "retryable": true
    },
    "request_id": "req_01j9k3m2p7q4r8s1"
  }
}
```