The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 1 | # 1Password Connect on a remote server |
| 2 | |
| 3 | Use a 1Password Connect server when you already run one, for example on a home server or in Kubernetes, and |
| 4 | want the T3 Code server to read secrets through it. Connect needs no desktop approval, so it works on a |
| 5 | headless or [remote](./remote-access.md) host. |
| 6 | |
| 7 | If you do not run Connect, a [service account](./secrets-1password-service-account.md) is simpler. For the |
| 8 | basics, see [Secrets](./secrets.md). |
| 9 | |
| 10 | ## Set it up |
| 11 | |
| 12 | 1. In 1Password, create a Connect server and an access token. Limit the token to the vaults T3 Code needs. |
| 13 | 2. Deploy the Connect API and sync containers where the T3 Code server can reach them. |
| 14 | 3. Install the [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) on the machine |
| 15 | that runs the T3 Code server. |
| 16 | 4. Put `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` in the server's environment. `OP_CONNECT_HOST` is the Connect |
| 17 | API's address, including the port if it is not the default for its scheme. Use an `https://` address |
| 18 | unless Connect runs on the same machine or a private network you trust, because the token and secrets |
| 19 | travel over that connection. For a |
| 20 | [background service](./background-service.md), add both to `service.env` and restart the service. See |
| 21 | [Configure the service environment](./background-service.md#configure-the-service-environment). |
| 22 | 5. In **Settings → Secrets**, select **Add provider**. The account is required, but `op` ignores it while |
| 23 | Connect is configured, so enter any sign-in address such as `my.1password.com`. |
| 24 | |
| 25 | Then use references as usual, for example `op://Automation/provider-token/credential`. |
| 26 | |
| 27 | ## Check that it works |
| 28 | |
| 29 | On the server's machine, set `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` in your shell to the values the |
| 30 | server uses. Confirm the address is a Connect server, then read a secret with a clean environment so only |
| 31 | the Connect variables can sign in: |
| 32 | |
| 33 | ```bash |
| 34 | curl -s "$OP_CONNECT_HOST/health" |
| 35 | env -i PATH="$PATH" HOME="$(mktemp -d)" OP_CONNECT_HOST="$OP_CONNECT_HOST" OP_CONNECT_TOKEN="$OP_CONNECT_TOKEN" \ |
| 36 | op read --no-newline "op://Automation/provider-token/credential" >/dev/null && echo "Secret read" |
| 37 | ``` |
| 38 | |
| 39 | The health response names the 1Password Connect API. Any other page means the address points at something |
| 40 | else, such as a reverse proxy that answers for every hostname. |
| 41 | |
| 42 | This checks the Connect variables in your shell, not the server's own environment. To confirm the server |
| 43 | can read the secret, use the reference in a setting and then use the feature that needs it. If the server |
| 44 | cannot read the secret, that feature shows an error naming the secret provider. |
| 45 | |
| 46 | ## Things to know |
| 47 | |
| 48 | - Agents run with the server's environment, so an agent can use the Connect token to read anything it can. |
| 49 | Give the token only vaults whose items you would let an agent read. |
| 50 | - Through Connect, `op` can read items but cannot list vaults or accounts. Test with `op read`, not |
| 51 | `op vault list`. |
| 52 | - A name in a reference can contain letters, digits, spaces, `.`, `_`, and `-`. An item titled |
| 53 | `Service Token: CI` cannot be written as a reference, so use its item ID instead, for example |
| 54 | `op://Automation/<item-id>/credential`. |
| 55 | - A Connect token sees only the vaults it was created for. A reference to any other vault cannot be read. |
| 56 | - T3 Code waits up to 45 seconds for 1Password. After that the secret counts as unreadable and the feature |
| 57 | that needs it shows an error naming the secret provider. |
| 58 | - Do not set `OP_SERVICE_ACCOUNT_TOKEN` in the same environment. |