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
}'
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())
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());
{
"id": "7f91ab02cd",
"status": "running",
"name": "burst-worker"
}
Lifecycle
Fork an instance
Copy an instance into an independent instance with its own id, URLs, budget, and billing.
POST
/
v1
/
instances
/
{id}
/
fork
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
}'
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())
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());
{
"id": "7f91ab02cd",
"status": "running",
"name": "burst-worker"
}
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
}'
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())
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());
{
"id": "7f91ab02cd",
"status": "running",
"name": "burst-worker"
}
Authorization: Bearer sk_live_... on https://api.agent37.com.
Path parameters
string
required
The instance id, returned when you create an instance.
Response and behavior
The response contains the full instance 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 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).
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 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.