> ## 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.
# Start computer
> Boot a stopped computer.
Starts a computer that is `frozen` or `stopped`. A `frozen` computer's archived disk is restored, including files, installed software, and configuration, and it cold-boots on a host chosen for it. A `stopped` computer whose virtual machine is still on its host is booted there from its own disk instead.
A computer started from its archive gets a **new `instance_id`**, and it can land on a different host with a different address and ports. Orgo asks for the previous ports and VNC password back, but does not guarantee them. Re-fetch [`GET /computers/{id}`](/api-reference/computers/get) afterwards. Only the disk is restored: processes and other in-memory state from before the stop are gone. The call can take considerably longer than a normal request while the saved disk is fetched and the computer boots.
## Path parameters
Computer UUID or `instance_id`. Both resolve to the same computer. A `frozen` computer has no `instance_id`, so address it by UUID.
## Query parameters
`true` or `false`. `true` returns `202` immediately instead of waiting, as described in [Return immediately and poll](#return-immediately-and-poll). Any other value returns `400`.
## Response
`true` when the start succeeded or the computer was already running.
Present and `true` only when the computer's record said `stopped` but the computer was still running on its host, so the record was corrected instead of a second copy being booted. No boot happened.
Present and `true` only when a `stopped` computer was booted on its existing host from its own disk, rather than restored from its archive.
Starting is idempotent for an already-`running` computer: it returns `{ "success": true }` and changes nothing. Only `frozen` and `stopped` computers are startable. Every other status, including `suspended`, returns `409`.
## Example
```bash cURL theme={null}
curl -X POST https://www.orgo.ai/api/computers/$COMPUTER_ID/start \
-H "Authorization: Bearer $ORGO_API_KEY"
```
```python Python theme={null}
import requests
response = requests.post(
f"https://www.orgo.ai/api/computers/{computer_id}/start",
headers={"Authorization": f"Bearer {api_key}"}
)
if response.json().get("success"):
print("Computer starting")
```
```javascript JavaScript theme={null}
const response = await fetch(`https://www.orgo.ai/api/computers/${computerId}/start`, {
method: 'POST',
headers: { 'Authorization': `Bearer ${apiKey}` }
});
const { success } = await response.json();
if (success) console.log('Computer starting');
```
### Response
```json theme={null}
{
"success": true
}
```
## Errors
| Status | Body | When |
| - | - | - |
| `400` | `{ "error": "Expected a JSON object with an optional boolean async field." }` | The body is not empty and is not a JSON object with an optional boolean `async`. |
| `400` | `{ "error": "async must be true or false" }` | The `async` query parameter is neither `true` nor `false`. |
| `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": "Your plan does not include running computers. Upgrade to start this computer.", "code": "upgrade_required" }` | The workspace owner's plan no longer funds running computers. The archived disk is kept; upgrading re-enables start. For a `stopped` computer booted on its host, the message ends "Upgrade to restart this 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. |
| `404` | `{ "error": "Desktop not found" }` | No computer matches the id. |
| `409` | `{ "error": "Computer cannot be started (status: creating)", "code": "not_startable" }` | The computer is in a status other than `frozen`, `stopped`, or `running`. |
| `409` | `{ "error": "No saved state found for this computer", "code": "NO_SAVED_STATE" }` | The computer has no archived disk to restore. |
| `409` | `{ "error": "…", "code": "SAVED_STATE_OUTDATED" }` | The computer's virtual machine is gone and its newest archive is older than its last disk, so starting would lose work. Contact support. |
| `409` | `{ "error": "This computer is paused. Resume it to continue.", "code": "COMPUTER_SUSPENDED" }` | A `stopped` computer turned out to be suspended on its host. |
| `409` | `{ "error": "…", "code": "NOT_ON_HOST" }` | The computer has no archive to start from (a macOS, iOS, or Android computer, or a device) and its host no longer has it. Contact support. |
| `409` | `{ "error": "…", "code": "DEVICE_LIFECYCLE_UNSUPPORTED" }` | The computer runs on a dedicated machine Orgo manages directly. Contact support. |
| `409` | `{ "error": "This Mac is managed by Orgo. Ask support to release it.", "code": "pool_mac_release_required" }` | The computer is a Mac that has been released back to Orgo. |
| `409` | `{ "error": "…", "code": "migrating" }` | The computer is being moved to another host. Retry in a few minutes. |
| `409` | `{ "error": "A different operation is already in progress.", "code": "OPERATION_IN_PROGRESS" }` | A stop is still pending for this computer. |
| `409` | `{ "error": "The previous operation was interrupted and is being checked. Try again in a few minutes.", "code": "OPERATION_NEEDS_REVIEW" }` | An earlier start or stop is in `needs_review`. |
| `500` | `{ "error": "…", "code": "…" }` | The start failed for an unclassified reason. Check the operation status before retrying; an uncertain result is fenced as `needs_review`. |
| `503` | `{ "error": "…", "code": "HOST_UNREACHABLE" }` | The host of a `stopped` computer did not answer. Retry in a minute. |
| `503` | `{ "error": "…", "code": "…" }` | No host could take the boot. `code` is one of `golden_unavailable`, `frozen_disabled`, `NO_TEMPLATE_HOST`, `FLEET_CAPACITY_FULL`, `OS_UNAVAILABLE`, `DEDICATED_CAPACITY_FULL`, or `GPU_HOST_UNAVAILABLE`. |
| `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. |
A failure that happens while the operation runs also carries `operation_id` and `poll_url` in its body.
## Return immediately and poll
Send `?async=true`, a JSON body `{ "async": true }`, or the header `Prefer: respond-async` to return `202` immediately. The response includes `id` (the computer UUID), `status` (`starting` or `stopping`), `operation_id`, `operation`, and `poll_url`, plus `Location` and `Retry-After: 2` headers. Repeating the same action while it is pending returns the same operation. An opposite action returns `409` with code `OPERATION_IN_PROGRESS`.
Fetch `poll_url` with the same authentication until the operation reports `succeeded`, `failed`, or `needs_review`. A `needs_review` result means the host's outcome is uncertain. Orgo checks the computer and settles the operation on its own; until then, a new start or stop returns `409` with code `OPERATION_NEEDS_REVIEW`. See [Get computer operation](/api-reference/computers/operation).
Without the async option the request waits for completion, up to 300 seconds. If still pending, it returns `202` and the same polling fields. Both modes preserve disk data; stopping discards live processes and memory, and starting cold-boots with potentially different connection details.
## OpenAPI
````yaml POST /computers/{id}/start
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}/start:
post:
tags:
- Computer Lifecycle
summary: Start computer
description: >-
Starts a `frozen` or `stopped` computer. A `frozen` computer's archived
disk is restored and it cold-boots on a host chosen for it, with a new
`instance_id` and possibly a new address and ports. A `stopped` computer
still on its host is booted there. Starting an already `running`
computer returns `{ "success": true }` and changes nothing. Accepts the
computer UUID or its `instance_id`.
operationId: startComputer
parameters:
- name: id
in: path
required: true
description: Computer ID
schema:
type: string
- name: async
in: query
required: false
description: >-
`true` returns `202` immediately instead of waiting. Omitted, the
request waits up to 300 seconds. Any value other than `true` or
`false` returns `400`.
schema:
type: string
enum:
- 'true'
- 'false'
default: 'false'
- name: Prefer
in: header
required: false
description: Send `respond-async` for the same effect as `?async=true`.
schema:
type: string
enum:
- respond-async
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
async:
type: boolean
default: false
description: >-
`true` returns `202` immediately. An empty body is accepted;
any body that is not a JSON object with an optional boolean
`async` returns `400`.
responses:
'200':
description: Started, or already running
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: true
reconciled:
type: boolean
description: >-
Present and `true` only when the record said `stopped` but
the computer was still running on its host, so the record
was corrected. No boot happened.
restarted:
type: boolean
description: >-
Present and `true` only when a `stopped` computer was
booted on its existing host from its own disk.
example:
success: true
'202':
description: >-
Accepted. Returned immediately with `?async=true`, a body `{
"async": true }`, or `Prefer: respond-async`, and by a synchronous
request still pending after 300 seconds. Poll `poll_url` with the
same credential until the operation reports `succeeded`, `failed`,
or `needs_review`. Repeating the same action while it is pending
returns the same operation.
headers:
Location:
description: The `poll_url`.
schema:
type: string
Retry-After:
description: Always `2`.
schema:
type: string
example: '2'
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The computer UUID.
status:
type: string
enum:
- starting
- stopping
operation_id:
type: string
format: uuid
operation:
$ref: '#/components/schemas/ComputerOperation'
poll_url:
type: string
example:
id: a3bb189e-8bf9-3888-9912-ace4e6543002
status: starting
operation_id: 5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
operation:
id: 5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
desktop_id: a3bb189e-8bf9-3888-9912-ace4e6543002
action: start
status: queued
result: null
error: null
created_at: '2026-04-07T10:35:00Z'
updated_at: '2026-04-07T10:35:00Z'
poll_url: >-
/api/computers/a3bb189e-8bf9-3888-9912-ace4e6543002/operations/5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
poll_url: >-
/api/computers/a3bb189e-8bf9-3888-9912-ace4e6543002/operations/5f0c7a1e-2b3d-4c5e-8f9a-0b1c2d3e4f5a
'400':
description: >-
The body is not empty and is not a JSON object with an optional
boolean `async`, or the `async` query parameter is neither `true`
nor `false`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
body:
summary: Bad body
value:
error: >-
Expected a JSON object with an optional boolean async
field.
query:
summary: Bad query value
value:
error: async must be true or false
'401':
$ref: '#/components/responses/Unauthorized'
'402':
description: >-
The owner's plan no longer funds running computers (the archived
disk is kept), or the computer is a trial computer whose trial has
ended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
upgrade:
summary: Plan does not fund running computers
value:
error: >-
Your plan does not include running computers. Upgrade to
start this computer.
code: upgrade_required
trial:
summary: Trial ended
value:
error: Choose a plan to continue.
'403':
$ref: '#/components/responses/AccessDenied'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: The start was refused.
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
examples:
not-startable:
summary: Not `frozen`, `stopped`, or `running`
value:
error: 'Computer cannot be started (status: creating)'
code: not_startable
no-saved-state:
summary: No archived disk
value:
error: No saved state found for this computer
code: NO_SAVED_STATE
outdated:
summary: Newest archive older than the last disk. Contact support.
value:
error: >-
This computer’s latest disk is not in its saved copy, so
starting from that copy would lose recent work. Contact
support to recover it.
code: SAVED_STATE_OUTDATED
suspended:
summary: A `stopped` computer was suspended on its host
value:
error: This computer is paused. Resume it to continue.
code: COMPUTER_SUSPENDED
not-on-host:
summary: >-
No archive to start from, and the host no longer has the
computer. Contact support.
value:
error: >-
This macOS computer is no longer running on its host, so
Start can’t reach it. Contact support and we’ll bring it
back.
code: NOT_ON_HOST
device:
summary: >-
Runs on a dedicated machine Orgo manages directly. Contact
support.
value:
error: >-
Start isn’t available for this computer. It runs on a
dedicated machine that Orgo manages directly, so contact
support and we’ll do it for you.
code: DEVICE_LIFECYCLE_UNSUPPORTED
pool-mac:
summary: A Mac released back to Orgo
value:
error: This Mac is managed by Orgo. Ask support to release it.
code: pool_mac_release_required
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
in-progress:
summary: A stop is still pending
value:
error: A different operation is already in progress.
code: OPERATION_IN_PROGRESS
needs-review:
summary: An earlier operation is in `needs_review`
value:
error: >-
The previous operation was interrupted and is being
checked. Try again in a few minutes.
code: OPERATION_NEEDS_REVIEW
'500':
description: >-
The start failed for an unclassified reason. Check the operation
status before retrying; an uncertain result is fenced as
`needs_review`.
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
example:
error: …
code: …
'503':
description: >-
The host of a `stopped` computer did not answer
(`HOST_UNREACHABLE`), no host could take the boot
(`golden_unavailable`, `frozen_disabled`, `NO_TEMPLATE_HOST`,
`FLEET_CAPACITY_FULL`, `OS_UNAVAILABLE`, `DEDICATED_CAPACITY_FULL`,
or `GPU_HOST_UNAVAILABLE`), or the credential could not be verified
because of a server-side fault (carries `Retry-After: 5`). Retry.
content:
application/json:
schema:
type: object
properties:
error:
type: string
code:
type: string
operation_id:
type: string
description: >-
Present on a failure that happened while the operation
ran.
poll_url:
type: string
examples:
host:
summary: Host did not answer
value:
error: >-
Orgo couldn’t reach this computer’s host, so Start didn’t
go through. Try again in a minute, or contact support if
it keeps happening.
code: HOST_UNREACHABLE
capacity:
summary: No host could take the boot
value:
error: …
code: FLEET_CAPACITY_FULL
auth:
summary: Credential could not be verified
value:
error: >-
Service temporarily unavailable. The database is not
accepting requests. Retry shortly.
headers:
Retry-After:
description: Present, as `5`, on the credential-verification fault.
schema:
type: string
components:
schemas:
ComputerOperation:
type: object
properties:
id:
type: string
format: uuid
desktop_id:
type: string
format: uuid
action:
type: string
enum:
- start
- stop
status:
type: string
enum:
- queued
- running
- succeeded
- failed
- needs_review
result:
type:
- object
- 'null'
description: 'On success, such as `{ "success": true }`.'
error:
type:
- object
- 'null'
description: 'On failure: `error`, `code`, and `status`.'
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
poll_url:
type: string
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.
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
AccessDenied:
description: >-
You are not the owner or a member of the computer's workspace, you have
view-only access, or the API key is scoped to another workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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).
NotFound:
description: No computer with this id on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Desktop not found
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.