Agent-host configuration

Paths in the table are relative to [agent_host]. Check parsing and unknown keys with gdsgate doctor --config <PATH> --json.

[agent_host]

Used by: Agent host.

The node identifier and the catalog boundary for agent faces. Agents are declared on Authority with authority set-agent.

Running agents requires Linux. On Windows the agent host starts but runs no agents; each one is logged as not held.

Key	Type	Default	Applies to	Purpose
id	string	"agents"	Agent host	Node identifier, shown by gdsgate authority list-nodes. Unique within the tenant.
scope	string	""	Agent host	id_prefix of the catalog boundary the host publishes faces into. Empty: no faces are published.

The boundary

Faces are published into a discovery boundary declared on Authority. A face appears in the catalog when:

• the boundary's node is this host;
• the boundary's kinds include the face's kind;
• the boundary's max_live is not reached.

A host naming a boundary that belongs to another node is refused. The catalog row name is the boundary's id_prefix followed by the face name: support-bot-web in scope = "agents-" is agents-support-bot-web.

With scope empty, agents can call resources and are not reachable.

Related settings

Setting	Where
Agents and their access	Authority: authority set-agent
Authority address	[endpoints].authority
Proxy address for published faces	[endpoints].proxy_internal, read when scope is set
Proxy address for the agents' own sessions	[endpoints].proxy_public
CA verifying that listener	[client].transport_ca. Unset: the system roots
Node identity and renewal	[enroll]
Health endpoints	[telemetry].metrics_listen

Example

[endpoints]
authority = "auth:50051"
proxy_public = "gate:443"

[client]
transport_ca = "/etc/gdsgate/transport-ca.pem"

[enroll]
endpoint = "https://auth:50050"
renew_endpoint = "https://auth:50051"
state_dir = "/var/lib/gdsgate/agent-host"

[agent_host]
id = "agents-01"
scope = "agents-"

[telemetry]
metrics_listen = "127.0.0.1:9090"

Symptom: every agent reports a transport error for every resource

Log line: session ended (<resource>): failed to connect: transport error, for resources the agent holds and the policy permits.

Cause	What to do
[endpoints].proxy_public unset (default 127.0.0.1:50061)	Set it to the Proxy's client listener.
[client].transport_ca unset, and the listener's certificate is issued by the cluster CA	Set it to the cluster transport CA.

gdsgate join --role agent-host writes both keys. It writes neither when the Proxy's [endpoints].proxy_public is unset or a wildcard address, or when the control plane is older than v0.9.0-rc.9. It writes no transport_ca when the listener's certificate is publicly issued.

Symptom: no work comes up, doctor fails state.agent.cage

On Linux. The doctor row lists the missing cage features. A strict declaration does not start while any feature is missing.

Named in the row	Cause	What to do
memory, process and CPU limits	The unit's cgroup is not delegated, holds the process itself, or is mounted read-only.	Delegate=yes and DelegateSubgroup=supervisor (systemd 254+), no ProtectControlGroups=. The shipped unit has all three.
a private PID namespace, a control socket inside the cage	The service runs unconfined on a host with kernel.apparmor_restrict_unprivileged_userns=1 (Ubuntu 23.10+), and loses its capabilities inside the namespaces it creates.	Install packaging/apparmor/gdsgate to /etc/apparmor.d/ and load it with apparmor_parser -r.
Landlock, a private network namespace	The kernel lacks Landlock, or unprivileged user namespaces are disabled.	Use a kernel with Landlock and set kernel.unprivileged_userns_clone=1.
a system-call filter	The unit's SystemCallFilter= refuses seccomp.	Keep the unit's second SystemCallFilter= line.

When the unit's SystemCallFilter= refuses Landlock's calls, the node is killed with SIGSYS the first time it starts a work, and doctor under the same unit is killed the same way. The shipped unit allows them.

A full template ships as packaging/config/agent-host.toml.example. Install the unit packaging/systemd/gdsgate-agent-host.service by hand; gdsgate service install does not support the agent host role. There is no Windows service for it.