1Password Environments & CLI (op) Migration Guide: Local Mac & Headless Ubuntu

🧭 Executive Overview: The Dual-Horizon Secrets Architecture

One of the greatest security blind spots in modern software engineering and operations is credential sprawl in .env files. Developers inadvertently commit them to GitHub, leave them unencrypted on developer laptops, and bake them into staging and production servers.

1Password solves this problem across two distinct operational horizons:

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                     1PASSWORD SECRETS MANAGEMENT PARADIGM                              │
├──────────────────────────┬─────────────────────────────────────────────────────────────┤
│ 1. LOCAL WORKSTATIONS    │ • 1Password Environments with LOCALLY MOUNTED `.env` FILES. │
│    (Interactive macOS)   │ • Leverages UNIX Named Pipes (FIFOs).                       │
│                          │ • 0 bytes written to disk; authorized via Touch ID.         │
├──────────────────────────┼─────────────────────────────────────────────────────────────┤
│ 2. HEADLESS SERVERS      │ • 1Password CLI (`op run`) + SERVICE ACCOUNTS.              │
│    (Ubuntu `luke-sky`)   │ • Secret Reference URIs (`op://HomeLab/Item/Field`).        │
│                          │ • Machine token injection into RAM; safe in git & backups.  │
└──────────────────────────────────────────────────────────┴─────────────────────────────┘

🛠️ Module 1: Local Mac .env Migration

1Password’s Developer Environments feature mounts .env files dynamically using UNIX named pipes (FIFOs). Your local build tools (Next.js, Vite, Node dotenv, Python) read the file normally, but the plaintext contents never exist on your SSD.

Step 1: Backup Your Existing Local .env

Before mounting, preserve a temporary backup of your current file:

cp .env .env.backup

Step 2: Create a 1Password Environment & Import Variables

1. Open and unlock the 1Password desktop app.
2. From the menu bar, navigate to Developer > View Environments.
3. Click New environment (top right) and name it: project-local.
4. Select your account and save.
5. In the new Environment screen, click Import .env file.
6. Select your .env.backup file. 1Password will parse all key-value pairs (database URLs, API tokens, service keys) and securely encrypt their values.

Step 3: Remove the Plaintext File & Mount the Named Pipe

1Password cannot mount over an existing physical file on disk. Remove the original:

rm .env

Now, mount the 1Password Environment:

1. In the 1Password app under your Environment, look at the Connect to section.
2. Click Connect next to Local .env file.
3. Choose your project directory path (/path/to/project/.env).
4. Click Mount .env file.

Step 4: Verify the Mount in Your Terminal

Run a directory listing in your project:

ls -l .env

Look at the very first character of the permissions string:

prw-r--r--  1 donniepage  staff  0  Oct 10 12:00 .env

Notice the p—it is a named pipe, taking up 0 bytes on disk. When your local server (npm run dev) starts up, 1Password authorizes the process via Touch ID, streams the environment variables into process memory, and closes the pipe.

🐧 Module 2: Setting Up 1Password CLI on Headless Servers

Because headless Linux servers lack a desktop GUI or Touch ID sensor, interactive user logins (op signin) are not used. Instead, 1Password uses Service Accounts—secure machine tokens designed for servers, daemons, and automated environments.

1Password Families Account Note:

On 1Password Families accounts, the web GUI might not show the “Developer” tab for creating Service Accounts. You can generate them directly via the 1Password CLI on your primary Mac:

op service-account create server-srv --vault "HomeLab:read_items"

(Copy the generated service account token starting with ops_...).

Step 1: Install 1password-cli on Ubuntu

On your remote host, install the official package:

curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
  sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \
  sudo tee /etc/apt/sources.list.d/1password.list

sudo apt-get update && sudo apt-get install -y 1password-cli

Step 2: Configure System Environment on Headless Server

Store the machine token in the root environment:

echo 'OP_SERVICE_ACCOUNT_TOKEN="ops_..."' | sudo tee -a /etc/environment
source /etc/environment

Verify non-interactive resolution:

op whoami

⚡ Module 3: Zero-Plaintext Runtime Injection (op run)

With the service account configured, create a .env template that contains zero secrets, only pointers:

# .env (Safe to commit to Git)
DB_HOST=127.0.0.1
DB_PORT=5432
DB_PASSWORD=op://HomeLab/PostgreSQL-Production/password
JWT_SECRET=op://HomeLab/Auth-Service/secret

Launch your application with runtime injection:

op run --env-file=.env -- npm start

op run intercepts every op:// reference, pulls the values into RAM, and launches the node process. The secret values are never saved to disk and never leak into logs.