Connect with an API key

1. Create a key in Settings → API Keys.
2. Select Authorize and paste the complete grupa_live_… or grupa_test_… key.
3. Choose an endpoint, select Try it out, and then select Execute.

Paste the key without a Bearer prefix. Swagger adds it automatically. The key stays only in this browser tab.

Build a worker that can continue

Persistent workers keep an identity while idle. Enable memory to carry compact context across assignments. Idle identities and pending triggers do not reserve a desktop; execution and waits inside an active run are billed.

• Steer active work: POST /v1/runs/{runId}/feedback. Ordinary feedback continues the run; interrupt: true stops at a safe boundary for follow-up.
• Answer a missing fact: read /questions, then post an answer. Authentication and approvals use their separate interfaces.
• Continue after completion: enable retainContext when creating the run, then use /continue with new work and a new timeout. A new browser starts; source credentials are not copied.
• Wake on time or events: create a persistent worker and use its /automations for fixed intervals, authenticated event triggers, or dependency workflows. Use /turns to queue work while it is busy.
• Teach once: save instructions and named skills on a persistent worker. Update them for future work or override them for one assignment. Playground and the worker editor support editable skills and Markdown/text import. This saves guidance; it does not train model weights.
• Reuse selected access: Playground restores authorized credential selections on retry and worker selection. Use Save access defaults or PATCH /v1/workers/{workerId} with credentialDefaults to save future access. Each assignment checks authorization again; passwords are never returned.
• Receive generated files: use the run's artifact downloads in Playground or /artifacts in the API. Completed app exports and workspace deliverables are retained with the run; a separate Drive upload is unnecessary.
• Call your application: register custom tools with execution: "client" and inputSchema. Claim requests from /tool-calls, execute once, persist results, then submit output.
• Correct an earlier action: /remediations starts linked correction work. Reversal depends on the external system; it is not a guaranteed undo.

The playground exposes feedback, agent questions, and follow-up in Run details. Feedback is not a separate concurrent chat service. Managed desktops are the default execution surface. A local browser needs an explicitly connected client tool; see the local browser instructions below.

Claude Code, CLI and MCP

grupa account guide (MCP grupa_account_guide) explains setup without a key. Agents can launch workers once their host has an authorized credential. grupa keys list requires keys:manage; grupa billing status requires admin. First-key setup still uses Console sign-in. Initial billing authorization and auto-top-up settings require a console administrator. CLI/MCP do not collect cards, return new key secrets or initiate payments; the API/SDK support authorized prepaid payments with purpose: "prepaid" and an idempotency key.

The Grupa stdio MCP adapter exposes the same authorized API for starting work, reading progress, sending feedback, answering questions, continuing work and retrieving files. It manages Grupa runs; it does not itself connect your browser. It is currently distributed from source, not as a public npm release.

With authorized source access and Node.js 22+, follow the CLI and MCP setup guide. Build and install the local package, then have your MCP host launch grupa mcp. Use grupa capabilities for exact schemas. If you cannot access the source, request pilot access before setting up.

Configure GRUPAAI_API_KEY through the host's secret environment and set GRUPAAI_BASE_URL to the intended API (for staging: https://api.staging.grupa.ai). Never paste keys into prompts, task JSON or source files. The adapter is stdio; this reference does not advertise a public HTTP MCP endpoint.

MCP tools include grupa_run_start, grupa_run_trace, grupa_run_feedback, grupa_run_continue, client-tool claim/output and grupa_tool_artifact_upload. The MCP resource grupa://docs/usage explains recovery and lifecycle. Tools preserve the API's tenant, scope, approval, deadline and budget rules.

An attended Claude Code or Codex session can use its own authorized browser tools as the execution surface for client-tool requests. Register the actual tool names and schemas with the run; the host must claim each request, perform the authorized action, and return what it observed. The Grupa MCP server does not automatically invoke other host tools or establish a browser connection. Keep the host session available during the run and follow its browser permissions. Page content sent in results and optional images can reach Grupa and the host's model provider.

grupa_host_connect can register a short-lived, run-scoped MCP process heartbeat. A recent heartbeat means only that the MCP process is alive; it does not verify the agent, browser, user consent, or tool access. The host must allowlist its tool names and retain its claim/result journal. grupa_host_claim, grupa_host_complete, and grupa_host_deliver support attended handoff and retrying delivery without repeating an uncertain action.

Local browser control

A cloud worker can choose actions for an explicitly connected local browser through client-executed tools. You sign in locally; passwords, cookies and browser profiles are not uploaded as run resources. Task page content and retained screenshots or video can reach the cloud. This is browser control, not full-device control.

1. Connect an authorized local browser executor such as Playwright MCP through a local bridge. The tested Windows pilot uses an owned test profile. Customer pairing, personal browser sessions and macOS/Linux are not yet validated.
2. Register that executor's actual tool names and schemas in resources.customTools with execution: "client". Use worker.mode: "single", without persistence, and output.captureSource: "client". Do not start a run before the bridge is ready to service its tools.
3. The bridge reads GET /v1/runs/{runId}/tool-calls, exclusively claims a call, executes it once on the selected browser, retains its result and posts output. An uncertain output retry must not repeat a click or submission.
4. Upload that browser's images with PUT /v1/runs/{runId}/tool-calls/{callId}/artifacts/{artifactId}, bearer authentication, the exclusive X-GrupaAI-Claim-ID and X-GrupaAI-Artifact-Kind (screenshot or recording). The SDK offers context.uploadArtifact; CLI/MCP uploads require an explicit GRUPAAI_EVIDENCE_DIR.
5. Read the run's authenticated /live-preview and /artifacts for local-browser proof. Images are limited to 8 MiB; optional WebM/MP4 recordings to 64 MiB. If requested, screenshot artifact masking happens on the control plane before storage; the original image reaches the control plane. Set output.recording: true only with recording consent. Video is unmasked. Native cloud-desktop input is withheld in client mode.

The local browser template explains how an attended host starts and services a run with its own authorized tools. Open the host-started run by ID in the Playground to watch it; the Playground does not execute its client tools or verify that a browser is connected. The separate local connector remains available through the API for existing integrations. Personal browser sessions and cross-platform operation require independent end-to-end verification.

Current limitation: jobs classified as extraction-only block remote tools to enforce the read-only boundary, so they cannot yet use the connected browser. Do not assume every read-only research task can run through this connection.