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
- In 1Password, create a vault for shed, for example
shed. Any name works. - 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.
- 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:
- 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.
- It creates one item for each service in the vault, holding the service's variables.
- 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
| What | Layout |
|---|---|
| Vault | the one you chose when connecting |
| Item, one per service | Secure Note titled <project> / <service>, for example acme / api |
| Tag | shed/<project>, so the 1Password sidebar nests each project's items under shed |
| Variables | Concealed 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:
| Action | Calls |
|---|---|
| Opening the Variables tab | Reads the service's item, each time the tab loads. |
| Saving variables | Reads and writes the service's item, creating it if it is missing. |
| Opening a project | Reads 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 reference | Reads the items the reference needs. |
| A deployment starts | Reads 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 service | Creates its item with the template's variables. If that fails, the service is not created. |
| Renaming a project | Updates its services' items' titles and tags. If that fails, the rename is not saved. |
| Deleting a service | Archives 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.
| Account | Per token, hourly | Per account, daily |
|---|---|---|
| Business | 10,000 reads, 1,000 writes | 50,000 requests |
| Teams | 1,000 reads, 100 writes | 5,000 requests |
| Families and individual | 1,000 reads, 100 writes | 1,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.