For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.

Create, update, and revoke config resources such as API keys at runtime through the agentgateway config resource API.

Manage agentgateway resources such as API keys at runtime through the config resource API, without restarting the proxy. Use agctl standalone to manage the resources from the command line, or call the API directly.

About

Agentgateway serves a config resource API for reading and writing config resources at runtime, such as virtual API keys, models, routes, and policies. The UI calls this same API, so you can create, update, and revoke API keys from a script instead of the browser. For more information about where the UI and its API are served, see Launch the UI.

The config resource API is served wherever the UI is served, and the admin address always keeps a copy of it.

What config.storage.mode changes is where a write is stored, and whether the API lists the resource afterward. In file mode, agentgateway writes the resource into your config file, and a list request returns the resources from that file. In hybrid mode, agentgateway stores the resource in the database, and a list request returns the resources from the database only, not from the baseline file. For each mode, what the database holds, and how the modes differ per installation method, see Storage modes.

The rest of this guide uses hybrid mode, which supports the full set of operations.

Before you begin

1. Set config.storage.mode to hybrid and give agentgateway a database in config.database.url. A sqlite:// URL creates the file for you, and a postgres:// URL is also supported. For more information, see Database.

2. Add an apiKey policy to llm.policies. Agentgateway merges database-backed keys into this policy, so the policy must exist before you create a key. Set keys to an empty array to start with no keys in the file. Without the policy, a create returns 409 with the message DB-backed API keys require llm.policies.apiKey.

   # yaml-language-server: $schema=https://agentgateway.dev/schema/config
   config:
     adminAddr: "127.0.0.1:15000"
     storage:
       mode: hybrid
     database:
       url: "sqlite://./agentgateway.db"
   llm:
     policies:
       apiKey:
         mode: strict
         keys: []
     models:
     - name: "*"
       provider: openAI
       params:
         apiKey: "$OPENAI_API_KEY"

3. Verify the config and start agentgateway.

   agentgateway --validate-only -f config.yaml
   agentgateway -f config.yaml

For more information about API key authentication and the apiKey policy fields, see Virtual keys.

Resource kinds

A resource kind is written with dots, such as llm.apiKey. A bare name such as apiKey returns unsupported config resource kind: apiKey.

Agentgateway supports the following resource kinds. No other kind is accepted.

Each kind maps to a top-level config section. For example, the mcp.target kind manages the entries in mcp.targets. An MCP target that you define inline in routes[].backends belongs to its traffic.route resource instead. Likewise, inline model and route policies belong to the resource that contains them.

Manage resources with agctl

Use agctl standalone to list, apply, and delete resources from the command line. The CLI calls the same config resource API as the curl examples in Manage API keys. Before you begin, install agctl at the same version as your gateway.

Connect to a gateway

By default, agctl standalone connects to http://localhost:15000, which is the default admin address. To connect to another API address, use the --address flag. For example, the generated Docker configuration serves the UI and its API on the published gateway port 4000.

agctl standalone --address http://localhost:4000 get all

Use the base URL of the server, without /ui or /api. For Helm installations, port-forward the admin address before you run the CLI.

export AGCTL_STANDALONE_ADDRESS=http://localhost:15000
agctl standalone get all

Save connection profiles

Use named profiles to manage several standalone gateways. The CLI reads the file in $AGCTL_CONFIG. If the variable is not set, the CLI reads agctl/config.yaml in the user configuration directory of your operating system. On Linux, this file is typically ~/.config/agctl/config.yaml. On macOS, the file is ~/Library/Application Support/agctl/config.yaml.

1. Create a CLI configuration file. This file is separate from the configuration file that agentgateway reads.

   cat <<'EOF' > agctl.yaml
   current: local
   gateways:
     local:
       url: http://localhost:15000
     container:
       url: http://localhost:4000
   EOF
   export AGCTL_CONFIG="$PWD/agctl.yaml"

2. Select a profile with the --gateway flag. The flag refers to a CLI connection profile, not to a traffic gateway resource or a Kubernetes Gateway.

   agctl standalone --gateway local get all

The CLI selects the address in the following order: --gateway, --address, AGCTL_STANDALONE_ADDRESS, the current profile, and then http://localhost:15000. You cannot combine the --gateway and --address flags.

For an authenticated API, configure an exec credential plugin in the profile. The plugin uses the Kubernetes exec credential schema and supplies the credentials for each HTTP request. The authentication policy of the API must accept those credentials. A browser login session does not authenticate the CLI. For a profile example, see the agctl standalone reference. For API authentication policies, see Secure the UI.

Storage behavior

The CLI follows the config.storage.mode setting of the gateway.

The standalone Helm chart uses the readonly mode by default, which mounts a ConfigMap that the proxy cannot write. To manage resources with the CLI, use the database mode of the chart. For setup and ownership rules, see Configuration storage.

The get all command lists resources. It is not a full configuration backup. In file mode, the list omits singleton settings and the model catalog. In hybrid mode, the list omits the baseline file. Startup settings and legacy binds configuration are not CLI resources. For the merged configuration, use the /api/config/effective endpoint. For the runtime configuration that the proxy loaded, see Inspect config.

List resources

Use the get command to inspect the resources that the API manages. To narrow the result, add a resource kind, and then a resource name or ID. For structured output, add -o yaml or -o json. The CLI accepts both singular and plural kinds, such as llm.model and llm.models.

agctl standalone get all
agctl standalone get llm.apiKey
agctl standalone get llm.apiKey <name-or-id> -o yaml

Apply resources

Apply YAML or JSON resource documents to add or update configuration. Each document has a kind and a value. To update an existing API key or policy, also include its id. This format differs from a complete agentgateway configuration file.

1. Create a model resource. This example uses Ollama on the gateway host. Before you send requests to the model, install Ollama and pull the model.

   cat <<'EOF' > model.yaml
   kind: llm.model
   value:
     name: example-model
     provider: ollama
     params:
       model: llama3.2
   EOF

   Field	Description
   kind	The resource kind.
   value.name	The model name that clients request through agentgateway.
   value.provider	The provider type, or a reference to a configured provider.
   value.params.model	The model name that agentgateway sends to the provider.

2. Apply the resource to the running gateway.

   agctl standalone apply -f model.yaml

   Example output:

   llm.model/example-model created

3. Verify the resource.

   agctl standalone get llm.model

   Example output:

   NAME           PROVIDER  MODEL     ID
   example-model  ollama    llama3.2  example-model

To apply several resources at once, separate the YAML documents with ---. To read the documents from stdin, use -f -. The CLI applies providers before models, and API key policies before keys. Each write is separate, so an error can leave the earlier writes applied. Fix the failed resource and apply the file again.

The apply command creates and updates the resources in the file. It does not delete the resources that the file omits. Within a resource, send the complete value that you want to keep. To remove a resource, use the delete command.

Update a resource

Export a resource, edit its value, and apply it again.

1. Export the model without the server-managed revision and timestamp fields.

   agctl standalone get llm.model example-model -o yaml --no-metadata > model.yaml

2. Edit model.yaml. For example, change value.params.model to another model that your Ollama instance serves. Keep value.name unchanged so that the CLI updates the same model.

3. Apply the edited resource.

   agctl standalone apply -f model.yaml

   Example output:

   llm.model/example-model updated

The --no-metadata flag keeps the IDs of API keys and policies. For a hashed API key, also keep value.keyHash. You can send unchanged server-managed key metadata, such as agentgateway.dev/id, back in an update, but do not change these values. For a complete key workflow, see Set up virtual keys (agctl).

Writes reach the traffic path asynchronously, as described in Propagation timing. A resource listing confirms that agentgateway stored the resource, not that routing or inference works. To confirm the change, send a request through the gateway.

Delete resources

Delete a resource by name or ID. If a name matches several resources, use the ID from the get command. Delete dependent resources first, such as a virtual model before its target models, or a route before its gateway.

agctl standalone delete llm.model example-model

Example output:

llm.model/example-model deleted

Deleting a resource that does not exist returns an error. In hybrid mode, to remove a resource that the baseline file owns, edit the file.

Manage API keys

The following steps use the llm.apiKey kind. The same endpoints work for every kind in the previous table.

1. List the keys that the API manages.

   curl -s http://127.0.0.1:15000/api/config/resources/llm.apiKey

   Example response in hybrid mode. In file mode, the response contains only kind, id, and value. A key in the file that has no agentgateway.dev/id metadata field gets an id from its position in the list, such as @index:0.

   {"resources": [{
     "kind": "llm.apiKey",
     "id": "30cb4228-dd1f-402e-acc4-eeab18fc81fc",
     "value": {
       "key": "sk-agw-8a0b7a6a…",
       "metadata": {
         "agentgateway.dev/createdAt": 1792525913,
         "agentgateway.dev/id": "30cb4228-dd1f-402e-acc4-eeab18fc81fc",
         "group": "engineering",
         "name": "my-service",
         "user": "alice"
       }
     },
     "revision": 1,
     "createdAt": "2026-10-20T19:51:53.830801Z",
     "updatedAt": "2026-10-20T19:51:53.830801Z"
   }]}

2. Create a key with a collection PUT. The body wraps one or more records in a resources array. Agentgateway generates the id and copies it into the agentgateway.dev/id metadata field, so do not send an id yourself. The request is an upsert rather than a replace, so keys that already exist are kept.

   curl -X PUT http://127.0.0.1:15000/api/config/resources/llm.apiKey \
     -H 'Content-Type: application/json' \
     -d '{"resources":[{"value":{
           "key":"sk-agw-<hex>",
           "metadata":{"name":"my-service","user":"alice","group":"engineering"}
         }}]}'

3. Update a key with a single-resource PUT to /api/config/resources/llm.apiKey/{id}. Send the record’s existing key value with every update, so that the user keeps their key when other fields change. The following example changes the group.

   curl -X PUT http://127.0.0.1:15000/api/config/resources/llm.apiKey/<id> \
     -H 'Content-Type: application/json' \
     -d '{"value":{"key":"<existing key>","metadata":{"name":"my-service","user":"alice","group":"engineering"}}}'

4. Delete a key. A successful delete returns 200. Deleting the same id again returns 404.

   curl -X DELETE http://127.0.0.1:15000/api/config/resources/llm.apiKey/<id>

Update rules for API keys

The update endpoint replaces the record rather than patching it, which leads to the following behavior.

Propagation timing

Agentgateway applies a write asynchronously, so a change is not guaranteed to be visible on the traffic path the moment the API responds. In practice a new key is accepted on the next request, and a deleted key is rejected on the next request. A request that is already in flight when you delete a key can still complete.

Build a client that does not depend on the timing. If a script creates a key and uses it immediately, retry on 401, which is the status that agentgateway returns for a key that it does not recognize.