authy

Encrypted secrets for AI agents. Single binary, no server, no accounts.

30-Second Start

npm install -g authy-cli

authy init --generate-keyfile ~/.authy/keys/master.key
authy store api-key                          # type value, Ctrl+D
authy run --scope "*" -- ./my-script.sh      # script sees $API_KEY in its env

That's it. Secret is encrypted in the vault, injected into the subprocess, never in your shell history or .env files.

Config File Placeholders

# Template with placeholders (safe to commit)
echo 'host: <authy:db-host>\nport: <authy:db-port>' > config.yaml.tpl

# Resolve to real values at deploy time
authy resolve config.yaml.tpl --scope deploy --output config.yaml

authy run covers env vars. authy resolve covers config files.

MCP Server

Run Authy as an MCP (Model Context Protocol) server for AI agent platforms like Claude Desktop, Cursor, and Windsurf:

authy serve --mcp

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "authy": {
      "command": "authy",
      "args": ["serve", "--mcp"],
      "env": { "AUTHY_PASSPHRASE": "your-passphrase" }
    }
  }
}

Exposes 5 tools over stdio JSON-RPC 2.0: get_secret, list_secrets, store_secret, remove_secret, test_policy.

Library API

Use Authy as a Rust crate for programmatic vault access:

use authy::api::AuthyClient;

let client = AuthyClient::with_passphrase("my-vault-passphrase")?;
client.init_vault()?;
client.store("api-key", "sk-secret-value", false)?;
let value = client.get("api-key")?; // Some("sk-secret-value")

# Add to your project (library only, no CLI deps)
cargo add authy --no-default-features

Auth from environment variables:

// Reads AUTHY_KEYFILE or AUTHY_PASSPHRASE
let client = AuthyClient::from_env()?;

Language SDKs

Thin CLI wrappers for Python, TypeScript, and Go. Zero native deps — each SDK shells out to the authy binary with --json mode.

Python

pip install authy-secrets

from authy_secrets import Authy

client = Authy()
value = client.get("db-url")
client.store("api-key", "sk-secret-value")
names = client.list()

TypeScript

npm install authy-secrets

import { Authy } from "authy-secrets";

const client = new Authy();
const value = await client.get("db-url");
await client.store("api-key", "sk-secret-value");
const names = await client.list();

Go

go get github.com/eric8810/authy-go

client, _ := authy.New()
value, _ := client.Get(ctx, "db-url")
client.Store(ctx, "api-key", "sk-secret-value")
names, _ := client.List(ctx)

All three SDKs support passphrase, keyfile, and token auth via constructor options or environment variables.

Install

# npm (recommended)
npm install -g authy-cli

# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/eric8810/authy/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/eric8810/authy/main/install.ps1 | iex

# From source
cargo build --release

How It Works

You store secrets    →  authy vault (encrypted)
Agent runs command   →  authy run injects secrets as env vars into subprocess
Subprocess finishes  →  env vars gone, nothing on disk

Secrets never appear in shell history, .env files, process arguments, or LLM context.

Give Agents Scoped Access

# Create a policy — agent only sees db-* secrets
authy policy create backend --allow "db-*" --run-only

# Create a time-limited token
authy session create --scope backend --ttl 1h --run-only
# → authy_v1.dGhpcyBpcyBhIDMyIGJ5dGUgcmFuZG9t...

# Agent uses the token — can only inject, never read values
export AUTHY_TOKEN="authy_v1...."
export AUTHY_KEYFILE=~/.authy/keys/master.key
authy run --scope backend --uppercase --replace-dash '_' -- node server.js

--run-only means the agent can inject secrets into subprocesses and resolve config templates, but can never read values directly. authy get, authy env, authy export all return an error.

Project Config

Drop .authy.toml in your project root. No more --scope flags:

[authy]
scope = "my-project"
keyfile = "~/.authy/keys/master.key"
uppercase = true
replace_dash = "_"

authy run -- ./deploy.sh          # scope inferred from .authy.toml
eval "$(authy hook bash)"         # auto-activate on cd (like direnv)

Migrate Your Secrets

# From .env files
authy import .env                                         # imports all keys
authy import .env --dry-run                               # preview first

# From 1Password
authy import --from 1password --vault Engineering

# From pass (password-store)
authy import --from pass

# From Mozilla SOPS
authy import --from sops secrets.enc.yaml

# From HashiCorp Vault
authy import --from vault --path secret/myapp

Admin TUI

authy admin — manage secrets, policies, sessions, and audit logs interactively. Secrets entered through the TUI never touch shell history.

authy admin --keyfile ~/.authy/keys/master.key

Agent Skills

Works with Claude Code, Cursor, OpenClaw, and 38+ AI coding agents:

npx skills add eric8810/authy

The skill teaches agents to use authy run (inject secrets), authy resolve (config templates), and authy list (discover names). Agents never learn commands that expose values.

Security

• age encryption (X25519) — vault encrypted at rest
• HMAC-SHA256 session tokens — short-lived, read-only, constant-time validation
• Glob-based policies — deny overrides allow, default deny
• HMAC-chained audit log — tamper detection on every entry
• Zeroize on drop — all secret-holding memory wiped when freed
• Run-only mode — agents can inject but never read

All Commands

Basics
  authy init                        Initialize a new vault
  authy store <name>                Store a secret (reads from stdin)
  authy get <name>                  Retrieve a secret value
  authy list                        List secret names
  authy remove <name>              Remove a secret
  authy rotate <name>              Rotate a secret value

Policies
  authy policy create <name>       Create an access policy
  authy policy show <name>         Show policy details
  authy policy update <name>       Modify a policy
  authy policy list                List all policies
  authy policy remove <name>       Remove a policy
  authy policy test --scope <s> <name>  Test access

Sessions
  authy session create             Create a scoped session token
  authy session list               List active sessions
  authy session revoke <id>        Revoke a session
  authy session revoke-all         Revoke all sessions

Agent Commands
  authy run [--scope <s>] -- <cmd> Run a command with injected secrets
  authy resolve <file>             Resolve <authy:key> placeholders in files
  authy env [--scope <s>]          Output secrets as env vars
  authy import <file>              Import from .env file
  authy import --from <source>     Import from 1password, pass, sops, vault
  authy export --format <fmt>      Export as .env or JSON

Vault Management
  authy rekey                      Re-encrypt vault with new credentials

Project
  authy project-info               Show .authy.toml config
  authy alias [scope] [tools...]   Generate shell aliases
  authy hook <shell>               Shell hook for auto-activation

Audit
  authy audit show                 Show audit log
  authy audit verify               Verify log integrity
  authy audit export               Export log as JSON

Server
  authy serve --mcp                Start MCP server (stdio JSON-RPC)

Admin
  authy admin                      Launch admin TUI
  authy config show                Show configuration

All read commands support --json. --scope is optional when .authy.toml is present.

Docs

• docs/GUIDE.md — full command reference, auth modes, config, exit codes
• ARCHITECTURE.md — system design
• SECURITY.md — threat model
• CHANGELOG.md — version history

License

MIT