1Password CLI & Docker Deployment Guide#

2026-08-03 Troubleshooting popups for MCP server with account tokens - To implement on VM’s using OP: agy –conversation=22663bf8-df61-4167-99ad-7a3d9884c879 1

1. Installation#

1.1. Install 1Password CLI (Linux VM)#

# 1. Add the key
curl -sS [https://downloads.1password.com/linux/keys/1password.asc](https://downloads.1password.com/linux/keys/1password.asc) | sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg

# 2. Add the repository
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] [https://downloads.1password.com/linux/debian/amd64](https://downloads.1password.com/linux/debian/amd64) stable main' | sudo tee /etc/apt/sources.list.d/1password.list

# 3. Update and Install
sudo apt update && sudo apt install 1password-cli

1.2. Install 1Password CLI (LXC)#

# 1. Add the key
# 1. Ensure system initialization package is present
sudo apt update && sudo apt install systemd-sysv -y

# 2. Add the key securely
curl -sS [https://downloads.1password.com/linux/keys/1password.asc](https://downloads.1password.com/linux/keys/1password.asc) | sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg

# 3. Add the official repository
echo 'deb [arch=amd64 signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] [https://downloads.1password.com/linux/debian/amd64](https://downloads.1password.com/linux/debian/amd64) stable main' | sudo tee /etc/apt/sources.list.d/1password.list

# 4. Update repositories and install the CLI
sudo apt update && sudo apt install 1password-cli -y

1.3. Install 1Password CLI (macOS)#

# Install via Homebrew
brew install 1password-cli

2. Authentication & Account Setup#

2.1. Initial Account Setup (One-time)#

To add your 1Password account to the CLI manually:

op account add --address my.1password.com --email marc.ouellet@gmail.com

##To sign in and authenticate your active terminal session:
eval $(op signin)

2.2. Enable Persistence (Linux)#

# Enable the system keyring
op config edit --device-details on

# Set the account to stay signed in
op account edit --sign-in-address my.1password.com --biometry on

2.3. Enable Biometric Integration (macOS)#

Open the 1Password Desktop App.
Navigate to Settings > Developer.
Check the box for Connect with 1Password CLI.
Run op signin in the terminal to perform the initial handshake.
Verify with op whoami (triggers Touch ID).

# Test
op item get "Gemini-CLI" --vault "Homelab" --format json

2.4. Non-Interactive / Unattended Access (Service Account Token)#

Full documentation for MCP Service Account Token setup, rotation, and re-creation is maintained in the MCP Configuration Guide — §2 Service Account Token Management.

In short: Setting OP_SERVICE_ACCOUNT_TOKEN in ~/.zshrc allows all 29 MCP servers using op run to authenticate silently without GUI popups. The token is scoped to the Homelab-MCP vault only.

Setting this token completely disables biometric Touch ID authentication for all op commands in that shell. The two modes are mutually exclusive.

2.5. Per-Command Access to Personal Vaults#

The MCP service account is intentionally scoped to the Homelab-MCP vault. Some workstation utilities, such as the NetBox Google Sheets sync, use items in the personal Homelab vault. Do not grant the service account access to Homelab and do not remove the service account token from ~/.zshrc.

Instead, omit the token only for commands that need the personal 1Password session:

env -u OP_SERVICE_ACCOUNT_TOKEN op whoami
env -u OP_SERVICE_ACCOUNT_TOKEN op read \
  'op://Homelab/netbox/add more/GOOGLE_CLIENT_ID' >/dev/null

If the personal CLI session has not been initialized on the Mac, sign in without changing the service-account environment variable:

eval "$(env -u OP_SERVICE_ACCOUNT_TOKEN op signin)"

The NetBox alias uses the same per-command isolation:

alias netbox='env -u OP_SERVICE_ACCOUNT_TOKEN python3 "$HOME/Scripts/Linux/Netbox/Netbox_sync_gsheets_to_netbox.py"'

3. Secret Management & Deployment#

3.1. Setup 1Password Secret#

Create a Secure Note or API Credential in the Homelab vault.
Title the note (e.g., Cloudflare).
Add a field: Label = TUNNEL_TOKEN, Value = [Your Secret].

3.2. Configure .env File#

Create .env and add the reference:

TUNNEL_TOKEN=op://Homelab/Cloudflared/TUNNEL_TOKEN

3.3. Deployment & Verification#

# In Linux environments without biometric persistence:
eval $(op signin)

# Run deployment
op run --env-file=".env" -- docker compose up
docker logs cloudflared

4. Aliases for Docker and 1Password#

Add these to your .bashrc or .zshrc:

# 1Password & Docker Compose Alias - detach mode
alias 1p='op whoami >/dev/null 2>&1 || eval $(op signin); op run --env-file=".env" -- docker compose up -d && docker compose logs -f'

# Docker Cleanup Alias
alias clean='docker system prune --all --volumes'

# Compose Down/Up Aliases
alias up='docker compose up -d && docker compose logs -f'
alias down='docker compose down --remove-orphans'

5. Reference#

Private Tunnel Token Reference: TUNNEL_TOKEN=op://Homelab/PRIVATE/TUNNEL_TOKEN

If IPV6 Issues with 1Password-CLI#

# Run this in the affected VM
grep -q "^#precedence ::ffff:0:0/96  100" /etc/gai.conf && sudo sed -i 's/^#precedence ::ffff:0:0\/96  100/precedence ::ffff:0:0\/96  100/' /etc/gai.conf || grep -q "^precedence ::ffff:0:0/96  100" /etc/gai.conf || echo "precedence ::ffff:0:0/96  100" | sudo tee -a /etc/gai.conf > /dev/null

# Run this to revert if needed
sudo sed -i 's/^precedence ::ffff:0:0\/96  100/#precedence ::ffff:0:0\/96  100/' /etc/gai.conf

reboot