Cloud computers — a coding agent on the person's own computer in the cloud

A cloud computer is a computer that belongs to one person: a protected virtual machine in an AWS Nitro enclave, running a coding agent (OpenCode), with its files saved encrypted. Only that person can open it — not your server, not Witbitz. wb.computers lets your page make one, open it, run the agent's sessions, answer its approvals and questions, and read the files it changes.

Part of the SDK · every call: the reference.

The whole thing

const box = await wb.computers.create({ name: 'Build box' })   // model keys from the person's account, capped
const computer = await wb.computers.open(box.id, { onStep: (s) => show(s) })
const s = await computer.sessions.create({ dir: '/work' })
computer.on('message.part.updated', (e) => render(e))
computer.on('permission.asked', async (e) => {
  if (await askThePerson(e)) await computer.approvals.answer(e.properties.id, 'once', { session: e.properties.sessionID })
})
await computer.sessions.prompt(s.id, 'Add a test for the parser', { model: 'trustedrouter/deepseek/deepseek-v4-flash' })
await computer.close()                                         // a last save; its hours stop counting

The account must be on (wb.backup.enable or restore, Accounts) and the person signed in (People).

Make one

wb.computers.create({ name?, keys?, egress?, browsePrivate? }) adds a computer to the person's account and returns { id, name, cloud: true, version, egress }. Nothing starts until you open it.

• Model keys come from the person's account, capped, unless keys brings their own ({ trustedRouter, tinfoil?, github? }; keys_refused if a key does not work).
• What it may reach (egress): { mode: 'none' } (the default — only the models and the relay), 'trusted' (package registries and GitHub, a list that ships in the image and is measured with it), or 'custom' with hosts. There is no unrestricted mode.
• Private browsing (browsePrivate: true): the agent has its own web browser on the computer; with this on, the browser forgets cookies, logins and history every time the computer opens or closes, so nothing it signed into outlives the session. Off, the browser keeps them between openings, as a person's own browser would.

wb.computers.list() gives the account's computers, newest first — never a secret. wb.computers.remove(id) closes it, cancels its account keys and removes it from the account.

Open it

wb.computers.open(id, { onStep?, images?, onNewImage? }) starts or wakes the computer, checks it, hands it the person's keys sealed to it, and connects. onStep hears requesting, starting, verifying, opening, connecting — show them; a cold start takes a while.

Opening checks the computer before anything is sent. The enclave and its key guard must run images Witbitz has published (/cloud-claim.json), proven by the enclave's attestation. When Witbitz publishes a new image, images: 'auto' (the default) accepts it; 'ask' calls onNewImage(pcr0, role) — return true to accept. An image Witbitz has not published is refused (attestation); the person saying no is declined.

computer.close() makes a last save and stops it; its hours stop counting.

Sessions, approvals and files

An open computer (id, name, status) is the agent's side of the computer:

• Sessions — computer.sessions.list / create({ dir?, title? }) / messages(id) / prompt(id, text, { model?, agent? }) / abort / rename / remove / todo / status. model is 'provider/model'.
• Approvals — the agent asks before it runs a command or edits a file, as its mode says. computer.approvals.pending() and .answer(id, 'once' | 'always' | 'reject', { session?, message? }); a reject with a message tells the model what to do instead ("stop and ask me"). An older connector that does not take the message refuses it; when you pass the session, the SDK then sends the refusal without it.
• Questions — computer.questions.pending() / answer(id, answers) / dismiss(id).
• Files — computer.files.list(path?) / changes() / diff().
• The agent's browser — computer.browser.status(): the computer's own report of its browser, null until the agent opens one. The person watches it and takes the controls in the Witbitz app's Code section.
• Events — computer.on(type, fn) with OpenCode's event types (message.part.updated, permission.asked, session.idle, or '*'); it returns the function that stops listening.

What your page can reach is limited. Every call goes through the computer's connector over a sealed relay, and the connector serves only these routes — sessions, approvals, questions, files and diffs. There is no shell route: your page cannot run a command on the computer except by asking the agent, under the person's approvals.

Who pays

The person does. A computer's hours are charged to the person's own AWS key, minted at its first opening with its private half kept in their sealed account — about 23 credits an hour against a monthly allowance. wb.computers.usage() reads this month (in dollars: show credits, 100 credits = $1), or null before the first opening. Over the allowance, open rejects with aws_limit and resetsAt.

Where the keys live

With the person. The workspace's key half, the relay secret and the model keys sit in their sealed account and, while your page works with the computer, in its memory — as room keys do without a vault. A computer made in your app is listed in your app's account only.

Vault mode (the keys stay in the vault, Where the keys live) is not available for cloud computers yet: every call rejects with vault_mode.

Errors carry code: not_enabled, sign_in_required, not_found, keys_refused, aws_limit, attestation, declined, vault_mode.

The Witbitz Spaces app's Code section is built on cloud computers.

Machine-readable source: sdk-computers.md · Generated 2026-10-27T07:05:42Z · build f301388c · every doc in one fetch: llms-full.txt (HTML)