Computer use

The per-user cloud workspace Prime uses to work on websites and run code, how a user takes over the browser through a handoff, how to watch a task's browser, and the controls and usage endpoints.

Computer use

Each user has a persistent cloud workspace: a Linux computer with Chrome, a desktop, a shell and a home directory. Prime uses it for work that has no API, such as filing a form on a government portal, pulling a report out of a vendor site, or writing and running code. When a site needs the user, for a sign-in or a one-time code, Prime opens a handoff, the user takes over the live browser, and the task continues once they hand it back. This guide follows Ava as she files the HVAC repair permit for Jane Rivera's task "Collect three vendor quotes for the lobby HVAC repair".

How it works

 Task needs a site with no API
        │
        ▼
 Prime opens a tab in Jane's workspace browser ──► browses, clicks, types, reads
        │
        ├── sign-in wall, MFA or payment page
        │        │
        │        ▼
        │   Handoff opens, the task pauses, Jane is asked to take over
        │        │
        │        ▼
        │   Jane drives the live browser, then hands back ──► the task resumes
        │
        ▼
 Files saved to Jane's Files, screenshots in the task feed,
 outbound actions through approvals

What Prime does in the workspace

• Browses and acts on sites. Prime navigates, reads pages, clicks, types, selects and scrolls, and posts screenshots to the task's activity feed so the user can follow progress.
• Runs code. Shell commands run with Python 3, Node.js, git, the GitHub CLI, curl and jq preinstalled. Each command runs for up to 60 seconds.
• Produces files. Documents, spreadsheets, presentations, PDFs, charts and data files. Finished files are saved to the user's Files, where they appear as deliverables on the task.
• Delegates coding jobs. Prime hands a coding task to Claude Code or Codex in the workspace. The coding agent clones the repository, creates a branch, implements and tests the change, and opens a pull request. Prime relays any question the coding agent asks mid-run. This requires the user's GitHub connection and a coding connection (an API key, or a Claude subscription for Claude Code).

Prime never asks for passwords in chat. When it reaches a sign-in, it opens a handoff.

What persists

The workspace starts again on the next task that needs it. The first start after an idle period takes longer. Keep anything a user should keep in their Files.

Handoffs

Ava has the vendor quotes and now needs to file the repair permit on the county permit portal. The portal requires Jane's sign-in, so Ava opens a handoff and the task pauses. The hosted app runs this flow for Jane. To build it into your own app, use the steps below. Every workspace call is user-scoped: send X-User-Email with an account-wide key, or use a user-scoped token.

1. List what Prime is waiting on.

   curl https://api.agnt.ai/workspace/handoff/active \
     -H "Authorization: Bearer $AGNT_API_KEY" \
     -H "X-User-Email: [email protected]"
   

   {
     "ok": true,
     "handoffs": [
       {
         "id": "6702ca26d7e8f9a0b1c2d3e4",
         "taskId": "6702c4b0c9d8e7f6a5b4c3d2",
         "actionType": "login",
         "prompt": "Sign in to the county permit portal so I can file the HVAC repair permit for the lobby.",
         "targetUrl": "https://permits.harborcounty.gov/login",
         "status": "pending",
         "expiresAt": "2026-11-03T16:41:09.000Z",
         "createdAt": "2026-11-02T16:41:09.000Z"
       }
     ],
     "handoff": {
       "id": "6702ca26d7e8f9a0b1c2d3e4",
       "taskId": "6702c4b0c9d8e7f6a5b4c3d2",
       "actionType": "login",
       "status": "pending"
     }
   }
   

   handoffs lists every open handoff, oldest first. handoff is the newest on its own.

2. Start the live session and open sessionUrl for Jane.

   curl https://api.agnt.ai/workspace/handoff/6702ca26d7e8f9a0b1c2d3e4/session \
     -X POST \
     -H "Authorization: Bearer $AGNT_API_KEY" \
     -H "X-User-Email: [email protected]"
   

   {
     "ok": true,
     "sessionUrl": "https://workspace-proxy.agnt.ai/session/6702b1e8f9a0b1c2d3e4f5a6?token=...",
     "control": {
       "generation": 4,
       "handoffId": "6702ca26d7e8f9a0b1c2d3e4",
       "operator": "user"
     }
   }
   

   sessionUrl carries a single-use token. Open it once, for the user. If the page reloads, call session again for a fresh URL. While Jane has control, Prime cannot act in the browser.

3. Hand back when Jane has signed in.

   curl https://api.agnt.ai/workspace/handoff/6702ca26d7e8f9a0b1c2d3e4/complete \
     -X POST \
     -H "Authorization: Bearer $AGNT_API_KEY" \
     -H "X-User-Email: [email protected]"
   

   { "ok": true, "taskId": "6702c4b0c9d8e7f6a5b4c3d2" }
   

   Control returns to Ava, and the task resumes on the signed-in portal. The sign-in stays in Jane's browser profile for later tasks.

Outcomes

If Jane cannot sign in now, defer the handoff:

curl https://api.agnt.ai/workspace/handoff/6702ca26d7e8f9a0b1c2d3e4/defer \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "message": "After 5pm, I am on site until then.", "deferMinutes": 120 }'

The response is { "ok": true, "deferredUntil": "2026-11-02T18:43:00.000Z" }.

Unanswered handoffs expire at expiresAt, and an idle session ends on its own. Handoff calls return 409 when control of the computer changed in the meantime. Refresh the handoff list and retry.

Resolve several handoffs

POST /workspace/handoff/resolve ends the user's turn and reports an outcome for each handoff in one call.

curl https://api.agnt.ai/workspace/handoff/resolve \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "handoffId": "6702ca26d7e8f9a0b1c2d3e4", "outcome": "completed", "note": "Signed in to the permit portal." }
    ]
  }'

The response lists the closed handoffs in resolved.

Open the browser without a request

A user can open their workspace browser on their own, for example to sign in to the permit portal ahead of time. POST /workspace/handoff/launch returns { ok, handoffId, status: "starting" }. Poll GET /workspace/handoff/active until that handoff is ready, then call session. Its taskId is null.

Sign-in forms

When the hosted app identifies a sign-in form with confidence on a verified site, it can offer the user a form in place of the live browser. What the user types there is encrypted for the workspace and filled in directly. It is never visible to the assistant or to the AGNT API.

Handoff fields

Watch a task's browser

GET /workspace/watch returns a still image of the tab Prime is using for one of the user's tasks. It does not take control and never starts the workspace. Poll it for a live view.

curl "https://api.agnt.ai/workspace/watch?taskId=6702c4b0c9d8e7f6a5b4c3d2" \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]"

Usage and cleanup

GET /workspace/profile returns rolling usage, or profile: null until the workspace has run.

curl https://api.agnt.ai/workspace/profile \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]"

{
  "ok": true,
  "profile": {
    "lastActiveAt": "2026-11-02T16:52:30.000Z",
    "updatedAt": "2026-11-02T16:55:00.000Z",
    "peakMemoryBytes": 1879048192,
    "avgMemoryBytes": 1073741824,
    "memoryLimitBytes": 4294967296,
    "currentDiskBytes": 3221225472,
    "diskQuotaBytes": 21474836480,
    "avgCpuLoadAvg": 0.42,
    "totalActiveMinutes": 37,
    "topMcpSlugs": []
  }
}

peakMemoryBytes is the highest memory use in the last 24 hours. GET /workspace/snapshots?limit=48 returns point-in-time usage, oldest first, captured at most every 5 minutes while the workspace runs and kept 30 days. limit is at most 288.

POST /workspace/cleanup frees space without touching the user's own files. It starts the workspace if it is not running.

curl https://api.agnt.ai/workspace/cleanup \
  -X POST \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "X-User-Email: [email protected]" \
  -H "Content-Type: application/json" \
  -d '{ "scope": "cache" }'

Controls

Three switches govern computer use. Each is "on", "off" or null (inherit), with a *Locked sibling that pins the value so a user's own preference is ignored.

workspaceHandoffDomains narrows where a handoff may go: { allowlist, blocklist } of bare origins (harborcounty.gov, not URLs). An empty allowlist allows every origin not on the blocklist. Lists only tighten across tiers: allowlists intersect and blocklists add up. It has no lock.

Settings resolve from your account down to each team. An "off" at the account or at any of a user's teams wins. With no setting anywhere, each switch is on. Browser automation also requires the browser skill to be installed on your account. Account-wide settings are set in the AGNT console.

Limit the Maintenance team to handoffs on the county permit portal, and lock the shell off:

curl https://api.agnt.ai/teams/6702ab9fd4e5f6a7b8c9d0e1/settings/resource-permissions \
  -X PATCH \
  -H "Authorization: Bearer $AGNT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": {
      "workspaceCli": "off",
      "workspaceCliLocked": true,
      "workspaceHandoffDomains": { "allowlist": ["harborcounty.gov"] }
    }
  }'

A team admin or an account-wide key can set team settings. A lock needs a value: "workspaceCliLocked": true with no workspaceCli returns 400.

POST /teams/:teamId/settings/security-preset with { "preset": "restricted" } turns off and locks MCP servers (including custom ones), the workspace shell, browser automation and workspace handoff for the team in one call. Without the shell and browser, Prime cannot act on services that have no API. Editing any switch by hand after applying the preset clears the preset label. See Organizations and teams for how team policy combines with the rest of your settings.

Security

• Per-user isolation. Each user's workspace runs in its own container, and user files are kept in per-user directories. A session URL is valid only for the user it was issued to.
• No public IP. Workspaces accept no inbound connections from the internet. The live view reaches the user through an authenticated proxy using the single-use session token.
• Unprivileged user. Your commands, files and the browser run as an unprivileged user.
• A locked-down browser. Chrome's password manager, autofill, sync and browser sign-in are off. Prime can open only http, https and data URLs. Local files and cloud metadata endpoints are blocked.
• Approvals apply. Outbound actions Prime takes follow the user's autonomy settings, and page content is treated as untrusted. See Tasks and approvals.

See Security for the platform-wide guarantees.

Endpoints

Limits

• One browser per user. Tasks share it, each in its own tab, and a handoff gives the user the whole browser until they hand back.
• Shell commands run for at most 60 seconds each. Longer work, such as coding jobs, runs in the background and Prime checks on it.

See also

• Tasks and approvals
• Organizations and teams
• Security
• API reference