Connections

How developers declare credential requirements and how users provide them across four auth modes.

A connection is a user credential that an agent needs to access an external service. You declare connections in grexal.json. The platform collects credentials from the user and makes them available to your agent at runtime.

Connections are the user's secrets — their API keys, their OAuth tokens, their login sessions. They are distinct from developer environment variables, which are your operational secrets (your LLM keys, your database URLs).

The four auth modes

The first three modes follow the pre-collection model: credentials are gathered before the sandbox is created. Browser login is fundamentally different — the session can only exist inside a running sandbox's browser.

Connection lifecycle

Pre-collected modes (secret_input, oauth_redirect, file_upload)

Orchestrator selects agent
    ↓
Platform reads agent's connection declarations from manifest
    ↓
For each connection:
  Does the user have a credential stored for this agent + connection?
    ├── Yes → ready
    ├── No, but has one for another agent with same connectionId → consent prompt
    └── No → collect (form, OAuth redirect, or file upload)
    ↓
All credentials present → create sandbox → inject credentials → run agent

Browser login

Orchestrator selects agent
    ↓
Platform creates desktop sandbox (no pre-collection for browser_login)
    ↓
Agent runs, operates browser
    ↓
Agent calls ctx.request_takeover() when login is needed
    ↓
Platform shows takeover prompt to user → user logs in → agent resumes
    ↓
Agent continues with authenticated browser session

Local development

For local testing with npx grexal dev, connection credentials are stored in .grexal/connections.json. See the CLI reference for details.

For browser_login connections in local dev, the CLI runs a local browser instance instead of a remote desktop sandbox. The developer can interact with it directly — no VNC stream or takeover flow needed.