Skip to main content

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 login

Your 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 none

You will see the Swamp banner followed by:

Initialized swamp repository at /.../vault-tutorial (tools: none)
Created vault default (local_encryption) for secrets and sensitive outputs

Check 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-value
info    vault·put Stored secret "api-token" in vault "default"

We can verify it is stored without seeing the value:

$ swamp vault list-keys default
info    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-token
info    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-caller

Open 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 secrets
Scanning 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.