STORING SECRETS
In this tutorial, we will store a secret in a vault, annotate it with metadata,
reference the secret from a behavior using a vault.get() expression, and see
Swamp automatically redact it from output.
What we will build
We are going to use the local encrypted vault every new repository gets, store an API token in it, then create a behavior that uses the token. When the behavior runs, we will see the secret resolved into the command but redacted from all output — logs, data, and the terminal.
Prerequisites
- Swamp installed (see Install Swamp)
- A terminal open in an empty directory
Sign in
Every Swamp command needs a swamp-club.com account, so we sign in first:
$ swamp auth loginYour browser opens at swamp-club.com. Once you sign in, the terminal shows Authenticated with your username. If you are already signed in, skip this step.
Initialize the repository
First, we create a fresh Swamp repo:
$ mkdir vault-tutorial
$ cd vault-tutorial
$ swamp repo init --tool noneYou will see the Swamp banner followed by:
Initialized swamp repository at /.../vault-tutorial (tools: none)
Created vault default (local_encryption) for secrets and sensitive outputsCheck the vault
Vaults store secrets. swamp repo init already created one for us: a vault
named default, of type local_encryption, which encrypts secrets on disk with
a key generated for this machine. We confirm it is there:
$ swamp vault search --json{
"query": "",
"results": [
{
"id": "...",
"name": "default",
"type": "local_encryption",
"createdAt": "..."
}
]
}We will store our secret in default. A repository can hold more vaults, for
example one backed by a cloud secrets manager, but we do not need another one
for this tutorial.
Store a secret
Now we store a secret in the default vault. The value is encrypted at rest —
it never appears in plain text in any file:
$ swamp vault put default api-token my-secret-valueinfo vault·put Stored secret "api-token" in vault "default"We can verify it is stored without seeing the value:
$ swamp vault list-keys defaultinfo vault·list-keys Vault "default" ("local_encryption"): 1 key(s)
info vault·list-keys - "api-token"Annotate the secret
Secrets accumulate over time and it becomes hard to remember what each one is for. We add metadata — a URL to the settings page where the token was created and a note about its purpose:
$ swamp vault annotate default api-token \
--url "https://example.com/settings/api" \
--notes "Production API token"info vault·annotate Annotated "api-token" in vault "default" (fields: "url, notes")Now inspect shows the metadata without exposing the value:
$ swamp vault inspect default api-tokeninfo vault·inspect Metadata for "api-token" in vault "default":
info vault·inspect size: 15 chars (15 bytes)
info vault·inspect url: "https://example.com/settings/api"
info vault·inspect notes: "Production API token"
info vault·inspect updated: "..."
info vault·inspect refresh-hook: (none)Notice we can see the size, URL, notes, and when it was last updated — but never the value itself.
Use the secret in a behavior
Now we create a behavior that references the secret. This is where vault.get()
comes in:
$ swamp behavior create command/shell api-callerOpen the definition file (swamp behavior edit api-caller) and set the run
global argument to a command that uses the secret:
globalArguments:
run: "echo \"Calling API with token: ${{ vault.get('default', 'api-token') }}\""The ${{ vault.get('default', 'api-token') }} expression reads the secret from
the vault at evaluation time. The secret is resolved into the command before
execution.
Now run it:
$ swamp behavior run api-caller execute Resolved api-caller (command/shell)
Executing execute · 04:05:30 UTC
Calling API with token: ***
Completed execute on api-caller succeeded in 25ms · 04:05:30 UTC
┌───────────────────────────────────────────────────────────────────────────┐
│ Arguments │
│ run echo "Calling API with token: ${{ vault.get('default', 'api-... │
│ │
│ Data produced │
│ result │
│ exitCode 0 │
│ executedAt 2026-10-14T04:05:30.783Z │
│ command echo "Calling API with token: ***" │
│ durationMs 13 │
│ stdout Calling API with token: *** │
│ stderr │
│ │
└───────────────────────────────────────────────────────────────────────────┘Notice *** where the token value should be. Swamp detected that the output
contains a vault secret and redacted it automatically.
Check the data
Let us look at the stored data to confirm the secret is redacted there too:
$ swamp data query 'behaviorName == "api-caller" && name == "result" && isLatest' \
--single --json --select content{
"exitCode": 0,
"executedAt": "...",
"command": "echo \"Calling API with token: ***\"",
"durationMs": 13,
"stdout": "Calling API with token: ***",
"stderr": ""
}The secret is *** in the command, in stdout, and everywhere else it appears.
The actual value was used when the shell command ran, but it is never stored in
plain text in the data output.
Verify vault health
Swamp can scan behavior definitions for secrets that were accidentally stored as plain text instead of vault references:
$ swamp doctor secretsScanning definitions for cleartext sensitive global arguments…
✓ No cleartext sensitive global arguments found (1 definition(s) scanned)What we built
We used the repository's default vault, stored a secret, annotated it with
metadata for future reference, used vault.get() to reference it from a
behavior definition, and confirmed that Swamp automatically redacts vault
secrets from all output. We also ran swamp doctor secrets to verify no
cleartext secrets leaked into behavior definitions.