1# 1Password Connect on a remote server
2
3Use a 1Password Connect server when you already run one, for example on a home server or in Kubernetes, and
4want the T3 Code server to read secrets through it. Connect needs no desktop approval, so it works on a
5headless or [remote](./remote-access.md) host.
6
7If you do not run Connect, a [service account](./secrets-1password-service-account.md) is simpler. For the
8basics, see [Secrets](./secrets.md).
9
10## Set it up
11
12In 1Password, create a Connect server and an access token. Limit the token to the vaults T3 Code needs.
13Deploy the Connect API and sync containers where the T3 Code server can reach them.
14Install the [1Password CLI](https://developer.1password.com/docs/cli/get-started/) (`op`) on the machine
15 that runs the T3 Code server.
16Put `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).
22In **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
25Then use references as usual, for example `op://Automation/provider-token/credential`.
26
27## Check that it works
28
29On the server's machine, set `OP_CONNECT_HOST` and `OP_CONNECT_TOKEN` in your shell to the values the
30server uses. Confirm the address is a Connect server, then read a secret with a clean environment so only
31the Connect variables can sign in:
32
34curl -s "$OP_CONNECT_HOST/health"
35env -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"
38
39The health response names the 1Password Connect API. Any other page means the address points at something
40else, such as a reverse proxy that answers for every hostname.
41
42This checks the Connect variables in your shell, not the server's own environment. To confirm the server
43can read the secret, use the reference in a setting and then use the feature that needs it. If the server
44cannot read the secret, that feature shows an error naming the secret provider.
45
46## Things to know
47
48Agents 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.
50Through Connect, `op` can read items but cannot list vaults or accounts. Test with `op read`, not
51 `op vault list`.
52A 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`.
55A Connect token sees only the vaults it was created for. A reference to any other vault cannot be read.
56T3 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.
58Do not set `OP_SERVICE_ACCOUNT_TOKEN` in the same environment.