> ## 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.
# Resize computer
> Change CPU, RAM, disk, bandwidth, or auto-stop on a running computer.
Resizes a running computer. Every field is optional. Send only what you want to change.
`vcpus` and `bandwidth_limit_mbps` apply to the live computer. Disk growth applies live on Linux; a Windows computer restarts in place to grow its disk. A `mem_gb` change applies live on a Linux computer that supports live memory resize, and restarts any other computer in place. `connection_rotated` is `true` when the ports or VNC password changed. When it is, re-fetch [`GET /computers/{id}`](/api-reference/computers/get) and reconnect.
The computer must be `running`. The response reports the values the computer actually accepted, not the ones you asked for: a dimension that failed to apply comes back with its previous value.
## Path parameters
Computer UUID or `instance_id`. Both resolve to the same computer.
## Body parameters
New vCPU count: `0.5`, `1`, `2`, `4`, `8`, or `16`, as a JSON number. Any other value returns `400`. A value above your per-computer ceiling returns `403`. Omitted leaves CPU alone.
New RAM in GB: `4`, `8`, `16`, or `32`, as a JSON number. Any other value returns `400`. A resize tops out at the host's boot-memory ceiling, 32 GB by default, whatever your plan allows. `64` is accepted only on a fleet configured above that ceiling; otherwise a 64 GB computer is only reachable at create time. A value above your per-computer ceiling returns `403`. Omitted leaves RAM alone.
New disk size in GB. **Disk can only grow**; a value below the current size returns `400`. A value below `1` or above this computer's ceiling also returns `400`, with `max_disk_gb` in the body. Omitted leaves the disk alone. Call `GET /computers/{id}/resize` to read the ceiling first.
New bandwidth cap in Mbps. Must be a non-negative number and no higher than the workspace owner's plan limit; both violations return `400`. `0` is accepted but leaves the cap unchanged. Omitted leaves the cap alone.
Idle minutes before the computer suspends itself. `0` means always-on. Omitted leaves the current setting alone. This is applied separately from the four hardware dimensions and is not reflected in `results`. Orgo does not check the value before resizing: a value the host rejects, such as a negative number or more than `43200` (30 days), returns `500` after any hardware change has already applied.
## Response
Returns the effective configuration after the resize attempt.
Effective vCPU count.
Effective RAM in GB.
Effective disk size in GB.
Effective bandwidth limit in Mbps.
The `auto_stop_minutes` you sent, echoed back. Absent when you did not send it.
`true` when the computer's ports or VNC password changed. Re-fetch the computer's connection details before reconnecting.
`true` when the resize restarted the computer, `false` when it applied live. `null` when the host does not report it.
Names of connection values the host reports as changed: any of `api_port`, `novnc_port`, `vnc_password`, `ssh_host_port`, or `ip`. Empty when nothing changed or the host does not report changes.
One entry per attempted dimension: `{ "dimension": "vcpus" | "mem_mb" | "disk_gb" | "bandwidth_mbps", "requested": number, "applied": number, "ok": boolean, "error"?: string }`. This is an array, not an object keyed by dimension. Iterate it and switch on `dimension`. A dimension sent at its current value has no entry. Absent when the request included no hardware dimension.
`true` when at least one dimension failed, `false` otherwise. It is `true` on both `207` and `422`, so use the HTTP status to tell a mixed result from a total failure. Absent when the request included no hardware dimension.
### Status codes
* `200`: every requested dimension applied
* `207`: some dimensions applied and others failed (check `results`)
* `422`: every requested dimension failed
## Example
```bash cURL theme={null}
curl -X PATCH https://www.orgo.ai/api/computers/$COMPUTER_ID/resize \
-H "Authorization: Bearer $ORGO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"vcpus": 4,
"mem_gb": 8,
"disk_size_gb": 30
}'
```
```python Python theme={null}
import requests
response = requests.patch(
f"https://www.orgo.ai/api/computers/{computer_id}/resize",
headers={
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
},
json={"vcpus": 4, "mem_gb": 8, "disk_size_gb": 30}
)
result = response.json()
print(f"Now at {result['vcpus']} vCPU, {result['mem_gb']} GB RAM")
for r in result.get("results", []):
if not r["ok"]:
print(f"{r['dimension']} failed: {r.get('error')}")
```
```javascript JavaScript theme={null}
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/resize`, {
method: 'PATCH',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({ vcpus: 4, mem_gb: 8, disk_size_gb: 30 })
});
const result = await response.json();
console.log(`Now at ${result.vcpus} vCPU, ${result.mem_gb} GB RAM`);
for (const r of result.results ?? []) {
if (!r.ok) console.log(`${r.dimension} failed: ${r.error}`);
}
```
### Response
```json theme={null}
{
"vcpus": 4,
"mem_gb": 8,
"disk_size_gb": 30,
"bandwidth_limit_mbps": 1000,
"connection_rotated": false,
"restarted": null,
"identity_changed": [],
"results": [
{ "dimension": "vcpus", "requested": 4, "applied": 4, "ok": true },
{ "dimension": "mem_mb", "requested": 8192, "applied": 8192, "ok": true },
{ "dimension": "disk_gb", "requested": 30, "applied": 30, "ok": true }
],
"partial": false
}
```
## Errors
| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "vcpus must be 0.5, 1, 2, 4, 8, or 16 cores" }` | `vcpus` is not one of the accepted values. |
| `400` | `{ "error": "mem_gb must be one of 4, 8, 16, 32 GB" }` | `mem_gb` is not one of the accepted values. |
| `400` | `{ "error": "Storage can only be increased (current: 30 GB)" }` | `disk_size_gb` is below the current size. |
| `400` | `{ "error": "disk_size_gb must be between 1 and 28 …", "max_disk_gb": 28 }` | `disk_size_gb` is below `1` or above this computer's ceiling. |
| `400` | `{ "error": "bandwidth_limit_mbps must be a non-negative number" }` | `bandwidth_limit_mbps` is negative or not a number. |
| `400` | `{ "error": "bandwidth_limit_mbps must not exceed 1000" }` | `bandwidth_limit_mbps` is above the plan's limit. Bandwidth over the plan limit is a `400`, not a `403`. |
| `400` | `{ "error": "…", "code": "NOT_RESIZABLE" \| "RESIZE_UNSUPPORTED_OS" }` | The computer is a physical device, or its operating system does not support resize. |
| `400` | `{ "error": "Server address not found for this computer" }` | The computer has no host on record. |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `402` | `{ "error": "Choose a plan to resize this computer.", "code": "TRIAL_RESIZE_UNAVAILABLE" }` | The computer is a trial computer. |
| `402` | `{ "error": "Choose a plan to continue." }` | The computer is a trial computer whose trial has ended. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are not a member of the computer's workspace. |
| `403` | `{ "error": "This workspace is view-only. Ask the owner for write access (workspace_read_only)." }` | You have view-only access to the workspace. |
| `403` | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` | The API key is scoped to a different workspace. |
| `403` | `{ "error": "…", "code": "VCPU_ADDON" \| "PER_COMPUTER_CPU_CAP" \| "PLAN_LIMIT", "upgradeTier": "enterprise" }` | `vcpus` is above your per-computer ceiling, or past the universal per-computer hard cap. `PLAN_LIMIT` means the ceiling is a custom limit on your plan. |
| `403` | `{ "error": "…", "code": "RAM_ADDON" \| "PLAN_LIMIT", "max_ram_gb": 16 }` | `mem_gb` is above your per-computer ceiling, or more than your other computers leave in the account's RAM pool. `PLAN_LIMIT` means the limit is a custom one on your plan. |
| `404` | `{ "error": "Desktop not found" }` | No computer matches the id. |
| `409` | `{ "error": "…", "code": "migrating" }` | The computer is being moved to another host. Retry in a few minutes. |
| `409` | `{ "error": "Computer must be running to resize" }` | The computer is not `running`. |
| `422` | The normal response body, with `partial: true` | Every requested dimension failed. |
| `500` | `{ "error": "…" }` | The resize call itself failed, or the body is not valid JSON. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |
## Read the ceilings before resizing
`GET /computers/{id}/resize` returns this computer's headroom, so you can size a request before making it. It takes the same path parameter and no body.
The computer's current disk size in GB.
Per-computer disk included in the workspace owner's plan.
Storage add-on blocks the owner has purchased.
Those blocks expressed in GB.
The largest `disk_size_gb` this computer can be resized to. It is the plan's base plus whatever add-on storage the owner's other computers have not already claimed, up to 300 GB.
The largest `mem_gb` this computer can be resized to, already bounded by the live-resize limit and by the RAM the owner's other computers leave in the account's pool.
The largest `vcpus` this computer can be resized to.
The largest `bandwidth_limit_mbps` the workspace owner's plan allows.
Pooled RAM the owner has purchased, in GB.
Pooled vCPU the owner has purchased.
`true` when a `mem_gb` change applies without restarting the computer. Absent when the host cannot say, for example when the computer is not running.
A computer that cannot be resized, such as a physical device or an operating system without resize support, returns `200` with a different shape: `resizable: false`, `reason`, `code`, and `current_disk_gb`, `max_disk_gb`, `max_ram_gb`, and `max_cpu` all set to its current size.
```bash theme={null}
curl https://www.orgo.ai/api/computers/$COMPUTER_ID/resize \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```json theme={null}
{
"current_disk_gb": 8,
"base_disk_gb": 8,
"blocks": 1,
"add_on_gb": 20,
"max_disk_gb": 28,
"max_ram_gb": 32,
"max_cpu": 4,
"max_bandwidth_mbps": 1000,
"addon_ram_gb": 0,
"addon_vcpu": 0
}
```
| Status | Body | When |
| - | - | - |
| `401` | `{ "error": "Invalid API key" }` | The Bearer token starts with `sk_` but is not a known Orgo key. |
| `401` | `{ "error": "Authentication required" }` | No `Authorization` header, or a Bearer token that is not an `sk_` key. |
| `402` | `{ "error": "Choose a plan to continue." }` | The computer is a trial computer whose trial has ended. |
| `403` | `{ "error": "You do not have access to this workspace." }` | You are not a member of the computer's workspace. |
| `403` | `{ "error": "This API key cannot access this workspace (workspace_scope_mismatch)." }` | The API key is scoped to a different workspace. |
| `404` | `{ "error": "Desktop not found" }` | No computer matches the id. |
| `500` | `{ "error": "…" }` | The headroom could not be computed. |
| `503` | `{ "error": "Service temporarily unavailable. …" }` | Orgo could not verify the credential because of a server-side fault. The response carries `Retry-After: 5`. Retry after that delay. |
## OpenAPI
````yaml PATCH /computers/{id}/resize
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: Clients
description: >-
Run Orgo for your clients from your own app: a workspace and scoped key
each, billed to you or to them.
- 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}/resize:
patch:
tags:
- Computers
summary: Resize computer
description: >-
Resizes a running computer. Every field is optional. `vcpus` and
`bandwidth_limit_mbps` apply to the live computer. Disk growth applies
live on Linux; a Windows computer restarts in place to grow its disk. A
`mem_gb` change applies live on a Linux computer that supports live
memory resize, and restarts any other computer in place. When
`connection_rotated` is `true`, the ports or VNC password changed:
re-fetch the computer and reconnect. Returns `200` when every dimension
applied, `207` when some failed, and `422` when all failed.
operationId: resizeComputer
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
vcpus:
type: number
enum:
- 0.5
- 1
- 2
- 4
- 8
- 16
description: >-
New vCPU count. Omitted, the CPU is left alone. Capped by
the workspace owner's plan; call `GET
/computers/{id}/resize` for the ceiling.
mem_gb:
type: integer
enum:
- 4
- 8
- 16
- 32
description: >-
New RAM in GB. Omitted, the RAM is left alone. A resize tops
out at the host's boot-memory ceiling, 32 GB by default,
whatever your plan allows: `64` returns `400` unless the
fleet is configured above that ceiling, so a 64 GB computer
is otherwise reachable only at create time. Above your
per-computer ceiling, or more than your other computers
leave in the account's RAM pool, returns `403`. Call `GET
/computers/{id}/resize` for the ceiling.
disk_size_gb:
type: integer
description: >-
New disk size in GB. Omitted, the disk is left alone. Grow
only: a smaller value returns `400`. Below 1 or above this
computer's ceiling also returns `400`, with `max_disk_gb`.
bandwidth_limit_mbps:
type: integer
description: >-
New bandwidth cap in Mbps. Omitted, the cap is left alone.
Must be non-negative and no higher than the owner's plan
limit; either violation returns `400`.
auto_stop_minutes:
type: integer
description: >-
Idle minutes before the computer suspends itself. `0` means
always-on. Omitted, the setting is left alone. Applied
separately from the hardware dimensions and not reflected in
`results`. Orgo does not check the value first: a value the
host rejects, such as a negative number or more than `43200`
(30 days), returns `500` after any hardware change has
already applied.
responses:
'200':
description: Every requested dimension applied
content:
application/json:
schema:
$ref: '#/components/schemas/ResizeResult'
example:
vcpus: 4
mem_gb: 8
disk_size_gb: 30
bandwidth_limit_mbps: 1000
connection_rotated: false
restarted: null
identity_changed: []
results:
- dimension: vcpus
requested: 4
applied: 4
ok: true
- dimension: mem_mb
requested: 8192
applied: 8192
ok: true
- dimension: disk_gb
requested: 30
applied: 30
ok: true
partial: false
'207':
description: Some dimensions applied and others failed. Check `results`.
content:
application/json:
schema:
$ref: '#/components/schemas/ResizeResult'
'400':
description: >-
A value outside the accepted set, a disk shrink or out-of-range disk
(with `max_disk_gb`), a bad or over-plan `bandwidth_limit_mbps`, a
computer that cannot be resized (`NOT_RESIZABLE` for a physical
device, `RESIZE_UNSUPPORTED_OS` for an operating system without
resize), or no host on record.
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/QuotaError'
examples:
vcpus:
summary: Bad vcpus
value:
error: vcpus must be 0.5, 1, 2, 4, 8, or 16 cores
mem:
summary: Bad mem_gb
value:
error: mem_gb must be one of 4, 8, 16, 32 GB
shrink:
summary: Disk shrink
value:
error: 'Storage can only be increased (current: 30 GB)'
disk-ceiling:
summary: Disk above the ceiling
value:
error: >-
disk_size_gb must be between 1 and 28 (8 GB plan + 20 GB
add-on)
max_disk_gb: 28
bandwidth:
summary: Bandwidth over the plan limit
value:
error: bandwidth_limit_mbps must not exceed 1000
not-resizable:
summary: Cannot be resized
value:
error: …
code: NOT_RESIZABLE
no-host:
summary: No host on record
value:
error: Server address not found for this computer
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: >-
The computer is a trial computer, which cannot be resized, or its
trial has ended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
trial-resize:
summary: Trial computer
value:
error: Choose a plan to resize this computer.
code: TRIAL_RESIZE_UNAVAILABLE
trial:
summary: Trial ended
value:
error: Choose a plan to continue.
'403':
description: >-
You are not a member of the workspace, have view-only access, or the
key is scoped to another workspace. Also returned when `vcpus` is
above your per-computer ceiling (`VCPU_ADDON`,
`PER_COMPUTER_CPU_CAP`, or `PLAN_LIMIT` for a custom limit on your
plan, each with `upgradeTier`), or when `mem_gb` is above your
per-computer ceiling or more than your other computers leave in the
account's RAM pool (`RAM_ADDON`, or `PLAN_LIMIT` for a custom limit
on your plan, with `max_ram_gb`).
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/QuotaError'
examples:
no-access:
summary: Not the owner or a member of the workspace
value:
error: You do not have access to this workspace.
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).
scope-mismatch:
summary: The API key is scoped to another workspace
value:
error: >-
This API key cannot access this workspace
(workspace_scope_mismatch).
ram:
summary: RAM above the ceiling
value:
error: >-
This computer needs 32GB RAM, above your current 16GB. Add
RAM to your plan to power it (up to 64GB per computer).
code: RAM_ADDON
max_ram_gb: 16
'404':
$ref: '#/components/responses/NotFound'
'409':
description: The computer is being moved to another host, or is not `running`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
migrating:
summary: Being moved to another host
value:
error: >-
This computer is being moved to another host. Try again in
a few minutes.
code: migrating
not-running:
summary: Not running
value:
error: Computer must be running to resize
'422':
description: >-
Every requested dimension failed. The body is the normal response
with `partial: true`.
content:
application/json:
schema:
$ref: '#/components/schemas/ResizeResult'
'500':
description: The resize call itself failed, or the body is not valid JSON.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: …
'503':
$ref: '#/components/responses/AuthUnavailable'
components:
schemas:
ResizeResult:
type: object
description: >-
The effective configuration after the resize attempt. A dimension that
failed to apply comes back with its previous value.
properties:
vcpus:
type: number
description: Effective vCPU count.
mem_gb:
type: integer
description: Effective RAM in GB.
disk_size_gb:
type: integer
description: Effective disk size in GB.
bandwidth_limit_mbps:
type: integer
description: Effective bandwidth limit in Mbps.
auto_stop_minutes:
type: integer
description: >-
The `auto_stop_minutes` you sent, echoed back. Absent when you did
not send it.
connection_rotated:
type: boolean
description: >-
`true` when the computer's ports or VNC password changed. Re-fetch
`GET /computers/{id}` before reconnecting.
restarted:
type:
- boolean
- 'null'
description: >-
`true` when the resize restarted the computer, `false` when it
applied live, `null` when the host does not report it.
identity_changed:
type: array
items:
type: string
enum:
- api_port
- novnc_port
- vnc_password
- ssh_host_port
- ip
description: >-
Connection values the host reports as changed. Empty when nothing
changed or the host does not report changes.
results:
type: array
description: >-
One entry per attempted hardware dimension. Absent when the request
included no hardware dimension.
items:
type: object
properties:
dimension:
type: string
enum:
- vcpus
- mem_mb
- disk_gb
- bandwidth_mbps
requested:
type: number
applied:
type: number
ok:
type: boolean
error:
type: string
partial:
type: boolean
description: >-
`true` when at least one dimension failed. `true` on both `207` and
`422`. Absent when the request included no hardware dimension.
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.'
responses:
Unauthorized:
description: 'No usable credential. Send `Authorization: Bearer $ORGO_API_KEY`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalid-key:
summary: The key is not one of yours
value:
error: Invalid API key
no-credential:
summary: No key and no session
value:
error: Authentication required
NotFound:
description: No computer with this id on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Desktop not found
AuthUnavailable:
description: >-
Orgo could not verify the credential because of a server-side fault,
such as a database outage. Retry after `Retry-After`. Do not rotate the
key.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: >-
Service temporarily unavailable. The database is not accepting
requests. Retry shortly.
headers:
Retry-After:
description: Seconds to wait before retrying. Always `5`.
schema:
type: string
example: '5'
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.