@devries-cameron20 / t3code-1 / commits / d0f1f7200d
Fork 0

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

docs(secrets): sign op in with a service account or Connect on remote servers (#31760)

Co-authored-by: Julius Marminge <51714798+juliusmarminge@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

Yordis Prieto committed Nov 8, 2026 at 21:25 UTC d0f1f7200dce1229f75314b3d9eb1d7ac3abb607
3 files changed +115
docs/user/secrets-1password-connect.md new
+58
@@ -0,0 +1,58 @@
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.
docs/user/secrets-1password-service-account.md new
+53
@@ -0,0 +1,53 @@
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.
docs/user/secrets.md
+4
@@ -14,6 +14,10 @@ work everywhere.
14 signed in on the machine that runs the T3 Code server. When you use T3 Code on another machine or
15 from your phone, that is the remote machine, not the device in front of you.
16
17 +A desktop sign-in asks for approval on that machine, which a remote user cannot answer. On a remote
18 +or headless server, sign `op` in with a [service account](./secrets-1password-service-account.md) or a
19 +[Connect server](./secrets-1password-connect.md) instead.
20 +
21 To add one, open **Settings → Secrets**, select **Add provider**, and enter a name and the
22 1Password account: the shorthand, sign-in address (without `https://`), or ID that
23 `op account list` shows. Secret providers belong to the environment you are connected to. Each