Set Up Computer Control
Add a cloud computer to a workspace and embed a short-lived live viewer with explicit human takeover.
Add Computer Control when an agent needs a visible desktop. You need a workspace, an end user, an enabled computer-control alias and available Sandbox time. See Computer Control for control, persistence and capacity behavior.
Configure the app
From your backend:
const workspaceId = '550e8400-e29b-41d4-a716-446655440000'
await client.workspaces.addIntegration(workspaceId, {
integrationName: 'computer-control',
alias: 'computer',
connectionStrategy: 'per_user',
})
const started = await client.actions.execute('computer-control', 'start_session', {
workspaceId,
endUserId: 'customer_123',
integrationAlias: 'computer',
input: { durationSeconds: 600 },
})Create the end user through your normal end-user setup. The external ID must come from your application's authenticated user context. Do not let a browser choose another customer's identity.
Inspect the action result and retain its sessionId. A matching approval rule may return an approval request instead of starting a computer. Do not treat that response as a running session.
Let an agent work
The configured actions are available to the workspace's MCP server. In Code Mode, inspect weavz.computer before calling it:
return await weavz.computer.screenshot({ sessionId })Use screenshot, click, type, key, scroll, file and shell actions as the task requires. show_live_view returns a watch link. request_human pauses the agent and asks a person to take over. resume checks whether control was returned; it cannot override human control or a paused session.
Issue a human control link
Your backend must authenticate the person and authorize access to the particular computer before calling this API. A Weavz API key represents your backend, so Weavz cannot infer whether your own user is entitled to another user's session.
const access = await client.computerSessions.createAccess(sessionId, {
workspaceId,
endUserId: 'customer_123',
role: 'control',
ttlSeconds: 300,
frameOrigin: 'https://app.example.com',
})Use role: 'watch' when the person should only observe. Send viewerUrl privately to the authorized browser. Never put a control link in a model prompt, tool result, analytics event or application log. A control link is a short-lived credential.
A signed-in dashboard user can request access to their own computer; Project owners and admins can also grant access within their Project. Ordinary MCP tokens cannot mint human control links.
Embed the live view
Serve a small authenticated backend endpoint that returns a viewer URL for the current user and session. Render that URL in an iframe with an accessible title:
<iframe title="Live agent computer" src="VIEWER_URL_FROM_YOUR_BACKEND"></iframe>frameOrigin must be the exact HTTPS origin of the page hosting the iframe, with no path, credentials, query or wildcard. Only the API-key-authenticated backend can register it. The embedding permission expires with the access link. Request fresh access through your backend when reconnecting after expiry; the parent URL cannot widen access through query parameters.
The viewer keeps the capability out of request URLs and removes it from the address bar. Your application must preserve the returned fragment when initially opening the URL. A watch link can be opened directly; taking control still requires separate authorization.
The viewer shows who has control, connection failures and checkpoint problems. Take over interrupts the agent; Return control explicitly lets it continue. Losing the controller connection leaves the session paused.
Finish and recover
End a session through end_session or the viewer's End session control. Save output under /workspace first. Browser sign-ins and open applications are discarded.
If startup fails, inspect the error before starting another session. Capacity may remain reserved while a shutdown is being confirmed. If a live view disconnects, reconnect with a fresh access link; do not silently grant control to the agent. If a checkpoint fails, show that failure and retain the last saved output rather than claiming the latest files were saved.