The best way to control Claude Code, Codex and more from any computer or phone
| 1 | # 1Password service account on a remote server |
| 2 | |
| 3 | Use a 1Password service account when the T3 Code server runs on a machine you are not sitting at, such as a |
| 4 | headless host, a VM, or a [background service](./background-service.md) you reach through |
| 5 | [remote access](./remote-access.md). |
| 6 | |
| 7 | Signing in to 1Password through its desktop app asks for approval on the server's machine. A remote user |
| 8 | never sees that prompt, so the secret cannot be read. A service account signs in with a token instead, so |
| 9 | nothing needs approving. |
| 10 | |
| 11 | For the basics, see [Secrets](./secrets.md). To use a self-hosted Connect server instead, see |
| 12 | [1Password Connect](./secrets-1password-connect.md). |
| 13 | |
| 14 | ## Set it up |
| 15 | |
| 16 | 1. In 1Password, open Developer, then Service Accounts, and create one. |
| 17 | 2. Give it read access to only the vaults T3 Code needs. Access is fixed when the account is created, and a |
| 18 | service account cannot reach Personal, Private, or Employee vaults. |
| 19 | 3. Copy the token. It is shown once. |
| 20 | 4. Install the [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) on the machine |
| 21 | that runs the T3 Code server. |
| 22 | 5. Put `OP_SERVICE_ACCOUNT_TOKEN` in the server's environment. For a background service, add it to |
| 23 | `service.env` and restart the service. See |
| 24 | [Configure the service environment](./background-service.md#configure-the-service-environment). |
| 25 | 6. In **Settings → Secrets**, select **Add provider**. The account is required, but `op` ignores it while |
| 26 | the token is set, so enter any sign-in address such as `my.1password.com`. |
| 27 | |
| 28 | Then use references as usual, for example `op://Automation/provider-token/credential`. |
| 29 | |
| 30 | ## Check that it works |
| 31 | |
| 32 | On the server's machine, set `OP_SERVICE_ACCOUNT_TOKEN` in your shell to the same token the server uses, |
| 33 | then read a secret with a clean environment so only the token can sign in: |
| 34 | |
| 35 | ```bash |
| 36 | env -i PATH="$PATH" HOME="$(mktemp -d)" OP_SERVICE_ACCOUNT_TOKEN="$OP_SERVICE_ACCOUNT_TOKEN" \ |
| 37 | op read --no-newline "op://Automation/provider-token/credential" >/dev/null && echo "Secret read" |
| 38 | ``` |
| 39 | |
| 40 | If it prints `Secret read`, the token can read the secret. This checks your shell, not the server's own |
| 41 | environment. To confirm the server can read it, use the reference in a setting and then use the feature |
| 42 | that needs it. If the server cannot read the secret, that feature shows an error naming the secret provider. |
| 43 | |
| 44 | ## Things to know |
| 45 | |
| 46 | - Agents run with the server's environment, so an agent can use the token to read anything the service |
| 47 | account can. Give it only vaults whose items you would let an agent read. |
| 48 | - A name in a reference can contain letters, digits, spaces, `.`, `_`, and `-`. An item titled |
| 49 | `Service Token: CI` cannot be written as a reference, so use its item ID instead, for example |
| 50 | `op://Automation/<item-id>/credential`. |
| 51 | - T3 Code waits up to 45 seconds for 1Password. After that the secret counts as unreadable and the feature |
| 52 | that needs it shows an error naming the secret provider. |
| 53 | - Do not set `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` in the same environment. |