Gateway and Scheduler Configuration

The Gateway and Scheduler load JSON configuration through their -config command-line argument. The same configuration format is used by these multi-node deployments:

Configuration is loaded in this order, with later values overriding earlier ones:

1. Built-in defaults.
2. The JSON file selected by -config.
3. Supported environment variables in the service process.

The Default column lists built-in values, which may differ from values explicitly set in deployment examples. Configuration is read at startup; restart the affected services after applying changes using the relevant deployment guide. Runtime-node TOML settings are documented separately in the Runtime Node Configuration.

Configuration fields

Scheduler fields

All fields in this table are inside scheduler.

scheduler.discovery

scheduler.discovery.mode selects how the Scheduler discovers runtime nodes:

• static (the default) uses the node list in scheduler.nodes.

Each scheduler.nodes entry accepts:

Static mode requires a nonempty node list and nonempty IDs and endpoints. If nodes is omitted entirely, the built-in list contains local-node at http://127.0.0.1:8000.

For example, merge the following fields into the existing scheduler object to use the two runtime services in the Docker Compose deployment:

{
  "nodes": [
    {
      "id": "node-a",
      "endpoint": "http://agentenv-a:8000"
    },
    {
      "id": "node-b",
      "endpoint": "http://agentenv-b:8000"
    }
  ],
  "discovery": {
    "mode": "static"
  }
}

• kubernetes uses scheduler.discovery.kubernetes to watch a Service’s EndpointSlices.

The following fields belong under scheduler.discovery.kubernetes and are used only in Kubernetes mode:

Nonempty selectors must be valid Kubernetes label selectors.

For example, merge the following field into the existing scheduler object for the Service agentenv-nodes in namespace agentenv-system:

{
  "discovery": {
    "mode": "kubernetes",
    "kubernetes": {
      "namespace": "agentenv-system",
      "service_name": "agentenv-nodes",
      "port": 8000,
      "scheme": "http"
    }
  }
}

scheduler.node_resource_limit

For a new scheduling request, the Scheduler takes discovered, non-lingering nodes, filters them against scheduler.node_resource_limit, then selects one using round robin or random selection.

Every resource-limit field is optional. An omitted field imposes no limit.

Gateway fields

All fields in this table are inside gateway.

gateway.tls

Enabling TLS switches the main listener to HTTPS. It does not also start an HTTP listener or an HTTP-to-HTTPS redirect.

For an existing certificate, add this object inside gateway:

"tls": {
  "mode": "manual",
  "cert_file": "/etc/agentenv/tls/fullchain.pem",
  "key_file": "/etc/agentenv/tls/privkey.pem"
}

For ACME with a wildcard sandbox domain, a Cloudflare example is:

"tls": {
  "mode": "acme",
  "domains": ["api.example.com", "*.sandbox.example.com"],
  "storage_dir": "/var/lib/agentenv/tls",
  "email": "operator@example.com",
  "challenge": "dns-01",
  "dns_provider": "cloudflare",
  "dns_config": {
    "api_token": "<cloudflare-api-token>"
  }
}

IP certificates require TLS-ALPN-01, allow at most one IP per listener, and reject private or special-purpose IPs. TLS-ALPN-01 must not include dns_provider or dns_config, and public TCP port 443 must reach the Gateway TLS listener for validation.

Wildcard certificates require DNS-01. When challenge is set to dns-01, configure dns_provider and its corresponding dns_config object. Supported providers and their configuration fields are listed below:

Unknown provider fields are rejected.

Example configuration

This example uses the two runtime nodes in the Docker Compose deployment, static discovery, round-robin placement, and an HTTP Gateway.

{
  "log_level": "info",
  "log_format": "json",
  "scheduler": {
    "grpc_listen_addr": ":9090",
    "strategy": "round_robin",
    "discovery": {
      "mode": "static"
    },
    "nodes": [
      {
        "id": "node-a",
        "endpoint": "http://agentenv-a:8000"
      },
      {
        "id": "node-b",
        "endpoint": "http://agentenv-b:8000"
      }
    ],
    "node_resource_limit": {
      "max_cpu_used_percent": 85,
      "max_memory_used_percent": 90
    }
  },
  "gateway": {
    "http_listen_addr": ":8080",
    "scheduler_addr": "scheduler:9090",
    "request_timeout": "90s"
  }
}