> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orgo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fork computer

> Copy a running computer, memory included, so the copy carries on from the same moment.

Creates a copy of a running Linux computer, including what is in its memory. The fork comes up `running` in the source’s workspace with the same apps, windows, and processes open, so an agent can carry on from the exact same point.

## Clone or fork?

| | [Clone](/api-reference/computers/clone) | Fork |
| - | - | - |
| Copies | The disk: files, installed apps, browser sessions | The disk and live memory: open apps, windows, running processes |
| The copy starts | From a fresh boot | Where the source was |
| Source | Running or stopped | Running, Linux only |
| Name | Your `name`, or `agent-1 (clone)` | `agent-1 (fork)` |

Clone a computer to reuse its setup. Fork it to try two next steps from the same moment.

<Info>
  The source pauses for about two seconds while its memory is copied, then carries on. The fork gets a new UUID and a new `instance_id`. Its auto-stop is forced to always-on regardless of the source’s setting.
</Info>

## Path parameters

<ParamField path="id" type="string" required>
  The source computer’s `instance_id`: the value `POST /computers` returns as `instance_id`, and `GET /computers/{id}` as `fly_instance_id`. Unlike clone, fork does not take the UUID: a UUID returns `404`.
</ParamField>

## Response

Returns `201` once the fork is running. The request has no body.

<ResponseField name="id" type="string">
  New computer UUID.
</ResponseField>

<ResponseField name="name" type="string">
  A generated name: `agent-1 (fork)`, then `agent-1 (fork 2)`.
</ResponseField>

<ResponseField name="status" type="string">
  Always `running`: the response is sent after the fork has resumed.
</ResponseField>

<ResponseField name="fly_instance_id" type="string">
  The fork’s `instance_id`. Use it for the fork’s own calls, including another fork.
</ResponseField>

## Plan limits

A fork is a new computer, so it is charged against the **workspace owner’s** plan. It draws on their computer slot, account RAM, per-computer CPU/RAM ceiling, and the storage the source’s disk requires. Any of those being exhausted returns `403`. See [https://orgo.ai/pricing](https://orgo.ai/pricing).

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://www.orgo.ai/api/computers/$INSTANCE_ID/fork \
    -H "Authorization: Bearer $ORGO_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      f"https://www.orgo.ai/api/computers/{instance_id}/fork",
      headers={"Authorization": f"Bearer {api_key}"}
  )

  fork = response.json()
  print(f"Fork created: {fork['name']} ({fork['fly_instance_id']})")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(`https://www.orgo.ai/api/computers/${instanceId}/fork`, {
    method: 'POST',
    headers: { 'Authorization': `Bearer ${apiKey}` }
  });

  const fork = await response.json();
  console.log(`Fork created: ${fork.name} (${fork.fly_instance_id})`);
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "7f3a9c21-5e8b-4d0a-b6c4-1e2f3a4b5c6d",
  "name": "agent-1 (fork)",
  "status": "running",
  "fly_instance_id": "7f3a9c21"
}
```

## Errors

Every error body carries `error` and `code`.

| Status | `code` | When |
| - | - | - |
| `400` | `DEVICE_LIFECYCLE_UNSUPPORTED` | The source runs on a dedicated machine that Orgo manages directly. |
| `400` | `NOT_FORKABLE` | The source has no server address on record, so it was never fully provisioned. |
| `401` | `UNAUTHENTICATED` | No valid API key, or the key can’t change the source’s workspace: you are not a member, you are view-only, or the key is scoped to another workspace. These checks run during authentication, so they return `401`, not `403`. |
| `401` | `UNAUTHENTICATED` | The credential store is unavailable: `Service temporarily unavailable. The database is not accepting requests. Retry shortly.` Retry; your key is not the problem. |
| `403` | `GUEST_RESTRICTED` | Share-link guests cannot create computers. |
| `403` | `DESKTOP_LIMIT`, `UPGRADE_REQUIRED`, `VM_SLOT_ADDON`, `RAM_ADDON`, `VCPU_ADDON`, `PER_COMPUTER_RAM_CAP`, `PER_COMPUTER_CPU_CAP`, `CHANGE_PLAN`, `PLAN_LIMIT` | The owner’s plan cannot fund another computer of this size. `PLAN_LIMIT` means a limit of a plan negotiated with Orgo. Also carries `upgradeTier` where a plan change would fix it. |
| `403` | `DISK_QUOTA_EXCEEDED` | The source’s disk is larger than the per-computer storage the owner’s plan allows. Also carries `max_disk_gb`. |
| `404` | `NOT_FOUND` | No computer has this `instance_id`, or its workspace no longer exists. |
| `409` | `NOT_FORKABLE` | The source is not running, is a Windows computer, or runs on an older VM type that cannot fork live. Create a new computer to fork, or contact support to migrate this one. |
| `409` | `HOURLY_QUOTE_REQUIRED` | The source is billed hourly or by its own subscription, so a copy needs its own purchase. |
| `500` | `AUTH_LOOKUP_FAILED` | The account could not be verified. |
| `500` | `INSERT_FAILED` | The fork record could not be saved. |
| `500` | `FORK_FAILED` | The copy failed on the host. The placeholder record is rolled back, so no half-made computer is left behind. |

```json theme={null}
{
  "error": "This computer must be running to fork (a fork copies its live memory).",
  "code": "NOT_FORKABLE"
}
```


## OpenAPI

````yaml POST /computers/{id}/fork
openapi: 3.1.0
info:
  title: Orgo API
  description: >-
    Launch cloud computers that AI agents can control and interact with. Create
    workspaces, provision computers, and control them programmatically.
  version: 2.0.0
  contact:
    name: Orgo Support
    email: spencer@orgo.ai
    url: https://orgo.ai
servers:
  - url: https://www.orgo.ai/api
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Account
    description: >-
      Account capacity: how many computers an account may run, and adding or
      giving back more.
  - name: Workspaces
    description: Organize computers into named workspaces
  - name: Computers
    description: Provision and manage virtual computers
  - name: Computer Lifecycle
    description: Start, stop, and restart computers
  - name: Computer Actions
    description: Control mouse, keyboard, and execute commands
  - name: Screens
    description: >-
      More than one desktop on a single computer. Each screen is its own X
      server with its own cursor and window manager, so an agent working on one
      cannot disturb another.
  - name: Files
    description: Upload and download files
  - name: Templates
    description: Author, build, and launch reproducible computers from templates
paths:
  /computers/{id}/fork:
    post:
      tags:
        - Computers
      summary: Fork computer
      description: >-
        Creates a copy of a running Linux computer, including its live memory,
        in the source's workspace. The fork comes up running with the same apps
        and windows open. The source pauses for about two seconds while its
        memory is copied. The fork is charged against the workspace owner's
        plan. Takes the source's `instance_id`; a UUID returns `404`. To copy
        only the disk, from a fresh boot, use clone. Every error body carries
        `error` and `code`.
      operationId: forkComputer
      parameters:
        - name: id
          in: path
          required: true
          description: Source computer `instance_id`
          schema:
            type: string
      responses:
        '201':
          description: Fork created and running
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: New computer UUID.
                  name:
                    type: string
                    example: agent-1 (fork)
                  status:
                    type: string
                    enum:
                      - running
                  fly_instance_id:
                    type: string
                    description: The fork's `instance_id`.
              example:
                id: 7f3a9c21-5e8b-4d0a-b6c4-1e2f3a4b5c6d
                name: agent-1 (fork)
                status: running
                fly_instance_id: 7f3a9c21
        '400':
          description: >-
            `DEVICE_LIFECYCLE_UNSUPPORTED`: the source runs on a dedicated
            machine. `NOT_FORKABLE`: no server address on record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-forkable:
                  summary: No server address
                  value:
                    error: >-
                      This computer can’t be forked (no server address on
                      record).
                    code: NOT_FORKABLE
        '401':
          description: >-
            No usable credential, or an access check failed. Every `401` carries
            `code: "UNAUTHENTICATED"`. Access, view-only, and scope failures run
            during authentication, so they return `401`, not `403`. A
            server-side fault while verifying the credential also returns `401`;
            retry that one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid-key:
                  summary: The key is not one of yours
                  value:
                    error: Invalid API key
                    code: UNAUTHENTICATED
                no-credential:
                  summary: No key and no session
                  value:
                    error: Authentication required
                    code: UNAUTHENTICATED
                no-access:
                  summary: Not the owner or a member of the workspace
                  value:
                    error: You do not have access to this workspace.
                    code: UNAUTHENTICATED
                view-only:
                  summary: View-only member, and the request changes something
                  value:
                    error: >-
                      This workspace is view-only. Ask the owner for write
                      access (workspace_read_only).
                    code: UNAUTHENTICATED
                scope-mismatch:
                  summary: The API key is scoped to another workspace
                  value:
                    error: >-
                      This API key cannot access this workspace
                      (workspace_scope_mismatch).
                    code: UNAUTHENTICATED
                service-unavailable:
                  summary: Server-side fault while verifying the credential. Retry.
                  value:
                    error: >-
                      Service temporarily unavailable. The database is not
                      accepting requests. Retry shortly.
                    code: UNAUTHENTICATED
        '403':
          description: >-
            Share-link guests cannot create computers (`GUEST_RESTRICTED`), the
            owner's plan cannot fund another computer of this size
            (`DESKTOP_LIMIT`, `UPGRADE_REQUIRED`, `VM_SLOT_ADDON`, `RAM_ADDON`,
            `VCPU_ADDON`, `PER_COMPUTER_RAM_CAP`, `PER_COMPUTER_CPU_CAP`,
            `CHANGE_PLAN`, or `PLAN_LIMIT` for a limit of a plan negotiated with
            Orgo, with `upgradeTier` where a plan change fixes it), or the
            source's disk is larger than the plan allows (`DISK_QUOTA_EXCEEDED`,
            with `max_disk_gb`).
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/QuotaError'
                  - $ref: '#/components/schemas/Error'
              examples:
                guest:
                  summary: Share-link guest
                  value:
                    error: Sign up to create your own workspace.
                    code: GUEST_RESTRICTED
                plan-limit:
                  summary: Plan cannot fund the fork
                  value:
                    error: >-
                      Creating a computer requires a paid plan. Upgrade to
                      launch your first computer.
                    code: UPGRADE_REQUIRED
                deal:
                  summary: Past a limit of a plan negotiated with Orgo
                  value:
                    error: >-
                      Your plan allows 3 computers, and you have 3. Delete one,
                      or contact us to change your plan.
                    code: PLAN_LIMIT
                    upgradeTier: enterprise
        '404':
          description: >-
            No computer has this `instance_id`, or its workspace no longer
            exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Desktop not found
                code: NOT_FOUND
        '409':
          description: >-
            `NOT_FORKABLE`: the source is not running, is a Windows computer, or
            runs on an older VM type that cannot fork live.
            `HOURLY_QUOTE_REQUIRED`: the source is billed hourly or by its own
            subscription, so a copy needs its own purchase.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                not-running:
                  summary: Source not running
                  value:
                    error: >-
                      This computer must be running to fork (a fork copies its
                      live memory).
                    code: NOT_FORKABLE
                windows:
                  summary: Windows source
                  value:
                    error: >-
                      Only Linux computers can be forked (a live-RAM fork needs
                      the QEMU backend).
                    code: NOT_FORKABLE
                hourly:
                  summary: Source billed on its own
                  value:
                    error: Choose a separate purchase for a new computer.
                    code: HOURLY_QUOTE_REQUIRED
        '500':
          description: >-
            `AUTH_LOOKUP_FAILED`: the account could not be verified.
            `INSERT_FAILED`: the fork record could not be saved. `FORK_FAILED`:
            the copy failed on the host, and the placeholder record is rolled
            back.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                insert:
                  summary: Record not saved
                  value:
                    error: Failed to save fork.
                    code: INSERT_FAILED
                auth-lookup:
                  summary: Account not verified
                  value:
                    error: Could not verify account
                    code: AUTH_LOOKUP_FAILED
components:
  schemas:
    Error:
      type: object
      description: >-
        The base error body. Every failure carries `error`; individual endpoints
        add the fields named in the schemas below.
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable message.
          example: Access denied
        code:
          type: string
          description: >-
            Machine-readable reason. Present on the failures that define one,
            absent otherwise.
    QuotaError:
      type: object
      description: >-
        The request was refused by the plan the workspace owner is on rather
        than by ownership. See https://orgo.ai/pricing for what each plan
        includes.
      required:
        - error
      properties:
        error:
          type: string
        code:
          type: string
          description: >-
            Machine-readable reason. Values this API emits: `UPGRADE_REQUIRED`,
            `DESKTOP_LIMIT`, `VM_SLOT_ADDON`, `RAM_ADDON`,
            `PER_COMPUTER_RAM_CAP`, `VCPU_ADDON`, `PER_COMPUTER_CPU_CAP`,
            `DISK_QUOTA_EXCEEDED`, `disk_exceeds_quota`,
            `WINDOWS_REQUIRES_SCALE`, `GUEST_RESTRICTED`, `NOT_A_MEMBER`,
            `CHANGE_PLAN`, `PLAN_LIMIT`, `upgrade_required`.
        upgradeTier:
          type: string
          description: The plan that would allow the request.
        canManageCapacity:
          type: boolean
          description: True when you own the workspace and can raise the limit yourself.
        max_ram_gb:
          type: integer
          description: >-
            On a RAM refusal from resize: the largest RAM a live resize can
            reach for this computer.
        max_disk_gb:
          type: integer
          description: 'On a storage refusal: the largest disk this computer may have.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your key at orgo.ai/workspaces

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.