DEV Community

JasperNoBoxDev
JasperNoBoxDev

Posted on • Originally published at noboxdev.com

NoxKey — A macOS Secrets Manager With Touch ID and AI Agent Detection

#security #macos #opensource #cli

We were debugging a Stripe integration at 1am when Claude printed a live API key in its debug output. Full key. Right there in the conversation log.

The agent was not malicious. The system was broken. The secret sat in a .env file. The agent read the file and included the value in its response. That is what agents do — they read project files and use what they find. The .env file was the vulnerability, not the agent.

That night we started building NoxKey.

A macOS secrets manager built for developers

NoxKey is a macOS menu bar app and CLI that stores secrets in the macOS Keychain, protected by Touch ID. No cloud. No accounts. No subscription. Your secrets live in Apple's encrypted storage on your machine and nowhere else.

When an AI agent requests a secret, NoxKey detects it automatically and delivers the value through an encrypted handoff — the secret reaches the agent's process environment without ever appearing in its conversation context.

Keychain storage. Touch ID authentication. Encrypted handoff for AI agents.

0
cloud connections

30s
to install


0
config needed
Enter fullscreen mode Exit fullscreen mode

Architecture: menu bar app + CLI over a Unix socket

NoxKey has two pieces:

Menu Bar App
SwiftUI · Native macOS

Touch ID

Agent Detection

Keychain Access

Session Manager

Unix
Socket

CLI
Swift · /usr/local/bin/noxkey

get / set / ls

import / unlock

peek / strict

Encrypted Handoff

macOS Keychain

The menu bar app is a native SwiftUI application. It manages the Keychain, handles Touch ID prompts, performs process-tree agent detection, and serves requests over a Unix domain socket. This is the server. It has Keychain entitlements, biometric access, and full control over what gets returned to whom.

The CLI (noxkey) talks to the menu bar app over that Unix socket. It does not touch the Keychain directly — every request goes through the server, which validates the caller independently.

Why a Unix socket instead of XPC or HTTP? Unix sockets provide LOCAL_PEERPID — the kernel tells the server exactly which process connected. No authentication tokens to manage. No port conflicts. No network exposure. The socket file lives at a user-specific path, accessible only to your user account.

Install this macOS secrets manager in 30 seconds 

$ brew install no-box-dev/noxkey/noxkey

==> Downloading noxkey-0.6.43.tar.gz
==> Installing noxkey
==> Caveats
NoxKey menu bar app installed to /Applications.
CLI installed to /usr/local/bin/noxkey.
==> Summary
  /Applications/NoxKey.app
  /usr/local/bin/noxkey
Enter fullscreen mode Exit fullscreen mode

Launch NoxKey.app from your Applications folder. It appears in the menu bar — a small key icon. That is the server running. The CLI works immediately.

$ noxkey --version
noxkey 0.6.43
Enter fullscreen mode Exit fullscreen mode

No account creation. No master password. No onboarding wizard. It uses your existing macOS login Keychain and your existing fingerprint.

Replace your .env files with Keychain storage

If you have dozens of .env files scattered across your machine, the first step is importing them.

$ noxkey import myorg/api .env
[Touch ID prompt]
Imported 6 secrets:
  myorg/api/STRIPE_KEY
  myorg/api/DATABASE_URL
  myorg/api/REDIS_URL
  myorg/api/CLOUDFLARE_TOKEN
  myorg/api/SENDGRID_KEY
  myorg/api/JWT_SECRET

$ noxkey ls myorg/api/
  myorg/api/CLOUDFLARE_TOKEN
  myorg/api/DATABASE_URL
  myorg/api/JWT_SECRET
  myorg/api/REDIS_URL
  myorg/api/SENDGRID_KEY
  myorg/api/STRIPE_KEY

$ rm .env
Enter fullscreen mode Exit fullscreen mode

Secrets are organized as org/project/KEY. One secret, one location, accessible from any terminal in any project directory. No more duplicating the same Cloudflare token across six repos.

Daily usage: Touch ID for every API key access

The core pattern is one line:

$ eval "$(noxkey get myorg/api/STRIPE_KEY)"
[Touch ID prompt]
$ echo $STRIPE_KEY
sk_live_...  # available in your shell environment
Enter fullscreen mode Exit fullscreen mode

Touch ID fires. The secret loads into your shell environment. Your script or application reads it from $STRIPE_KEY like any environment variable.

Session unlock eliminates friction
For batch operations — say you need five secrets to run your dev server — run noxkey unlock myorg/api once with Touch ID. All subsequent get calls under that prefix skip biometric auth for a configurable window. The session is bound to your PID and process start time, so PID recycling cannot hijack it.

Need multiple secrets at once? Session unlock handles that:

$ noxkey unlock myorg/api
[Touch ID prompt — once]
Session unlocked for myorg/api/* (expires in 15 minutes)

$ eval "$(noxkey get myorg/api/STRIPE_KEY)"    # no Touch ID
$ eval "$(noxkey get myorg/api/DATABASE_URL)"   # no Touch ID
$ eval "$(noxkey get myorg/api/REDIS_URL)"      # no Touch ID
Enter fullscreen mode Exit fullscreen mode

One fingerprint, then flow. The session is bound to your process ID and its start time — PID recycling cannot hijack it.

For your most sensitive secrets, strict mode overrides sessions:

$ noxkey strict myorg/api/STRIPE_KEY
# This key ALWAYS requires Touch ID, even during an active session
Enter fullscreen mode Exit fullscreen mode

How AI agent detection works

When Claude Code runs noxkey get, you do not configure anything. Detection is automatic.

noxkey PID 61023 — get myorg/api/STRIPE_KEY    └─ zsh PID 61020 — spawned shell      └─ node PID 58401 — Claude Code runtime        └─ claude PID 58399 — MATCH! Agent detected Encrypted Handoff ← AES-256-CBC → temp script → source → self-delete Result: $STRIPE_KEY in shell env. Raw value never in conversation context.

The agent can make API calls, run your test suite, and deploy your app. It just cannot see, log, or echo the raw secret value. If it tries to use --raw or --copy, the CLI blocks it.

The six most common agent leak patterns — reading .env files, echoing secrets in debug output, storing values in conversation logs, hardcoding them in generated code, passing them to spawned processes — are all mitigated by this approach.

Security, DX, and agent safety features

Security 

🤚
Touch ID on every access
Enter fullscreen mode Exit fullscreen mode

Not a password, not a PIN. Your fingerprint. Every time.

🔒
macOS Keychain storage
Enter fullscreen mode Exit fullscreen mode

Apple's Data Protection Keychain, backed by the Secure Enclave. Not a custom vault.

🚫
Zero network connections
Enter fullscreen mode Exit fullscreen mode

NoxKey never phones home. No telemetry, no sync. Your secrets never leave your machine.

🛡
Strict mode
Enter fullscreen mode Exit fullscreen mode

High-value secrets always require Touch ID, even during unlocked sessions.

🚨
DLP guard
Enter fullscreen mode Exit fullscreen mode

Scans agent output for leaked secret values using 8-character fingerprints. Blocks leaks before they enter AI context.

Developer experience 

⚡
One command
Enter fullscreen mode Exit fullscreen mode

eval "$(noxkey get org/proj/KEY)"

🔓
Session unlock
Enter fullscreen mode Exit fullscreen mode

One Touch ID, then batch operations flow without interruption.

📥
.env import
Enter fullscreen mode Exit fullscreen mode

noxkey import org/proj .env — migrate in one step.

👀
Peek
Enter fullscreen mode Exit fullscreen mode

noxkey peek org/proj/KEY — first 8 characters for verification, without exposing the full value.

📁
Org/project hierarchy
Enter fullscreen mode Exit fullscreen mode

Secrets are namespaced, searchable, and never duplicated across projects.

🖥
Menu bar UI
Enter fullscreen mode Exit fullscreen mode

Browse, add, edit, and organize secrets without touching the terminal.

AI agent security 

🤖
Automatic agent detection
Enter fullscreen mode Exit fullscreen mode

Process-tree walking identifies Claude, Cursor, Codex, Windsurf, Copilot, and others.

🔐
Encrypted handoff
Enter fullscreen mode Exit fullscreen mode

Agents get secrets in their process environment, never in conversation context.

🛑
Command blocking
Enter fullscreen mode Exit fullscreen mode

--raw, --copy, load, export, bundle, env are all blocked for agent callers.

🔍
DLP scanning
Enter fullscreen mode Exit fullscreen mode

Catches leaked values in agent output before they persist.

What NoxKey does not do

Deliberate scope
NoxKey is for individual developers on macOS who need to keep API keys and tokens out of .env files and AI agent contexts. It is not a team vault, not cross-platform, not a password manager, and has no cloud sync.

Not a team tool. NoxKey is for individual developers. No shared vault, no role-based access, no audit log. For team secret management, look at Doppler or HashiCorp Vault.

Not cross-platform. macOS only. The security model depends on the macOS Keychain, Touch ID, and the Secure Enclave. These do not exist on Linux or Windows. The concepts are portable — this implementation is not.

Not a password manager. NoxKey manages developer credentials — API keys, tokens, database URLs, webhook secrets. It does not autofill browser forms or sync across devices. Use 1Password or Bitwarden for that.

No cloud sync. Your secrets exist on one machine. If your laptop dies, you re-import. This is a feature — no server to breach, no sync protocol to exploit, no third party with your data. Backups are your responsibility.

Why we built a dotenv alternative for macOS

We were using .env files like everyone else. We had a .gitignore entry. We thought we were fine.

Then AI coding assistants became part of the daily workflow. Every project file became fair game for an agent to read, reference, and include in responses. The .env file went from "slightly risky convenience" to "active liability." The dotenv pattern was designed in 2012, before AI agents existed. It assumes the only thing reading your project files is your code.

We looked at existing options. 1Password CLI is solid but requires a subscription and has no agent detection. HashiCorp Vault targets infrastructure teams, not solo developers. Doppler is cloud-hosted. None of them distinguish between a human caller and an AI agent.

The macOS Keychain was sitting right there. Encrypted. Biometric. Local. Already on every Mac. All it needed was a developer-friendly interface and awareness of AI agents.

Get started 

brew install no-box-dev/noxkey/noxkey
Enter fullscreen mode Exit fullscreen mode

Free. No account. No cloud. Your Keychain and your fingerprint.

Key Takeaway
NoxKey stores your secrets in the macOS Keychain with Touch ID protection and zero cloud connections. When an AI agent requests a secret, process-tree detection delivers the value through an encrypted handoff — the secret reaches the agent's shell environment without appearing in its conversation context. Install with brew install no-box-dev/noxkey/noxkey and your .env files become obsolete.

Read more: how we migrated 47 .env files, how Touch ID protects your API keys, or six ways AI agents leak secrets.

noxkey.ai

Frequently asked questions

*What is NoxKey?*
NoxKey is a free, open-source macOS menu bar app that stores developer secrets (API keys, tokens, passwords) in the macOS Keychain with Touch ID. It replaces .env files with hardware-encrypted storage and adds AI agent detection with encrypted handoff.

*How does NoxKey detect AI agents?*
NoxKey walks the macOS process tree when a secret is requested. If it detects an AI agent (Claude Code, Cursor, Copilot) in the calling chain, it switches to encrypted handoff — the secret reaches the agent's shell environment through a self-deleting encrypted script, never entering the conversation context.

*Is NoxKey free?*
Yes. NoxKey is MIT-licensed, open source, and completely free. No account, no subscription, no cloud. Install with brew install no-box-dev/noxkey/noxkey.

*How do I migrate from .env files?*
One command: noxkey import myorg .env. This imports all key-value pairs into the macOS Keychain. Then delete the .env file. Access secrets with eval "$(noxkey get myorg/KEY)".

*Does NoxKey send data to the cloud?*
No. NoxKey makes zero outbound network connections. All secrets are stored locally in the macOS Keychain, which uses Apple's Secure Enclave for hardware encryption. This is verifiable via macOS network monitoring.

*What's the difference between NoxKey and 1Password CLI?*
NoxKey is local-only (no cloud, no account), free, and includes AI agent detection with encrypted handoff. 1Password CLI requires a cloud subscription and has no AI-specific security features. Full comparison.

NoxKey is free and open source. brew install no-box-dev/noxkey/noxkey — GitHub | Website

Top comments (0)