> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentsfleet.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage secrets

> Store, replace, inspect, and delete workspace secrets.

# Manage secrets

## 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.

## Steps

1. Create a secret with an obviously fake value.

   ```bash theme={"theme":"vesper"}
   agentsfleet secret create github --data='{"api_token":"af_test_00000000"}'
   ```

   ```text theme={"theme":"vesper"}
   ✓ Secret 'github' stored in vault.
   ```

   Replace the fake value through a secret manager. Avoid putting real values in shell history.

2. Confirm that the secret exists.

   ```bash theme={"theme":"vesper"}
   agentsfleet secret show github
   ```

   ```text theme={"theme":"vesper"}
   Secret 'github' exists.
   <varies>
   ```

3. List secret names.

   ```bash theme={"theme":"vesper"}
   agentsfleet secret list
   ```

   ```text theme={"theme":"vesper"}
   github  <varies>
   ```

## Replace a value

Update replaces the stored body in one call. The name stays claimed for the whole call, so fleets that require it keep running.

```bash theme={"theme":"vesper"}
agentsfleet secret update github --data='{"api_token":"af_live_11111111"}'
```

```text theme={"theme":"vesper"}
✓ Secret 'github' updated. The name stayed claimed throughout.
```

Replacement is total. Send the whole object you want stored — a field you omit is absent from the secret afterwards. This is deliberate: a stored secret is never readable, so a partial change could not be checked by the caller.

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}`.

A name the workspace does not hold returns `UZ-VAULT-003` and creates nothing. Claiming a name is `create`'s job alone.

## Verify it works

Install a fleet that declares the secret name. Installation fails with `UZ-BUNDLE-003` when a required name is missing.

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.

```bash theme={"theme":"vesper"}
agentsfleet secret delete github
```

```text theme={"theme":"vesper"}
✓ Secret 'github' removed from vault.
```

Deletion is idempotent. Recreate the same name to restore access with a new value.

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.

## Related pages

* [Connectors](/fleets/connectors)
* [Author a fleet](/fleets/authoring)