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

# Fork an instance

> Copy an instance into an independent instance with its own id, URLs, budget, and billing.

<RequestExample>
  ```bash curl wrap theme={null}
  curl -X POST \
    https://api.agent37.com/v1/instances/ab12cd34ef/fork \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "resources": {
        "cpu": 2,
        "memory": 4,
        "disk": 6
      },
      "user": "u_882",
      "name": "burst-worker",
      "metadata": {
        "plan": "pro"
      },
      "auto_sleep": true,
      "idle_timeout_seconds": 900
    }'
  ```

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

  response = requests.post(
      "https://api.agent37.com/v1/instances/ab12cd34ef/fork",
      headers={
          "Authorization": "Bearer sk_live_...",
          "Content-Type": "application/json"
      },
      json={
          "resources": {
              "cpu": 2,
              "memory": 4,
              "disk": 6
          },
          "user": "u_882",
          "name": "burst-worker",
          "metadata": {
              "plan": "pro"
          },
          "auto_sleep": True,
          "idle_timeout_seconds": 900
      },
  )
  response.raise_for_status()
  print(response.json())
  ```

  ```javascript Node wrap theme={null}
  const response = await fetch(
    "https://api.agent37.com/v1/instances/ab12cd34ef/fork",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer sk_live_...",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        "resources": {
          "cpu": 2,
          "memory": 4,
          "disk": 6
        },
        "user": "u_882",
        "name": "burst-worker",
        "metadata": {
          "plan": "pro"
        },
        "auto_sleep": true,
        "idle_timeout_seconds": 900
      }),
    },
  );
  if (!response.ok) {
    throw new Error(await response.text());
  }
  console.log(await response.json());
  ```
</RequestExample>

<ResponseExample>
  ```json 201 (excerpt) wrap theme={null}
  {
    "id": "7f91ab02cd",
    "status": "running",
    "name": "burst-worker"
  }
  ```
</ResponseExample>

Authenticate with `Authorization: Bearer sk_live_...` on `https://api.agent37.com`.

## Path parameters

<ParamField path="id" type="string" required>
  The instance id, returned when you create an instance.
</ParamField>

## Response and behavior

The response contains the full [instance object](/docs/agents-api/instances/object); the example shows selected fields.

`POST /v1/instances/{id}/fork` copies an instance into a second instance: the same image and the same files, with its own id, URLs, starter credential, budget, and meter. The source keeps running throughout and is not touched. The body is optional and every field in it defaults to the source's, so a bare `POST` clones the instance as it stands.

| Field | Default |
| - | - |
| `resources` | the source's shape |
| `name`, `user`, `metadata` | the source's |
| `auto_sleep`, `idle_timeout_seconds` | the source's |

`resources` is the field that makes fork more than a copy: `cpu` and `memory` may move in either direction, so a fork can be smaller or larger than its source. `disk` can only match or grow, since the fork has to hold the same files, and a smaller one returns `400`. To change one instance's size and keep its id and URLs, [resize](/docs/agents-api/instances/resize) it instead; fork when you want a second instance at the other size. The new instance is created under the same gates as any other, so it counts against your workspace's instance limit and needs a day of balance (see [Capacity and limit errors](/docs/agents-api/instances/create#capacity-and-limit-errors)).

What is copied is the source's disk, not its memory: processes running in the source do not carry over, and the fork boots fresh with the same files. The copy is taken at the moment of the call. From there the two instances are fully independent, each with its own disk, so a write in one is never visible in the other.

The fork gets fresh URLs, and its [public ports](/docs/agents-api/public-ports) are its template's defaults minted for its own id, never the source's: a slug is the credential for the port it opens, so it is not shared out by a copy. Anything the agent keeps in its own files does come across, including credentials you put there, which is what makes a fork a fork. If the source has a messaging channel connected, both instances will hold the same bot token, so disconnect it on one of them.

A fork of a large instance can outrun its request. It then returns `202` with the new instance `provisioning` and the platform finishes it on its own: poll `GET /v1/instances/{id}` until it reads `running`. The source must be `running`, `stopped`, or `sleeping`; one parked in cold storage has to be started first.


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