Connections

How developers declare credential requirements and how users provide them.

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).

Auth modes

Mode	Status	What the user provides	How it reaches the agent
Secret Input	Supported	API keys, passwords, tokens via a form	`ctx.connect()`
OAuth Redirect	Not yet implemented	Authorization via OAuth flow	`ctx.connect()` (access token)
File Upload	Not yet implemented	A config file, key file, or certificate	File at `/tmp/grexal/{connection_id}/`
Browser Login	Not yet implemented	Interactive login in a live browser	Session lives in the sandbox's browser

Only secret_input is live today. Agents that declare oauth_redirect, file_upload, or browser_login will still deploy, but the platform will refuse to run them with a clear error in the Run dialog until those modes ship.

Secret Input lifecycle

Credentials are per-user and reusable across agents: you enter your Vercel AI Gateway key once, and any agent that declares a vercel_ai_gateway connection can request access. Each agent needs an explicit per-user grant before it can read the credential — think of it like OAuth's "allow this app" step, but for stored keys.

User clicks Run on an agent
    ↓
Run dialog reads the agent's declared connections
    ↓
For each connection:
  Is a credential with this connectionId saved for the user?
    ├── No → show fields, user enters values, auto-grant this agent on save
    ├── Yes, and this agent already has a grant → ready
    └── Yes, but no grant for this agent → show consent prompt
    ↓
All connections ready → run starts → sandbox receives GREXAL_CONNECTIONS env

Users can review and revoke grants, overwrite field values, or delete entire connections from /dashboard/connections.

Runtime contract

Inside the sandbox the SDK reads credentials from the GREXAL_CONNECTIONS env var, which is a JSON object of the shape:

{
  "<connection_id>": {
    "<field_name>": "<plaintext_value>"
  }
}

Your agent code never touches the env var directly — call ctx.connect(connectionId) and then .get(fieldName).

Local development

For local testing with npx grexal dev, connection credentials live in .grexal/connections.json in the agent directory. See secret_input for the file format.