Agents configuration¶
The flat configuration hub remains the compatibility route. This page is the canonical source-checked field reference for its family, including nested tables and list rows.
Paths in the tables are relative to the profile heading. Each row gives the
serde type and source default or unset meaning; keep model credentials in
protected files or the supported environment overlay. Check profile shape and
unknown keys with gdsgate --config <PATH> delegate --list-agent-profiles or
gdsgate --config <PATH> delegate --list-profiles, then follow the
delegation guide.
agent_profiles[].checked agent_profiles[].config_args 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_memory delegation_profiles[].sandbox_processes delegation_profiles[].ttl_secs
[[agent_profiles]]¶
The registry gdsgate delegate --exec wires a named agent up from: which
environment variable that agent reads its model address from, and what shape and
place its MCP configuration takes. See
Agent profiles for what a run does with one.
The binary ships rows of its own. A row here with the same name replaces the
shipped one outright, and a row with a new name is added, so a vendor that
renames a variable is corrected without a release of gdsgate.
| 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 | Documentation page every other field was read from. |
checked |
date string | unset, required | Day that page was checked, in YYYY-MM-DD form. |
model_url_env |
array of strings | [] |
Environment variables set to the model endpoint's base URL. Empty for an agent that takes its address in configuration instead. |
model_url_path |
string | "" |
Appended to http://127.0.0.1:<port> before those variables are set, for example /v1 for an agent whose base URL includes the API version. |
model_config_key |
string | "" |
Dotted key in the rendered configuration that takes the base URL, for an agent with no variable for it. Left empty in the shipped rows wherever the key would name a provider id only the operator knows. |
config_path |
string | "" |
Where that agent's own configuration lives, relative to its $HOME. Written there only under a cage, whose $HOME is the run's own; uncaged that home is the operator's and nothing is installed into it. |
config_env |
string | "" |
A variable the agent reads an additional configuration file's path from. Set it only where that file is merged rather than substituted for the operator's, since it is used with and without a cage. |
config_args |
array of strings | [] |
Arguments put before yours, for an agent whose documented way of reading an arbitrary configuration file is a flag. ${config} becomes the written file's path. Printed with the run. |
config_format |
string | "" |
json or toml, the syntax of that file. |
tools_key |
string | "" |
Dotted key holding the map of MCP servers in it: mcpServers, mcp_servers, mcp.servers, mcp. |
tools_entry |
string | "" |
One server's entry, as a JSON object. ${url} is the endpoint's Streamable HTTP address, ${endpoint} its host:port, ${command} this binary's path. Which of them a row uses is how it says whether that agent dials the endpoint or needs gdsgate mcp bridge to reach it. |
note |
string | "" |
Printed verbatim with the run: what this profile could not do for that agent, and what to do by hand instead. |
# An agent that dials Streamable HTTP itself 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}"]}'
source, or whose checked is not a date, is refused when
the command starts rather than used.
[[delegation_profiles]]¶
A saved gdsgate delegate invocation, named: the capabilities, the cage, the
paths that agent's toolchain reads, the variable it wants its credential in.
Retyping that row is how one of them quietly goes missing, and the one that goes
missing is usually the cage. See Saved delegations.
It is a different thing from [[agent_profiles]]: that is a
claim about somebody else's product and goes stale when their product changes;
this is a claim about your own intent, what you are willing to delegate and
behind what boundary.
| 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 | "" |
Which agent profile to wire the program up with, where the program's own name is not the one to look up. |
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_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 rolled forward within the window. |
env |
table of strings | {} |
Environment for the program, on top of whatever its agent profile sets. |
sandbox, model and agent_profile are read only on an invocation that runs a
program. The same row is also how somebody gets a grant id to hand to an agent
started elsewhere, and refusing that because the row describes a cage would make
the two uses need two rows. A --sandbox typed on the command line without
--exec is still refused.
A value under env may be ${env:NAME}, read from the environment of whoever
runs the command, or ${file:/path}, read from a file with the trailing newline
dropped. Both keep the secret out of this file, which is read by everything that
loads the configuration and copied into every backup of it. A plain string is
taken literally, for the variables that are settings rather than secrets. A
reference that resolves to nothing refuses the run before the grant is minted.