AI agents¶

This page covers an agent a person runs under their own grant with gdsgate delegations create, for the grant's TTL. An agent that runs unattended under its own identity runs on an agent host. The two are compared in Concepts → Agent host.

A delegated run is limited by four controls:

Control	Set by
Delegation	the owner: capability list and TTL
Cedar	standing policy: the ceiling and each request's decision
Agent identity	an agent-bound certificate that names the delegation
Sandbox	`--sandbox none`, `basic` or `strict`: local containment

--model (gateway, direct, off) selects the model channel. Direct egress is blocked only by a delivered sandbox; a gateway endpoint alone does not block it.

Properties that apply to every run¶

Every action through gdsgate is checked against the person's standing policy, the delegated capability and revocation state. Session-bearing resources open a session. MCP tools and Kubernetes requests are checked per request. Model resources are checked on every call.

With --exec, the grant and the agent-bound credential live as long as the foreground process. The child receives endpoint addresses and no private key of the person. When the process exits, gdsgate closes the endpoints and revokes the grant. If cleanup reports a revoke failure, treat the grant as live until gdsgate delegations list shows it revoked or you revoke it by hand. After a revoke or TTL expiry the next request is denied.

With --bind-key, the credential bundle is written to a directory the owner chooses, mode 0600. Delete it after revocation. A local status check can lag a remote revoke; the next request shows the current state.

Delegation audit linkage requires the Authority's control keyring ([security.integrity]). Without a usable key the linkage is not durable.

Options¶

Option	Values	Meaning
`--sandbox`	`none`, `basic`, `strict`	local filesystem, network, process and syscall controls
`--model`	`gateway`, `direct`, `off`	where a model call may go
`--ttl`	seconds	maximum grant lifetime
`--exec`	program	bind the grant lifetime to one foreground process
`--bind-key`	directory	write an agent-bound bundle for a separate process
`--allow-degraded`	flag	continue when the host cannot deliver a requested property

Use a short TTL and the smallest capability list. --allow-degraded does not accept an invalid --model/--sandbox pair and does not create a missing property.

Gateway coverage and sandbox enforcement¶

In gateway mode model calls go through the configured LLM resource. The Connector reads the model name from each request body, evaluates llmCall, and records the decision and token counters. MCP calls, database operations and Kubernetes requests are decided per request.

Under none the program keeps the host network and can call a model or backend directly. The audit contains only traffic that crossed gdsgate.

Under basic and strict, a delivered network boundary limits the program to the run's endpoints. These are host controls; they are not a VM or a kernel-exploit boundary. gdsgate doctor shows which properties the host delivers.

Platform	`basic` and `strict` are built from
Linux	Landlock, network and PID namespaces, `no_new_privs`. `strict` adds a seccomp filter and cgroup limits.
Windows	An AppContainer with no network capability and a Job object. No system-call filter. The network property needs the Base Filtering Engine service running.
Windows	Endpoints need the `gdsgate-client-net` service (installed by the MSI). Without it a grant that names a resource is refused.

Details per property: Delegation.

Compatibility¶

Sandbox	gateway model	direct model	off
`none`	allowed, advisory	allowed, unmanaged	allowed
`basic`	allowed, enforced when delivered	refused	allowed
`strict`	allowed, enforced when delivered	refused	allowed

--model direct with --sandbox basic or strict is refused before the grant is created. --allow-degraded does not change that.

When --model is omitted: gateway if the grant names an LLM capability, otherwise off. Set it explicitly in deployment records.

Common combinations¶

Goal	Shape	What the audit shows
Observe a trusted program	`none` + `direct`	gateway actions only; model traffic is unmanaged
Run untrusted code with a model	`strict` + `gateway`	sandbox claim, per-call decisions
Run a local integration tool	`basic` + `gateway`	endpoint allowlist, model and tool denials
No model access	`strict` + `off`	no model capability; calls refused

`--sandbox none`: no containment¶

none runs as the invoking user with the same filesystem, environment, process visibility and network. Use it for a cooperative program. A local credential the program reads, or a backend it dials directly, is not seen by gdsgate. If that happens, revoke the delegation, rotate the exposed credential and use basic or strict for the next run.

`--model gateway` without a sandbox¶

Without a sandbox the gateway endpoint and the generated MCP configuration are advisory: the program may ignore them or use another provider. A call through the gateway has an audit row naming the LLM resource; a direct call has none. To enforce the gateway, run under basic or strict.

Sandbox profiles and process lifetime¶

Check the host before launching:

gdsgate --config "$CLIENT_CONFIG" doctor --json

The output lists which filesystem, network, syscall, process and resource-limit properties are available. When a property is missing, basic or strict refuses to run unless --allow-degraded is given; the run then records the shortfall.

With --exec the foreground process is the lifetime boundary. Under none a program that daemonizes can outlive the grant. Under basic or strict the child ends with the run (PID namespace on Linux, Job object on Windows). Cleanup is revoke, endpoint shutdown and removal of any --bind-key directory.

Model resources¶

The Connector owner configures an LLM resource. The Connector holds any substitution credential; the agent sees no provider key:

[[connector.backends]]
resource = "models-dev"
kind = "llm"
allowed_models = ["test-small"]

The policy author grants llmCall on the model or service. An allowed call produces model and token counters and an llm.call audit row. A call for another model, or under a revoked delegation, is refused at the Connector before any outbound traffic.

Do not put a provider URL or token in an agent bundle. With pass-through configured, the caller's credential stays the caller's responsibility, and direct traffic is not observed.

Security limitations¶

none is not containment.
basic and strict are host controls. They are not a VM, hypervisor or kernel-exploit boundary.
--allow-degraded records a shortfall and does not create the missing property.
Gateway mode does not block direct egress without a delivered sandbox.
An agent-bound certificate narrows identity. It does not grant a capability Cedar denies.
A local status report does not show whether a remote revoke has propagated; the next request does.
Prompt and answer retention follows the configured recording policy. Do not put secrets in test prompts.

Reference¶

A lab launch end to end:

The agent owner checks the release with gdsgate --version and runs doctor --json.
The Connector owner has published tools-dev with a read-only search tool and models-dev with test-small. The policy author has written mcpCallTool and llmCall permits and matching forbids.
[security.integrity].control_keyring on the Authority names a keyring, readable only by the service.
On the client host, run:

gdsgate --config "$CLIENT_CONFIG" delegations create \
  --can mcp:search@tools-dev \
  --can llm:call@models-dev \
  --ttl 900 \
  --sandbox strict \
  --model gateway \
  --agent-profile PROFILE_NAME \
  --exec ./agent-wrapper -- --single-search-and-single-model-call

Expected result: the wrapper makes one search and one model call, then exits. The audit has delegation.create, sandbox.claim, the two operation rows and the session close events. An unlisted MCP tool or model gets a policy denial with no backend call.

Revoke the delegation while a second request is pending:

gdsgate --config "$CLIENT_CONFIG" delegations list
gdsgate --config "$CLIENT_CONFIG" revoke DELEGATION_ID

Expected result: the next request is denied and the revoke audit row names the delegation. Remove the wrapper output and any --bind-key directory. A --bind-key run takes the same capability list and needs an explicit revoke and deletion of the directory.

An agent profile names an external program; it does not fix that program's behavior. Record the program version and configuration in the deployment record and re-check them after upgrades. Policy rules: Policy guide. Launch choices: User guide.