Hush

A personal secret vault for coding agents. Deploy it to your Cloudflare account, manage secrets in your browser, and give commands the credentials they need:

hush exec github -- gh api user
hush exec cloudflare -- cf deploy --mode production

Secret values are encrypted before they reach the server. A Profile maps selected secrets to environment variables; hush exec decrypts those values locally and passes them to the command. The CLI supports Linux x86_64, Linux ARM64, and Apple Silicon macOS.

Getting started: Deploy → Create a vault → Install the CLI → Connect a machine.

flowchart LR
    subgraph browser["Your browser"]
        Web["Web admin<br/>Encrypt secrets and manage profiles/devices"]
    end

    subgraph cloud["Your Cloudflare account"]
        Access["Access<br/>Authenticate requests"]
        API["Worker API"]
        DB[("D1<br/>Encrypted values and wrapped keys<br/>Readable metadata")]
        Access --> API
        API <--> DB
    end

    subgraph machine["Your agent machine"]
        Agent["Coding agent"]
        CLI["hush CLI<br/>Decrypt locally"]
        Command["Command<br/>gh, cf, ..."]
        Agent -->|"hush exec profile -- command"| CLI
        CLI -->|"Selected environment variables"| Command
    end

    Web <-->|"Owner sign-in / vault updates"| Access
    CLI <-->|"Service Token / encrypted reads"| Access

The Worker serves the Web app and stores its encrypted uploads in D1. You enroll each machine once through Web admin; agents then use the CLI without entering the master password. Decryption happens on the client, and every CLI execution needs an online service.

You need a Cloudflare account with Workers, D1, and Zero Trust Access, a domain managed by Cloudflare, and Node.js 24+ with npm 11 on the machine you deploy from. Choose an unused hostname such as hush.example.com. The Web admin and API share this hostname; no separate frontend hosting or always-on server is needed.

git clone https://github.com/txchen/hush.git
cd hush
npm ci
(cd apps/service && npx cf auth login)
(cd apps/service && npx cf d1 create --name hush)

Keep the returned database ID for step 3. The database holds encrypted secret values, wrapped keys, and metadata. See Cloudflare's D1 setup guide if your account needs additional setup.

Create a self-hosted Access application for hush.example.com, covering the entire hostname, including /api/* and the Web admin.

• Add an Allow policy restricted to your owner email. Use that same email for OWNER_EMAIL below.
• Configure a login method for that account.
• Copy the application's Application Audience (AUD) value and your Zero Trust team domain, such as your-team.cloudflareaccess.com.

Access sign-in authorizes you to use the service. Your Hush master password, created later, unlocks the encrypted vault. They are separate credentials.

The shared apps/service/cloudflare.config.ts contains no deployment identity. Copy the example into a Git-ignored local file:

cp apps/service/deployment.example.json apps/service/deployment.local.json

Fill in your account ID, D1 database ID, hostname, Access team domain, application AUD, owner email, and admin origin. ACCESS_TEAM_DOMAIN is a hostname without https://; ADMIN_ORIGIN includes https:// with no trailing slash. Never put passwords or API tokens in this file.

--mode production loads this local file; ordinary builds and tests use generic defaults. Keep workersDev and previewUrls disabled. Select your authentication profile with --profile PROFILE when using multiple accounts. Deployment IDs and email addresses belong only in the ignored file, not the shared configuration.

The route uses a Workers Custom Domain. Cloudflare provisions its DNS record and certificate; choose a hostname without an existing conflicting CNAME record.

Run from the repository root:

npm run build -w @hush/web
(cd apps/service && npx cf d1 migrations apply YOUR_DATABASE_ID --dir migrations)
(cd apps/service && npx cf deploy --mode production)

Open https://hush.example.com and sign in through Access. You should see Create your vault. If setup fails, see troubleshooting.

1. Choose a vault name and a long, unique master password. Store the password somewhere safe; Hush has no password-reset service. Trust this browser is optional and allows future unlocks using a key stored on that browser.
2. In Secrets, add a secret named GITHUB_TOKEN with your GitHub token as its value.
3. In Profiles, create a profile named github. Select that secret and map it to the environment variable GITHUB_TOKEN.

You can add more profiles, such as cloudflare with CLOUDFLARE_API_TOKEN and CLOUDFLARE_ACCOUNT_ID. Secret edits, profile changes, and device management happen in the Web admin; CLI devices have read-only service access.

curl -fsSL https://raw.githubusercontent.com/txchen/hush/master/install.sh | bash
hush version

Supports Linux x86_64, Linux ARM64, and Apple Silicon macOS. The installer downloads the latest GitHub Release, verifies SHA-256, and installs hush into ~/.local/bin. Add that directory to PATH if prompted. No Node.js or Go is required. Run the same command to upgrade; your device credentials are retained.

The CLI installation guide covers version pinning, custom install directories, and manual downloads. Linux containers need a CA certificate bundle. macOS binaries are not Developer ID signed or notarized.

The Hush skill teaches agents to select a Profile, run commands with injected credentials, and handle connection failures without exposing secret values. It includes CLI installation and device enrollment guidance.

Install the skill with the Skills CLI (requires Node.js and npm):

npx skills add txchen/hush --skill hush

Run this in the project where you want to use Hush and select your coding agent when prompted. For a global Codex installation:

npx skills add txchen/hush --skill hush --agent codex --global

This installs agent instructions and the bundled setup reference, not the Hush executable or credentials. Install the CLI separately, then connect the machine below. You can also copy the complete skills/hush/ directory, including references/, into your agent's skills directory.

Do this once on each machine that will run hush:

1. Create a Cloudflare Access Service Token for the machine. Save its Client ID and Client Secret. In your Hush Access application, add a Service Auth policy that includes this token. Keep the owner's Allow policy as well.

2. Generate the machine's device key:

   hush init --url https://hush.example.com --name agent-server --client-id YOUR_ID.access

3. In Web admin, open Devices → Register CLI device. Copy the four fields printed by hush init: name, device ID (id), public key, and Access Client ID. These fields are public enrollment information; the private key stays on the machine.

4. Run hush login and enter the Client Secret at the hidden prompt. This is the Access token secret, not your master password.

5. Check the connection and run a command:

   hush status --json
   hush profile list --json
   hush exec github -- gh api user

Once connected, agents can run hush exec without interactive login. Credentials are kept in a private local file, so access to that file grants access as the device. See CLI configuration and credential handling for custom directories and automated provisioning.

• Run a command: hush exec <profile> -- <command> [args...]. Profile variables override matching variables in the current environment. Arguments, standard streams, signals, and exit status are preserved.
• Inspect available metadata: hush secret list --json and hush profile list --json. The CLI does not offer a command to print individual secret values.
• Remove a machine: revoke it in Web admin to block future reads. hush logout only removes credentials from the local machine.
• Update or back up your vault: follow the operations guide.

Every execution needs an online service. If the service is unavailable or decryption fails, Hush does not start the command. A running command can still print or use its injected secrets; Hush does not sandbox agent code or redact command output.

Secret values and the vault encryption key are stored encrypted. Secret names, profile mappings, device information, and timestamps are visible to the service. A database copy alone does not directly reveal secret values, but it permits offline guessing of the master password, so password strength matters.

Read How Hush encryption works for the key flow and security boundaries, or the format-1 protocol for exact algorithms and wire formats.

• CLI reference
• Updates, backups, and troubleshooting
• Development and testing
• API contract