Install and Configure 1Password CLI in a Home Lab

Outcome

Install 1Password CLI in a home lab, choose the right authentication model for your environment, and use 1Password secret references plus op run so agents and automation can access secrets without leaving plaintext credentials in config files.

Audience and Scope

Audience	New home lab users who want to use 1Password as the password manager and secret-loading tool for local automation
Difficulty	Beginner
Estimated Time	30 to 45 minutes
Assumptions	You have a 1Password subscription, a Linux or desktop system where you can install the CLI, and permission to create or manage a service account if you want headless automation

Before You Start

• Make sure you have a 1Password account with developer access
• Decide whether this machine is an interactive workstation or a headless automation host
• Use the principle of least privilege when deciding which vaults a service account can access
• Plan where you will store your service-account token file, wrapper scripts, and environment-reference files

Hardware and Software

Step-by-Step

Step 1: Choose the right authentication model

Objective: Pick the 1Password pattern that matches how the machine will be used.

Actions:

• Use desktop app integration on your personal workstation when you want interactive sign-in and approval prompts
• Use a service account on a headless server or unattended automation host
• Use a service account for wrappers that start MCP servers, scripts, or background jobs

Verification:

• You know whether this system will sign in interactively or use a service-account token
• You know which vaults the workflow actually needs

Common failure and fix: If you are trying to run unattended automation, do not depend on desktop app integration. Use a service account instead.

Step 2: Install 1Password CLI

Objective: Put the op binary on the machine and confirm it works.

Actions:

• Open the official 1Password CLI install page and choose the instructions for your operating system and package manager
• On Linux, 1Password documents install paths for APT, YUM, Alpine, NixOS, and manual installation
• After installation, run:

op --version

Verification:

• The op command is in your shell path
• The version check returns a version instead of command-not-found

Common failure and fix: If the shell cannot find op, move the binary into a directory in your PATH or reopen the shell after installation.

Step 3: Configure desktop app integration if this is an interactive machine

Objective: Let the CLI reuse your local 1Password app session when the machine is meant for interactive use.

Actions:

• Install and unlock the 1Password desktop app
• On Linux, turn on system authentication in the app security settings
• Open the app’s developer settings and enable 1Password CLI integration
• Run these checks:

op vault list
op whoami

Verification:

• The CLI can authenticate through the desktop app
• The commands above work from your shell

Common failure and fix: If app integration does not work on Linux, confirm that PolKit and a running authentication agent are available.

Step 4: Create a service account for headless automation

Objective: Give your home lab automation a non-interactive way to resolve secrets.

Actions:

• In 1Password Developer settings, create a service account
• Grant access only to the vaults or Environments your automation needs
• Save the token immediately. 1Password only shows it once
• Remember that service-account permissions and vault access are immutable after creation

Verification:

• You have a stored service-account token
• You know exactly which vaults it can read

Common failure and fix: If you need different vault access later, create a new service account with the correct permissions instead of trying to edit the old one.

Step 5: Store the service-account token safely

Objective: Keep the token out of shell history, source control, and plaintext config.

Actions:

• Create a runtime file readable only by the local admin account
• Store the token in a file like service-account.env using the environment variable name below
• Set the file permissions to owner-read and owner-write only

OP_SERVICE_ACCOUNT_TOKEN=ops_<redacted-token>

Verification:

• The token file exists with restricted permissions
• The token does not appear in your shell history or shared config files

Common failure and fix: If the token is pasted into a general-purpose .env file that gets reused broadly, move it into a dedicated runtime file with tighter permissions.

Step 6: Sign in or activate the service account

Objective: Prove that the CLI can authenticate the way you intended.

Actions:

• For desktop integration, run a simple CLI command and complete the sign-in flow
• For a service account, source the runtime file and confirm the identity:

source /path/to/service-account.env
op whoami

Verification:

• op whoami reports the active session or service account
• The CLI can read only the vaults it should have access to

Common failure and fix: If 1Password Connect variables are also set, clear them before using the service account:

unset OP_CONNECT_HOST
unset OP_CONNECT_TOKEN

Step 7: Store project secrets as secret references

Objective: Convert plaintext runtime secrets into references that op run can resolve at process start.

Actions:

• Create or choose a vault for your project secrets
• Save each secret as a 1Password item or field
• Map your runtime environment variables to secret references in an env file

UNIFI_API_KEY=op://HomeLab/unifi-mcp-api-key/password
ANOTHER_SECRET=op://HomeLab/example-item/password

Verification:

• Your env file contains secret references instead of plaintext values
• The vault and item names or IDs match real objects in 1Password

Common failure and fix: If a secret reference fails, check the vault name, item name, field name, and service-account permissions.

Step 8: Run applications with op run

Objective: Start processes with secrets injected only for the duration of the subprocess.

Actions:

• Use op run with an env file to launch the target application
• Wrap repeated commands in a shell script so the calling client never needs raw secrets
• Use the same pattern for MCP servers, cron jobs, and helper scripts

op run --env-file=/path/to/project.env -- <command>
op run --env-file=/path/to/unifi-mcp.env -- uvx --from unifi-mcp-server unifi-mcp-server

Verification:

• The process starts successfully
• The target application can read the resolved environment variables

Common failure and fix: If a variable expands to the secret reference string instead of the secret value, run the variable-expanding command in a subshell so op run resolves the secret first.

Step 9: Lock down and document the runtime

Objective: Make the setup repeatable and safer to operate.

Actions:

• Keep the token file and secret-reference env files outside source control
• Document which wrappers depend on 1Password CLI
• Rotate the service-account token when permissions or ownership change
• Use separate vaults or Environments for dev, staging, and production where appropriate

Verification:

• Runtime files are documented and permissioned correctly
• Team members know which 1Password objects back each automation path

Common failure and fix: If the setup becomes hard to audit, split by project and reduce vault access instead of sharing one large service account across everything.

Validation Checklist

• The op binary is installed and working
• The intended authentication model is confirmed
• The service-account token is stored in a restricted runtime file if you use headless automation
• Secret-reference env files contain references, not plaintext secrets
• op run starts the target wrapper or application successfully
• The account or service account only has the vault access it actually needs

Operations and Maintenance

• Use service accounts for unattended automation and desktop integration for interactive admin work
• Rotate service-account tokens when access requirements change
• Prefer separate vaults or Environments for different contexts
• Review wrapper scripts periodically to make sure secrets are still scoped correctly

Troubleshooting and Rollback

• CLI not found: Fix the install path or reopen the shell
• Desktop integration not working: Confirm the app is unlocked and CLI integration is enabled
• Service account fails: Recheck the service-account token and vault access
• Wrong auth mode: Clear Connect variables if you intend to use a service account
• Rollback: Remove the wrapper or env-file integration and return to manual secret loading only long enough to recover safely, then re-secure the workflow

Source Links

• 1Password developer LLM index
• Get started with 1Password CLI
• Get started with 1Password Service Accounts
• Use service accounts with 1Password CLI
• Load secrets into the environment
• op run reference

My Implementation Notes

For Home Lab agents, the most durable pattern is usually a dedicated runtime file for the service-account token, a project-specific env file full of secret references, and a wrapper script that launches the target process through the same env-file pattern shown above. This avoids storing plaintext secrets in MCP config files, compose files, or shell profiles.