Agents configuration

Paths in the tables are relative to the profile heading. Keep model credentials in protected files or environment variables. Check the profiles with gdsgate --config <PATH> delegate --list-agent-profiles or gdsgate --config <PATH> delegate --list-profiles. See the delegation guide.

agent_profiles[].checked agent_profiles[].config_args agent_profiles[].config_dir_env agent_profiles[].config_env agent_profiles[].config_format agent_profiles[].config_path agent_profiles[].model_config_key agent_profiles[].model_url_env agent_profiles[].model_url_path agent_profiles[].name agent_profiles[].note agent_profiles[].source agent_profiles[].tools_entry agent_profiles[].tools_key delegation_profiles[].agent_profile delegation_profiles[].can delegation_profiles[].env delegation_profiles[].exec delegation_profiles[].exec_args delegation_profiles[].model delegation_profiles[].name delegation_profiles[].renewable delegation_profiles[].sandbox delegation_profiles[].sandbox_allow delegation_profiles[].sandbox_cpu delegation_profiles[].sandbox_listen delegation_profiles[].sandbox_memory delegation_profiles[].sandbox_processes delegation_profiles[].ttl_secs

[[agent_profiles]]

How gdsgate delegate --exec configures a named agent: the environment variable for its model address, and the format and location of its MCP configuration. See Agent profiles.

The binary ships built-in profiles. A row here with the same name replaces the built-in one; a row with a new name is added.

Key	Type	Default	Meaning
name	string	unset, required	Matched against the file name the --exec program was invoked under, or named directly by --agent-profile.
source	string	unset, required	URL of the agent documentation the row is based on.
checked	date string	unset, required	Date that page was checked, YYYY-MM-DD.
model_url_env	array of strings	[]	Environment variables set to the model endpoint's base URL. Empty for an agent that takes the address from its configuration.
model_url_path	string	""	Suffix appended to http://127.0.0.1:<port>, for example /v1.
model_config_key	string	""	Dotted key in the written configuration that receives the base URL, for an agent without a variable for it.
config_path	string	""	Location of the agent's configuration, relative to its $HOME. Written only under a cage, where $HOME belongs to the run.
config_env	string	""	Variable the agent reads an additional configuration file path from. Use it only when the agent merges that file with its own; it is set with and without a cage.
config_dir_env	string	""	Variable the agent reads its configuration directory from. Under a cage it is set to a directory in the run's home, which is created. Required on Windows, where a sandboxed program cannot look up its profile directory. The built-in codex row sets CODEX_HOME.
config_args	array of strings	[]	Arguments placed before yours, for an agent that takes a configuration file by flag. ${config} is replaced with the written file's path. Printed with the run.
config_format	string	""	json or toml.
tools_key	string	""	Dotted key of the MCP server map: mcpServers, mcp_servers, mcp.servers, mcp.
tools_entry	string	""	One server entry as a JSON object. ${url}: the endpoint's Streamable HTTP address. ${endpoint}: its host:port. ${command}: this binary's path, for agents that reach the endpoint through gdsgate mcp bridge.
note	string	""	Printed with the run: what the profile cannot configure and what to do by hand.

# An agent that dials Streamable HTTP and reads its model address from
# the environment.
[[agent_profiles]]
name = "acme-agent"
source = "https://acme.example/docs/configuration"
checked = "2026-08-03"
model_url_env = ["ACME_BASE_URL"]
model_url_path = "/v1"
config_env = "ACME_CONFIG"
config_format = "json"
tools_key = "mcpServers"
tools_entry = '{"type": "http", "url": "${url}"}'

# An agent whose MCP client can only start a program: it gets the bridge.
[[agent_profiles]]
name = "stdio-agent"
source = "https://stdio.example/docs/mcp"
checked = "2026-08-03"
config_path = ".config/stdio-agent/config.json"
config_format = "json"
tools_key = "mcpServers"
tools_entry = '{"command": "${command}", "args": ["mcp", "bridge", "${endpoint}"]}'

A row without source, or with a checked value that is not a date, is refused when the command starts.

[[delegation_profiles]]

A named, saved gdsgate delegate invocation: capabilities, cage, extra paths, and environment. See Saved delegations. [[agent_profiles]] describes how to configure an agent program; this section describes what to delegate and under which cage.

Key	Type	Default	Meaning
name	string	""	What --profile names.
can	array of strings	[]	Capabilities, in the --can spelling. A --can on the command line replaces these.
exec	string	""	The program a bare --exec runs.
exec_args	array of strings	[]	Its arguments, as -- would pass them. Used only when the command line gives none.
agent_profile	string	""	Agent profile to use when the program's file name does not match one.
model	enum	""	gateway, direct or off. Empty follows the grant.
sandbox	enum	""	none, basic or strict.
sandbox_allow	array of strings	[]	Paths the caged program may also read and execute. A --sandbox-allow on the command line replaces these.
sandbox_listen	array of integers	[]	Ports the caged program listens on that this machine may reach, as --sandbox-listen. A --sandbox-listen on the command line replaces these.
sandbox_memory	optional string	unset	Memory ceiling for a strict run.
sandbox_processes	optional u64	unset	Process ceiling for a strict run.
sandbox_cpu	optional string	unset	CPU ceiling for a strict run.
ttl_secs	optional u64	unset	Grant lifetime. Unset takes the command's own default.
renewable	optional bool	unset	Whether the agent-bound certificate is renewed within the grant window.
env	table of strings	{}	Environment for the program, added to what its agent profile sets.

sandbox, model and agent_profile are read only when a program is run. Without --exec the same profile issues a grant id for an agent started elsewhere. --sandbox on the command line without --exec is refused.

A value under env may be ${env:NAME} (from the caller's environment) or ${file:/path} (file contents, trailing newline removed). Use them for secrets. A plain string is used as is. A reference that resolves to nothing stops the run before the grant is issued.

[[delegation_profiles]]
name = "coding-agent"
can = ["llm:call@models-prod", "db:read@pg-demo"]
exec = "acme-agent"
exec_args = ["--verbose"]
sandbox = "basic"
sandbox_allow = ["/opt/toolchain"]
model = "gateway"
ttl_secs = 3600
env = { ACME_TOKEN = "${env:ACME_TOKEN}", NODE_ENV = "production" }