Skip to main content

GETTING STARTED WITH 1PASSWORD VAULTS IN SWAMP

In this tutorial, we will connect a Swamp repository to 1Password, store a secret in a 1Password vault through Swamp, check that it arrived, and write the expression a behavior definition uses to read it.

What we will build

We are going to pull the @swamp/1password extension, create a Swamp vault called my-1password that writes to the 1Password vault named Private, and store an API key in it. At the end we will have a 1Password item named my-api-key and a vault.get() expression that refers to it by name.

Prerequisites

  • Swamp installed (see Install Swamp)
  • A terminal open in a Swamp repository created with swamp repo init
  • A signed-in Swamp account, from swamp auth login, or SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN set in CI
  • The 1Password CLI (op) installed and on your PATH
  • op signed in with a service account (OP_SERVICE_ACCOUNT_TOKEN), desktop app integration, or a Connect Server (OP_CONNECT_HOST and OP_CONNECT_TOKEN)
  • A 1Password vault named Private that the signed-in op can write to

Pull the extension

First, we pull the 1Password extension into the repository:

swamp extension pull @swamp/1password

You will see output like:

INF extension·pull: Pulling "@swamp/1password"@"2026.10.13.1"
INF extension·pull: Identity verified: "@swamp/1password"@"2026.10.13.1"
INF extension·pull: Pulled "@swamp/1password"@"2026.10.13.1"
INF extension·pull: Extracted 6 files:

The repository now has the @swamp/1password vault type.

Create the vault

Next, we create a Swamp vault named my-1password with swamp vault create. We give it the @swamp/1password type and set its one required setting, op_vault, to Private. The Use 1Password guide shows the full command and its --config argument.

From here on, Swamp sends every operation on my-1password to the Private vault in 1Password.

Store a secret

Now we store our first secret:

swamp vault put my-1password my-api-key example-api-key-value

This calls op to write example-api-key-value into the password field of a 1Password item named my-api-key in the Private vault. Open 1Password and you will find the new my-api-key item there.

List the keys

Let's check that Swamp can see the secret:

swamp vault list-keys my-1password

This lists the keys in my-1password, read from the Private vault through op. Notice that my-api-key is in the list and that the value is not shown.

Reference the secret

A behavior definition never contains the value itself. Wherever a definition needs the API key, we write this expression:

${{ vault.get('my-1password', 'my-api-key') }}

The first argument is the Swamp vault name and the second is the key. Swamp reads the value from 1Password when the behavior runs. The Storing Secrets tutorial shows how resolved values are redacted from output.

What we built

We pulled the @swamp/1password extension, created the my-1password vault backed by the 1Password Private vault, stored an API key as a 1Password item, listed it from Swamp, and wrote the vault.get() expression that a behavior definition uses to read it.