Skip to content

Secrets

A secret stores a credential for one agent. The agent holds a placeholder instead of the real value, and AgentZ swaps in the real value on requests to the hosts you list.

A Secret Belongs to One Agent

Create the agent first. See Create an agent. Then open Workspace settings → Secrets and pick the agent in the Agent selector. The page shows only when a role lets you read the secrets of at least one agent. A secret works for that agent only. Create the same secret again for another agent.

Create a Static Secret

  1. Pick the agent, select Create, then select Static. The New secret sheet opens.
  2. Enter a Name, for example SERVICE_API_TOKEN. Use letters, numbers and underscores, and start with a letter or underscore. The limit is 128 characters.
  3. In Hosts, enter each host and select Add. A secret takes 1 to 100 hosts. See the formats below.
  4. Paste the credential into Value. The limit is 48 KB.
  5. Select Create secret. The table shows the secret with the status Accepted, then Ready.

Each host is a hostname, *.hostname, **.hostname, an IP address or a CIDR range. Unlike sandbox allowed hosts, a secret accepts a bare IP address.

The value is write-only. After you save it, the AgentZ API returns the secret metadata and not the value.

The agent can reach a secret host only if its sandbox lists that host under Allowed hosts. See Allowed hosts.

The Agent Sees Only a Placeholder

A secret named SERVICE_API_TOKEN adds an environment variable with the same name to the agent. Its value is a placeholder:

SERVICE_API_TOKEN=agentz:resolve:env:SERVICE_API_TOKEN

The agent uses the variable as if it held the key:

curl https://api.example.com/items -H "Authorization: Bearer $SERVICE_API_TOKEN"

AgentZ replaces the placeholder with the real value on the way out.

AgentZ rewrites AgentZ does not rewrite
HTTPS requests over HTTP/1.1 Request bodies
Header values, including Authorization: Basic HTTP/2 traffic
The URL path and query Plain HTTP requests

A Host Mismatch Leaves the Placeholder in Place

AgentZ replaces the placeholder only when the request goes to a host on the secret's Hosts list. For any other host, the placeholder stays in the request and AgentZ logs a warning. The real value is not added to that request.

If two secrets share a host, the agent picks one by name, because each placeholder carries its secret name.

OAuth Secrets Refresh Tokens for You

Select Create, then OAuth. The New OAuth secret sheet opens.

  1. Pick a Catalog entry: Custom or Google Workspace CLI.
  2. Check Name, OAuth Server (an HTTPS URL) and Hosts. The Google entry fills them in.
  3. Enter Client ID and Client secret when the server has no registration endpoint. The Google entry has none, so enter them for it.
  4. Select Connect. A popup opens. Finish the sign-in. The secret appears in the table.

The Google Workspace CLI entry sets the name GOOGLE_WORKSPACE_CLI_TOKEN and the hosts *.googleapis.com and **.googleapis.com. Its scopes cover Drive, Gmail, Calendar, Sheets, Docs, Slides, Tasks and Contacts.

AgentZ refreshes the token for you. If a refresh fails, the status changes to Degraded.

Next Step

Skills