Desktop

Machines from the agent-browser template (shown as standard) have a Linux desktop with a browser. To watch it, open a machine in the dashboard and choose the Computer tab. Click the desktop to take control. Control goes back to the agent after a minute without input, or 30 seconds after you close the tab.

Let an agent drive it

import { Sandbox } from '@insforge/instabox-sdk'

const sbx = await Sandbox.create('agent-browser')
await sbx.desktop.start({ width: 1280, height: 800 })

await sbx.desktop.open('https://example.com')        // opens the browser
const png = await sbx.desktop.screenshot()           // PNG bytes, e.g. for a vision model
await sbx.desktop.click(640, 400)                    // { button: 'right' }, { double: true }
await sbx.desktop.press(['ctrl', 'l'])               // a key or a chord
await sbx.desktop.type('instabox.sh')                // any text, quotes and unicode included
await sbx.desktop.press('Enter')
await sbx.desktop.scroll({ direction: 'down', amount: 5 })

The other calls are move(x, y), drag([x1, y1], [x2, y2]), cursorPosition(), and status(). start() is safe to call again: it leaves a running desktop alone.

A minimal agent loop

for (let step = 0; step < 20; step++) {
  const png = await sbx.desktop.screenshot()
  const action = await yourModel.nextAction(png)     // { type: 'click', x, y } | { type: 'type', text } | { type: 'done' }
  if (action.type === 'done') break
  if (action.type === 'click') await sbx.desktop.click(action.x, action.y)
  if (action.type === 'type') await sbx.desktop.type(action.text)
}

streamUrl() makes a link to a full-screen viewer of one machine’s desktop. The link works without signing in, and you can embed it in an <iframe>.

const { url, expiresAt } = await sbx.desktop.streamUrl({
  viewOnly: true,        // the default: the viewer can watch, not type or click
  ttlSeconds: 3600,      // 60 to 86400; the default is one hour
})

<iframe src="LINK_URL" width="1280" height="800" style="border:0"></iframe>

One machine. A link opens that machine’s desktop only. It is not an API key and cannot call the API.
View-only is enforced by the server. Keyboard, mouse, and clipboard input from a view-only link never reach the machine. Pass viewOnly: false for a link that can control it.
Expiry stops new connections. A viewer that is already connected stays connected until it leaves.
Revoke ends everything. revokeStreamUrls() invalidates every link for the machine and closes open viewers within a few seconds. Deleting the machine does the same.

Links belong to the machine’s creator. Only the creator, signed in or with their personal key, may make or revoke them. A workspace API key, or another member of the workspace, gets 403 permission_denied. A personal key reaches only the machines of your personal workspace.

Without a link, two ways work, and both work with a workspace key:

Open the desktop over GET /v1/machines/{id}/vnc, VNC in a WebSocket for a viewer such as noVNC. It needs machines:write.
Read the screen with sbx.desktop.screenshot().

Build a service for your own users

Keep your API key on your server, never in a browser. Make a fresh link each time a user opens their desktop, and revoke it when their access ends. Links belong to the creator, so this server runs on the personal key of the account that creates the machines, and it creates them with that key too.

// your server, e.g. Express
app.get('/api/desktop-link', async (req, res) => {
  const machineId = await machineOf(req.user)       // your own user-to-machine mapping
  const sbx = await Sandbox.connect(machineId)
  res.json(await sbx.desktop.streamUrl({ viewOnly: !req.user.canControl, ttlSeconds: 600 }))
})

// when the user's access ends
await (await Sandbox.connect(machineId)).desktop.revokeStreamUrls()

To find machines later with Sandbox.list({ metadata }), tag them with metadata such as { customer: 'acme' }.

Relay the desktop with a workspace key

Your server opens GET /v1/machines/{id}/vnc, a WebSocket, with a key that has machines:write. It passes the VNC stream to your user’s viewer, or sends them sbx.desktop.screenshot() images. Your server then decides who sees what, and revoking means closing that connection.Each user has at most 8 open terminals and desktops at once, and a workspace key counts as its workspace’s owner. A ninth /vnc connection gets a retryable 429 quota_exceeded, so close a viewer’s connection when they leave.

H="X-API-Key: $INSTABOX_API_KEY"
# universal and t3 only (no desktop in the image): install, then wait until installed (about half a minute)
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"action": "install"}' "$INSTABOX_API_URL/v1/machines/m_.../desktop"
for i in $(seq 60); do   # up to 5 minutes; stops early on a failed install, and start then says why
  curl -s -H "$H" -H 'Content-Type: application/json' -d '{"action": "status"}' \
    "$INSTABOX_API_URL/v1/machines/m_.../desktop" | jq -e '.installed or .failed' >/dev/null && break
  sleep 5
done
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"action": "start", "width": 1280, "height": 800}' "$INSTABOX_API_URL/v1/machines/m_.../desktop"
curl -s -H "$H" -H 'Content-Type: application/json' \
  -d '{"viewOnly": true, "ttlSeconds": 3600}' "$INSTABOX_API_URL/v1/machines/m_.../desktop/stream"   # {url, expiresAt}
curl -s -X DELETE -H "$H" "$INSTABOX_API_URL/v1/machines/m_.../desktop/stream"                     # revoke

Over HTTP, start does not install anything. On a template without the desktop (universal, t3), send {"action": "install"} first, poll {"action": "status"} until installed is true (about half a minute), then start. A start that started nothing answers with installed false and a hint naming the next call. Both stream calls belong to the creator, as above: use a personal key with machines:write.

Computer use

An agent that browses and clicks on its own machine.

SDK quick start

Create, run and pause machines from code.

Get started

Use cases

Machines

Access

Security

Account

Reference

Let an agent drive it

Build a service for your own users

Computer use

SDK quick start

​Let an agent drive it

​Share a link to the desktop

​Build a service for your own users

​Start and share the desktop over HTTP

Computer use

SDK quick start

Let an agent drive it

Share a link to the desktop

Build a service for your own users

Start and share the desktop over HTTP