AI agents

This page is for the owner of an autonomous program. An agent is a principal with a delegated capability, not a new administrator. The safe path names four independent boundaries:

Boundary	Decision
Delegation	the owner grants a capability floor and TTL
Cedar	standing policy supplies the ceiling and per-request decision
Agent identity	an agent-bound certificate names the delegation
Host execution	none, basic, or strict sandbox describes local containment

A model channel is a fifth choice: gateway, direct, or off. A gateway endpoint does not prove that direct egress is blocked. Only a delivered sandbox can make that network claim.

Properties that apply to every run

Every action through gdsgate is checked against the human's standing policy, the delegated capability, and revocation state. Session-bearing resources open a session; MCP tools and Kubernetes requests are checked at their request boundary; model resources are checked on every call.

With --exec, the grant and agent-bound credential live for the foreground process. The child receives the configured endpoint information, not a human private key. When the process exits, gdsgate closes its endpoints and attempts to revoke the grant. If cleanup reports a revoke failure, treat the grant as live until gdsgate delegations or a manual revoke confirms otherwise. A confirmed revoke or TTL expiry denies the next request.

With --bind-key, the credential bundle is written to an owner-selected directory with mode 0600. It is a credential and must be deleted after revocation. A local delegation status check can be stale after a remote revoke; the next access is authoritative.

Prerequisite for the audit linkage is an external delegation key configured at audit.delegation_key_path. If it is missing or unusable, do not claim durable delegation audit.

Options

Option	Values	Meaning
--sandbox	none, basic, strict	local filesystem, network, process, and syscall controls
--model	gateway, direct, off	where a model call is allowed to travel
--ttl	seconds	maximum grant lifetime
--exec	program	bind 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. Do not use allow-degraded to waive an invalid model/sandbox pair or to turn a missing containment property into a security claim.

Gateway coverage and sandbox enforcement

Gateway mode sends model calls 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 have their own request decisions.

Under sandbox none, the program retains the host network and can call a model or backend directly. The agent may ignore the gateway endpoint, so the audit contains only traffic that actually crossed gdsgate.

Under basic and strict, a successfully delivered network boundary limits the program to the endpoints exposed by the run. Basic and strict are not virtual machines or kernel exploit boundaries. The host's doctor result is part of the claim.

Compatibility

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

Direct under a cage is refused before a grant is minted because a cage has no route to a provider and cannot safely receive a provider credential. The nearest negative is --model direct with --sandbox basic or strict. allow-degraded does not waive that contradiction.

When model is omitted, it follows the grant: gateway when the grant names an LLM capability, otherwise off. State the choice explicitly in a deployment record so a profile change cannot silently widen the channel.

Common combinations

Goal	Shape	Evidence
Observe a trusted program	none plus direct	only other gateway-mediated actions are visible; model traffic is unmanaged
Run untrusted code with a model	strict plus gateway	sandbox claim, per-call policy, and audit rows
Run a local integration tool	basic plus gateway	endpoint allowlist and model/tool denials
No model access	strict plus off	model capability absent and calls refused

--sandbox none: no containment

none runs as the invoking user with the same filesystem, environment, process visibility, and network. It is useful for attribution of a cooperative program, not hostile code. The nearest negative is a program that accesses a local credential or dials a backend directly; that behavior is outside gdsgate's observation. Recovery is to revoke the delegation, rotate any exposed credential, and use basic or strict for the next run.

--model gateway without a sandbox

The gateway endpoint and generated MCP configuration are advisory without a sandbox. The program may decline them or use another provider. Positive evidence is a model call whose audit row names the intended LLM resource. The nearest negative is a direct call that has no gdsgate row. Recovery is a delivered sandbox or an explicit decision to use unmanaged direct mode. Do not describe gateway mode as network enforcement in this combination.

Sandbox profiles and process lifetime

Run the host capability check before launching:

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

Expected result: the output states which filesystem, network, syscall, process, and resource-limit properties are available. The nearest negative is a missing property; strict refuses unless the operator explicitly chooses allow-degraded, and the run records the shortfall.

A foreground process is the lifetime boundary for --exec. A program that daemonizes can outlive the grant only under none; under a delivered PID namespace the child lifetime ends with the run. Test the actual wrapper and kernel, not a different host. Cleanup is revoke, endpoint shutdown, and removal of any bind-key directory.

Model resources

An LLM resource is configured by the Connector owner. The service 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 to the model or service. Positive evidence is one allowed test-small response, model/token counters, and an llmCall audit row. The nearest negative is a different model or a revoked delegation; the Connector refuses before outbound traffic. Cleanup is revocation, expiry, and removal of temporary model output.

Do not put a provider URL or token in an agent bundle. If pass-through is configured, the caller's credential remains the caller's responsibility and the gateway still cannot claim to observe direct traffic.

Security limitations

• none is not containment.
• basic and strict are host controls, not VM, hypervisor, or kernel-exploit boundaries.
• 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 but does not grant a capability that Cedar denies.
• a local status report cannot prove a remote revoke has propagated; test the next request.
• model prompt and answer retention follows the configured recording policy; do not place secrets in test prompts.

Reference

A complete, source-checked lab launch has these actors and steps:

1. The agent owner confirms the release with gdsgate --version, runs doctor --json, and verifies the local agent profile's external documentation owner and review date.
2. The Connector owner has published tools-dev with a read-only search tool and models-dev with test-small. The policy author has typed mcpCallTool and llmCall permits and matching denials.
3. The owner configures audit.delegation_key_path and checks that the key is external, mode 0600, and available to the Authority.
4. On the client host, run:

gdsgate --config "$CLIENT_CONFIG" delegate \
  --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 allowed search and one allowed model call, then exits. Positive evidence includes delegation.create, sandbox.claim, the two allowed operation rows, and the resulting session/close events. The nearest negative is an unlisted MCP tool or model, which returns a policy denial without a backend call. A direct model channel under strict is refused before launch.

1. Revoke the delegation while a second request is pending:

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

Expected result: the next request is denied and the revoke audit row names the delegation. Cleanup removes wrapper output and any bind-key directory. A bind-key flow uses the same capability list but requires explicit revoke and owner-only deletion.

The profile name is not a vendor guarantee. Keep the external program version, configuration shape, owner, documentation source, and review date in the deployment record, and re-check it after upgrades. The Policy guide owns typed rules; the User guide owns the human launch choice.