1Password

Keep every service's variables in a 1Password vault instead of on this server. shed reads a service's item when it deploys and writes it when you save its variables.

How it works

When 1Password is connected, shed keeps every service's variables in your 1Password account instead of in shed.db. It uses one service account and one vault of your choosing, with an item for each service. The Variables tab and the API don't change: they read and write the service's item instead of the database. Deployments read the items they need when they start.

The service account token is the only 1Password credential shed keeps. It is stored encrypted in shed.db, and the dashboard and API never show it again once it is saved.

Setup

  1. In 1Password, create a vault for shed, for example shed. Any name works.
  2. On 1Password.com, create a service account with Read and Write access to that vault. It needs no other vaults and no permission to create vaults. Copy its token.
  3. In shed, open Settings > 1Password, paste the token, and click Connect. If the service account can access more than one vault, choose the one for shed and click Connect again.

Create the vault yourself rather than letting the service account create one. A vault a service account creates belongs to it, and on Individual and Families accounts you can't give yourself access to it, so you couldn't see your own variables.

1Password fixes a service account's vault access when the account is created, so to use a different vault, create a new service account. 1Password allows 100 service accounts per account; shed needs one.

Connecting can take a while, because shed moves every service's variables out of this server as it connects:

  1. It signs in with the token and lists the vaults it can access. If 1Password rejects the token, or the service account can access no vaults, the card says so and nothing changes.
  2. It creates one item for each service in the vault, holding the service's variables.
  3. It deletes the variables from shed.db and saves the token.

If a step fails, nothing is saved in shed and the card shows the error. Connecting again picks up where it stopped: shed reuses the items it already created.

Once connected, the card shows the vault's name and how many services have an item. The Variables tab of every service says Stored in 1Password in its header.

Over the API, GET /api/onepassword reports whether 1Password is connected, the vault's name, and how many services have an item, without calling 1Password. POST /api/onepassword/vaults with {"token": "ops_…"} lists the vaults the token can access. PUT /api/onepassword with {"token": "ops_…", "vault": "<vault ID>"} connects; without vault, it uses the token's only vault. DELETE /api/onepassword disconnects. See the API.

The vault

WhatLayout
Vaultthe one you chose when connecting
Item, one per serviceSecure Note titled <project> / <service>, for example acme / api
Tagshed/<project>, so the 1Password sidebar nests each project's items under shed
VariablesConcealed fields in a section titled Variables, each titled with the variable's name

Renaming a project renames its services' items and tags. Deleting a service archives its item; you can restore or delete it in 1Password.

Editing variables

Edit a service's variables on its Variables tab or in the 1Password app; both change the same item.

In 1Password, add a field in the item's Variables section and title it with the variable's name, which must use letters, digits, and underscores and not start with a digit. shed reads every field whose title is a valid variable name. Fields with other titles, untitled fields, and notes are ignored, and saving variables in shed keeps them as they are.

References work the same way: ${{ api.STRIPE_SECRET_KEY }} reads STRIPE_SECRET_KEY from the api item.

When 1Password is used

shed calls 1Password only when something needs the values right then:

ActionCalls
Opening the Variables tabReads the service's item, each time the tab loads.
Saving variablesReads and writes the service's item, creating it if it is missing.
Opening a projectReads every service's item, to draw the service map from their references. The dashboard reuses what it read for a minute.
Copying a value that contains a referenceReads the items the reference needs.
A deployment startsReads the service's item, and another service's item when a reference needs one of its values. Each item is read at most once per deployment.
Creating a serviceCreates its item with the template's variables. If that fails, the service is not created.
Renaming a projectUpdates its services' items' titles and tags. If that fails, the rename is not saved.
Deleting a serviceArchives its item once the service is deleted. If archiving fails, the error is logged and the item stays in the vault.

Restarts, crash recovery, shed's own boot, and masking container logs never call 1Password. They reuse the variables recorded on the active deployment. Saved values are masked from 1Password: loading shed's own log reads every service's item, and telemetry reads every item (shed's own) or the project's items, at most once every 30 seconds per sender. If 1Password fails, shed's log fails to load rather than show a value unmasked.

Applying changes

1Password has no change notifications that shed can subscribe to. A change made in the 1Password app, whether a new variable, an edited value, or a rotated secret, reaches the service on its next deployment. Redeploy after you edit an item in 1Password, the same as after saving variables in shed.

Failures

A deployment that can't read an item fails, with the 1Password error in the build log and on the deployment. Common causes are a revoked token, a rate limit, and a network error. The running deployment keeps serving: the read happens before the new container starts.

When 1Password fails, the Variables tab shows the error in place of the variables, and the API answers 502.

A service whose item was deleted or moved out of the vault has no variables to read. Its Variables tab says the item is missing and offers Create item, which creates a new, empty item. Saving variables does the same. Until then its deployments fail, and the API answers 409 with "the 1Password item of service … is missing".

Disconnecting

Settings > 1Password > Disconnect reads every item, copies the variables back into shed.db, encrypted, and forgets the token. The vault and its items stay in 1Password; delete them there if you no longer need them. If any item can't be read, nothing changes and the dialog shows the error.

Connecting again later creates new items from the variables in shed.db.

Limits

  • Rate limits. 1Password limits each service account token per hour, and each 1Password account per day across all its service accounts. Each item read and each write counts.
AccountPer token, hourlyPer account, daily
Business10,000 reads, 1,000 writes50,000 requests
Teams1,000 reads, 100 writes5,000 requests
Families and individual1,000 reads, 100 writes1,000 requests
  • Memory. 1Password's client runs inside shed and uses about 110 MB of memory while 1Password is connected. It loads in the background when shed starts, and when you connect. Disconnecting doesn't free it; the memory is freed on shed's next restart.

Masking

Values stored in 1Password are masked as *** in build and runtime logs, like every other variable. See secret redaction for the limits of masking.