Backend runtime setup

Set up Cortex in a Convex host before connecting an application. The backend runs Agent, Workflow/Workpool jobs, registered tools, Gateway inference and asynchronous memory.

1. Install and register

Install the SDK dependency in the host as described in installation, inspect the additive plan and resolve its required-dependency report before applying it. For an explicitly selected disposable development deployment:

cortex backend install ./host --plan
cortex backend install ./host
cortex backend register ./host --target ./target.json
cortex backend provision ./host --target ./target.json --principal ./principal.json

Registration and provisioning need Convex management access and a matching dev: deployment key in environment variables (defaults CONVEX_ACCESS_TOKEN and CONVEX_DEPLOY_KEY). They verify the actual team/project/deployment tuple before dispatch. These helpers are development operator commands; normal app tokens never register a backend or provision grants.

target.json selects exact positive team/project IDs, deployment name and origin:

{
  "teamId": 123,
  "projectId": 456,
  "deploymentName": "your-development-deployment",
  "deploymentUrl": "https://your-development-deployment.convex.cloud",
  "disposable": true
}

Replace the example values with the selected deployment's actual metadata. A URL or credential alone does not establish a disposable target.

2. Configure identity and trusted grants

Configure the host's accepted JWT issuer, audience/application ID and JWKS (or its supported existing Convex auth integration). Trusted operator provisioning binds the verified issuer/subject to a principal, membership and grant.

{
  "issuer": "https://identity.example.com",
  "subject": "your-user-subject",
  "actorKind": "user",
  "tenantId": "your-tenant",
  "memorySpaceId": "your-space",
  "capabilities": ["read", "write", "run", "tool", "storage:read", "storage:write"],
  "resourceAccess": "own"
}

Grant capabilities are explicit. Supported access levels are own, space and tenant; a space grant requires a space, and a tenant grant omits the space selector. Optional expiresAt is a future Unix timestamp in milliseconds. Provision administrator/service grants only through trusted administration and for the required purpose.

The JWT identifies the actor. Caller claims, tenant labels, run IDs, local snapshots and resource IDs cannot provision grants or cross a scope boundary. Auth integration covers the token callback and view clearing.

3. Install policy and publish an Agent

An operator installs the deployment's versioned model qualifications and policies, narrows them for tenants/Agents, and publishes an executable Agent definition through the guarded agentDefinitions:publishVersion contract. The definition pins instructions, registered tools and context-handler versions/hashes, memory mode, required stages and policy versions. Revoke a version through agentDefinitions:revokeVersion when it should no longer run.

Use runtimeModelPolicy:installDeploymentPolicy with a trusted manifest; tenant policy provisioning and qualification records are internal operator contracts. Never fabricate model qualification receipts from a provider catalog entry. A model name alone does not establish interface, structured output, tool, embedding or media support.

The model-policy guide explains operation keys, limits, replay and incurred uncertainty. Text chat needs a qualified response policy and managed query/memory embedding profile. Applications read the profile from the backend.

4. Configure the application

cortex backend configure ./app   --url https://your-development-deployment.convex.cloud   --http-url https://your-development-deployment.convex.site   --agent-id your-agent --agent-version 1 --space your-space

This appends public metadata to .env.local, preserves existing values and refuses conflicting origins. Tokens and upstream keys are supplied separately through the host/backend configuration.

Setting	Purpose
NEXT_PUBLIC_CONVEX_URL	Installed runtime origin
NEXT_PUBLIC_CORTEX_HTTP_URL	Same installation's authenticated HTTP action origin
NEXT_PUBLIC_CORTEX_AGENT_ID / NEXT_PUBLIC_CORTEX_AGENT_VERSION	Published executable definition
NEXT_PUBLIC_CORTEX_MEMORY_SPACE_ID	Optional selector narrowing the actor's current grants

Deployment keys, Gateway/provider keys, callback secrets and graph passwords stay in trusted backend/operator services. The app supplies a short-lived host JWT through fetchToken.

Optional capabilities

Configure graph workers when graph projection is required. Private assets and media use the configured HTTP origin and retained jobs. The media guide covers service access, supported inputs and saved-operation recovery.

Continue with the quickstart or runtime client reference.