The best way to control Claude Code, Codex and more from any computer or phone

main
md 53 lines 2.97 KB
Rendered Raw
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.