Connection Wizard: Technical Reference

Key files

How state is stored

Wizard completion state is stored per-tenant in the database. The wizard_state column in the tenants table tracks which steps are complete as a JSON bitmask or step index. Step skips are allowed for Steps 4–8.

// Typical shape stored in tenants.wizard_state
{
  completedSteps: [1, 2, 3, 4],
  gatewayUrl: "http://localhost:18789",
  smartRoutingEnabled: true
}

How gateway checks work

POST /api/gateway/ping — forwards a health-check to the user-supplied gateway URL.

// Request
{ gatewayUrl: string }

// Response 200
{ ok: true, latencyMs: number }

// Response 400/503
{ ok: false, error: string }

The ping endpoint does not store the URL; it only validates reachability. URL is stored client-side until wizard submission.

How provider keys are handled

Step 3 posts keys to POST /api/aipipe/proxy → AiPipe /v1/tenants/{id}/providers. Keys are:

• Stored in AiPipe's SQLite per-tenant key store
• Never written to the MC database or logs
• Scoped per tenant: other tenants cannot access your keys

How Step 6 stores agent roles

Agent roles are stored in the agent_roles table:

CREATE TABLE agent_roles (
  id         serial PRIMARY KEY,
  tenant_id  integer NOT NULL REFERENCES tenants(id),
  agent_name text NOT NULL,
  role       text NOT NULL,
  created_at timestamp DEFAULT now()
);

Roles are surfaced in the Kanban board header tiles and agent stats view.

Wizard steps at a glance