Environment and auth

Your application server should authenticate the user, determine their organization, and attach the runner credential. The browser should supply only the task-specific request data.

Core environment values

These values stay on the server:

export KESTREL_RUNNER_SERVICE_URL=http://127.0.0.1:4010
export KESTREL_RUNNER_SERVICE_TOKEN=dev-secret

Do not expose the token through browser-readable environment variables.

Configuration owners should also declare the canonical profile/provider registry, memory persistence, MCP/network policy, budget/evaluation policy, release identity, and worker/image identity. Keep each value in the service that owns it instead of copying one unrestricted environment block everywhere.

Sandbox capability profiles reference only statically registered adapters. Profile configuration may narrow audience, broker authority, request and response ceilings, timeout, and expiry, but it cannot supply a provider URL, proxy, credential, adapter implementation, or broader effect classification. Local Core and the hosted runner resolve credentials in their trusted environments and pass no bearer value into the sandbox.

Resolve user context in one place

export async function resolveWorkspaceCopilotContext() {
  return {
    actor: {
      actorId: "user-123",
      actorType: "end_user" as const,
      displayName: "Taylor Example",
    },
    tenantId: "acme",
  };
}

Keeping this logic in one server module makes authentication behavior easier to review and change safely.

Correlation headers

The Next.js route helpers read these headers from the inbound request:

• x-request-id
• x-correlation-id
• user-agent
• x-forwarded-for

If either id is missing, the helper generates it and returns Kestrel correlation ids in the response headers. Preserve them so a support report can be matched to the corresponding runner activity.

Carry the resulting actor, tenant, request, correlation, session, thread, run, turn, and operation identifiers through downstream services.

Where each value comes from

Action and approval authority

Resolve the exact requested action and effect on the trusted server. A browser may choose among offered options, but the server validates the pending request, grant, action fingerprint, expiry, and actor before execution.

For a sandbox external_effect, also bind that approval to the same run, tool call, canonical payload, and effect idempotency identity. Source access, read-only authority, or approval for another action is never interchangeable. No sandbox write adapter ships by default.

Check the server-side setup

• the application reads credentials and caller identity in one server module
• actor and tenant values come from authenticated application data
• /api/copilot/run and /api/copilot/stream preserve request correlation end to end
• the selected profile, provider/model capabilities, tools, and budget are ready

If identity is missing or incorrect

Check the server route that reads the authenticated session and creates the Kestrel context. Do not accept actorId or tenantId directly from browser input.

Prepare for production

• Connect to a runner service
• Integrating with Next.js
• FAQ