Configuring HTTP API Domain Deployments

Overview

After adding HTTP mounts and endpoints to agents in code, you must configure an HTTP API deployment in golem.yaml so Golem knows which agents to expose and on which domain. This skill covers the httpApi manifest section, security scheme setup, and the auto-generated OpenAPI specification.

Adding a Domain Deployment

Add an httpApi section to the root golem.yaml:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      agents:
        TaskAgent: {}
        UserAgent: {}

Structure

• httpApi.deployments is a map keyed by environment name (e.g., local, staging, prod)
• Each environment contains a list of deployment objects
• Each deployment has:
  • subdomain: a single DNS label (lowercase letters, digits, and hyphens only — no dots, port, or URL scheme) resolved through the target environment server. Local HTTP API deployments resolve to <subdomain>.localhost:9006 by default, or <subdomain>.localhost:<customRequestPort> when localServer.customRequestPort is set to a stable nonzero port. Cloud HTTP API deployments resolve to <subdomain>.apps.golem.cloud.
  • domain: a full domain such as api.example.com for custom registered domains or custom server environments.
  • scheme (optional): the public scheme (http or https) advertised in OpenAPI. It defaults to http for built-in local and implicit local environments and to https for built-in cloud environments. An explicit value overrides these defaults. Custom server environments must set it explicitly; Golem does not infer it from the server management URL. This field does not configure the HTTP listener.
  • agents: a map of agent type names (PascalCase) to their deployment options
  • webhookUrl (optional): path prefix for webhook callbacks; defaults to /webhooks/

Define exactly one of subdomain or domain on each deployment. Prefer subdomain for built-in server: local and server: cloud environments. Use domain when you need a full custom domain. subdomain cannot be used with custom server environments — those must use domain.

Do not use localServer.customRequestPort: 0 in the manifest. Port 0 is only allowed when passed directly as --custom-request-port 0 to golem server run; manifest deployment domains require stable nonzero ports. The local server routes requests by matching their Host header against the expanded <subdomain>.localhost:<port>, so the running server must bind the same port the manifest expands to: golem server run warns when its --custom-request-port differs from the manifest value, and such deployments are not reachable until the two match.

<subdomain>.localhost resolves only on the machine running the local server, regardless of localServer.routerAddr (the HTTP API listener binds all interfaces). To call a local deployment from another machine, use domain with a host name that resolves there instead of subdomain.

Agent Options

Each agent entry accepts these optional fields:

agents:
  TaskAgent: {}                          # Default — no auth, no test header
  SecureAgent:
    securityScheme: my-oidc              # Reference a security scheme by name
  DevAgent:
    testSessionHeaderName: X-Test-Auth   # Use a test header for development

• securityScheme: name of a pre-configured security scheme (see below) — use this when the agent has auth: true
• testSessionHeaderName: header name for test/development authentication — provides a simple way to pass identity without a real OIDC flow
• Only one of securityScheme or testSessionHeaderName can be set per agent

Security Schemes

Security schemes define OIDC authentication providers. They are managed via the Golem CLI:

Creating a Security Scheme

golem api security-scheme create my-oidc \
  --provider-type google \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --redirect-url "http://my-app.localhost:9006/auth/callback" \
  --scope openid --scope email --scope profile

Supported Providers

For a custom OIDC provider:

golem api security-scheme create my-custom-oidc \
  --provider-type custom \
  --custom-provider-name "My OIDC" \
  --custom-issuer-url "https://auth.example.com" \
  --client-id "YOUR_CLIENT_ID" \
  --client-secret "YOUR_CLIENT_SECRET" \
  --redirect-url "https://app.example.com/auth/callback" \
  --scope openid

Managing Security Schemes

golem api security-scheme get my-oidc           # View details
golem api security-scheme update my-oidc ...     # Update fields
golem api security-scheme delete my-oidc         # Delete

Referencing in golem.yaml

After creating a security scheme, reference it by name in the agent deployment options:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      agents:
        SecureAgent:
          securityScheme: my-oidc

This enables OIDC authentication for all endpoints on SecureAgent that have auth: true set in their code-level annotations.

Test Session Header (Development)

For local development without a real OIDC provider, use a test session header:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      agents:
        SecureAgent:
          testSessionHeaderName: X-Test-Auth

Then pass identity in requests. The header value must be a JSON object representing an OIDC session. All fields have defaults, so only subject is needed to identify the caller:

curl -H 'X-Test-Auth: {"subject":"test-user-id"}' http://my-app.localhost:9006/secure/agent1/data

Available fields (all optional, with defaults):

⚠️ Important: The header value must be valid JSON — a plain string like "user1" will be rejected with a 400 error.

Multi-Environment Deployments

Define different domains and security configurations per environment:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      agents:
        TaskAgent: {}
        SecureAgent:
          testSessionHeaderName: X-Test-Auth
    cloud:
    - subdomain: my-app  # resolves to my-app.apps.golem.cloud
      agents:
        TaskAgent: {}
        SecureAgent:
          securityScheme: prod-google-oidc
 
environments:
  local:
    server: local
  cloud:
    server: cloud

Webhook URL

If agents use webhooks, configure the webhook path prefix:

httpApi:
  deployments:
    local:
    - subdomain: my-app  # resolves to my-app.localhost:9006 by default
      webhookUrl: /my-custom-webhooks/
      agents:
        WebhookAgent: {}

The deployment domain comes from subdomain or domain. The webhookUrl path prefix is combined with the agent’s webhookSuffix (defined in code) and the generated webhook ID to form the full callback URL, such as http://my-app.localhost:9006/my-custom-webhooks/order-hooks/<id>.

Deploying

After configuring golem.yaml, deploy. Always use --yes to avoid interactive prompts:

golem deploy --yes                     # Deploy all components and HTTP API
golem deploy --yes --reset             # Deploy and delete all previously created agents
golem deploy --yes --update-agents auto # Deploy and update running agents

Auto-Generated OpenAPI

Golem automatically serves an OpenAPI specification at /openapi.yaml on each deployment domain:

curl http://my-app.localhost:9006/openapi.yaml

This specification includes all endpoints from all agents deployed to that domain, with proper path parameters, request/response schemas, and CORS metadata.

Complete Example

# golem.yaml
 
httpApi:
  deployments:
    local:
    - subdomain: task-app  # resolves to task-app.localhost:9006 by default
      webhookUrl: /webhooks/
      agents:
        TaskAgent: {}
        AdminAgent:
          testSessionHeaderName: X-Admin-Auth
    cloud:
    - subdomain: task-app  # resolves to task-app.apps.golem.cloud
      agents:
        TaskAgent: {}
        AdminAgent:
          securityScheme: google-oidc
 
environments:
  local:
    server: local
  cloud:
    server: cloud

Key Constraints

• Agent type names in golem.yaml use PascalCase (matching the class/trait name in code)
• Each agent entry can have at most one of securityScheme or testSessionHeaderName
• Security schemes must be created via golem api security-scheme create before they can be referenced
• The resolved domain must be unique per environment
• After changing golem.yaml, run golem deploy --yes to apply changes