Skip to main content

​
What this does

A workspace secret stores one JSON object for fleet tools. The client never reads the stored value back. The credential firewall adds values to approved outbound calls. The fleet sees the response, not the secret value.

​
Before you begin

Select the workspace that should own the secret. Prepare a valid, non-empty JSON object. For an outgoing HTTP credential, include host with the destination host name. The credential firewall refuses requests whose destination does not match it.

​
Steps

  1. Create a secret with an obviously fake value.
    Replace the fake value through a secret manager. Avoid putting real values in shell history.
  2. Confirm that the secret exists.
  3. List secret names.
    CREATED shows the creation date and time. Use --json for structured metadata.

​
Replace a value

Update replaces the stored value without a delete-and-create gap. Fleets keep access to the secret name throughout the change.
Send the complete JSON object. Replacement removes any field you leave out. You cannot read the stored value back to check a partial change. Pipe the object on stdin with --data=@- to keep values out of shell history. The dashboard’s Edit dialog performs the same replacement through PUT /v1/workspaces/{workspace_id}/secrets/{secret_name}. Updating a missing name returns UZ-VAULT-003 and creates nothing. Use agentsfleet secret create for a new name.

​
Verify it works

In setup chat, ask to use the api_token field from the stripe secret for requests to api.stripe.com. Share the secret name and field, and keep the value out of chat. Review the requested tools and access before saving. Save a fleet that declares the secret name. If a required secret is missing, the fleet stays installing, and the readiness check names the secret to create. The list and show commands return metadata only. Neither command returns secret fields or values.

​
Common problems

UZ-VAULT-001 means the data is empty or is not a JSON object. Send an object with at least one field. UZ-VAULT-002 means the stored object exceeds 4 KiB. Remove unused fields or shorten values. UZ-VAULT-003 on update means the workspace holds no secret by that name. Create it instead. UZ-VAULT-005 means the workspace already holds that name. Creating a secret claims a name that is free, so nothing is written and the command exits 0. Replace the value with agentsfleet secret update.

​
Remove or undo

Deleting a secret removes the value immediately. Fleets that require the name will fail until you create it again.
Deletion is idempotent. Recreate the same name to restore access with a new value. Five secret names belong to connectors: github, slack, zoho, jira, and linear. Connecting a provider from the Integrations page stores its connection under that name. Deleting that secret disconnects the connector, the same as Disconnect on the Integrations page. Inbound events from that provider stop until you connect it again. The dashboard’s delete dialog names the connection before you confirm. A secret you stored by hand under one of these names holds no connection. The github secret from the quickstart is one example. Deleting it removes only the value, and the dashboard shows the usual delete dialog. Either way, an API key needs connector:write as well as secret:write to delete a secret with one of these names. To replace a value, prefer agentsfleet secret update — deleting first leaves the name absent between the two calls, and any fleet that requires it fails during that gap.