Safe8bit Manual

Everything the app and the safe8bit command do, with examples. Sections marked Pro need the license; the rest is free in Lite.

Install

Safe8bit needs macOS 15 or later. The app is signed and notarized by Apple, and the download is the same for Lite and Pro.

$ brew trust safe8bit-app/tap
$ brew install --cask safe8bit-app/tap/safe8bit

Homebrew installs the app in /Applications and the safe8bit command in the terminal. You can also use the Download button and drag the app to Applications. In that case, the command to put safe8bit in the terminal is in Settings › Terminal (CLI).

To update: brew upgrade --cask safe8bit. The vault is not touched.

Create the vault

1. Open Safe8bit. On the Create your vault screen, choose a master password with at least 12 characters and confirm it.
2. Leave Unlock with Touch ID (Secure Enclave) on so you can open the vault with your fingerprint.
3. Click Create vault.
4. Right after, create the Emergency Kit.

If you already use Safe8bit on another Mac with iCloud on, the screen shows There's a Safe8bit vault in your iCloud. Click Use the iCloud vault and open it with the same master password.

Touch ID is tied to the fingerprints enrolled on the Mac. If you add or remove one, you need the master password again once.

Activate Pro

1. Buy Pro at safe8bit.com/en/buy. The key arrives by email, from licencas@safe8bit.com; if it doesn't show up, check your trash or spam.
2. In the app, go to Settings › License.
3. Paste the key (it starts with SBL1.) and click Turn on.

The key is verified on the Mac, without internet. It is valid until the end of the paid period plus 7 days, and with each renewal you get a new key to paste in the same place (Update). The same key works on all your Macs.

The window

The sidebar has these sections:

At the bottom are Settings (⌘,) and the Lock the vault padlock (⌘L). The vault also locks on its own after the time you choose, when the Mac sleeps, when the screen locks and when you switch users. Safe8bit windows don't appear in screenshots or screen sharing.

Projects

Every secret belongs to a project. Create one in Projects › New project and choose a name, color and icon.

At the top of a project you have Edit, Use in code and Add. Right-click a project for Edit… or Delete…. Deleting a project erases all its secrets, and that can't be undone.

Use in code shows how to read the variables in Node, Python, Ruby, Deno and Swift, a ready-made safe8bit run command, a text to give to an AI agent, and buttons to copy the production .env or mount the .env without touching the disk.

Secrets and fields

When you create a secret you choose its type, and it comes with the right fields:

• + Field adds fields of type Text, Secret, Multiline or URL. If a visible field looks like a key, the app suggests Make secret.
• Attachment: drag in a file up to 4 MB. In the secret you can copy its contents or Save as….
• Validity: Never, 90 days, 6 months, 1 year or a date. The Radar warns you 14 days before.
• Tags (comma-separated) and Notes.
• History: keeps the last 10 versions, every time a sensitive value changes. Restore… goes back to one of them.
• A .env also has Copy as .env, Export .env… and Split variables.

When you copy a value, it is cleared from the clipboard after 30 seconds (you can change this in Settings), unless you have copied something else in the meantime. Clipboard managers are told not to save it.

Environments and variables

Each secret can have an environment: None, Dev, Staging or Prod. Secrets without an environment are the base: they go into every environment, and the ones from the chosen environment override them.

For a field to reach the terminal, give it a variable name. In the secret editor, each field has a $ pill to the right of its name: type STRIPE_SECRET_KEY there, for example. Only uppercase letters, digits and _ are accepted. Leave it empty if the field shouldn't be exported. In the secret, the name shows as $STRIPE_SECRET_KEY.

To name many fields at once, open Use in code › Fields without a variable and click Apply names.

Then, in the terminal: safe8bit run -e prod -- npm start. See Terminal.

2FA codes

In the secret editor, click 2FA code and choose one of these options:

• paste the otpauth://… link or the setup key the website gives you;
• Paste QR: take a screenshot of the QR to the clipboard with ⌃⇧⌘4 and paste it;
• Image with QR…: choose an image containing the QR.

The current code appears right away. The codes also show up in the 2FA codes section: click one to copy it. Copying a 2FA field always copies the code, never the seed. Codes of 6 to 8 digits are accepted, with SHA1, SHA256 or SHA512.

When you copy the password of a Credential that has 2FA, you get a notification with Copy code. For 2 minutes, ⌃⇧Space opens straight on that code. The clipboard is never replaced unless you ask. Turn this off in Settings › Quick Access.

AutoFill and passkeys

For Safe8bit to fill in logins in Safari and in apps:

1. Go to Settings › AutoFill and click Open System Settings.
2. In General › AutoFill & Passwords, turn on Safe8bit.

AutoFill fills in Credentials (the URL field decides which website they appear on), the 2FA codes of any secret, and passkeys. It always asks for Touch ID or the master password; it never fills in silently.

Suggest logins automatically in Safari is off by default. If you turn it on, usernames and domains (never passwords) are kept in a system index, outside the vault, so Safari can suggest them.

Passkeys

When a website (GitHub, for example) offers to create a passkey, choose Safe8bit. It goes into the Passkeys project. To sign in, the website asks for the passkey and you confirm with Touch ID. Passkeys can't be shared.

Quick Access

⌃⇧Space opens a search on top of any app. It searches titles, projects and tags.

• ↩ copies the main value and goes back to the app you were in;
• ↑ ↓ pick a result;
• the buttons on each row copy another field: password, 2FA code, username, public key or .env;
• esc closes it.

If the vault is locked, it asks you to unlock it first. The shortcut can't be changed, but you can turn it off in Settings › Quick Access.

Generator

It shows the bits of entropy of what it generated. In a secret's editor, the Generate button opens the generator and Use puts the value in the field.

Rotation Radar

Shows each secret by age (rings at 30 days, 90 days and 1 year) and flags the ones that need attention:

Filter by all, prod only or with alerts. Open takes you to the secret. For a value reused on purpose, It's OK stops the warning. To rotate a rejected key: generate a new one in the service, paste it into the secret and confirm with safe8bit test. The analysis is all done on the Mac.

Detector and Import

Detector

In the Detector section, choose a folder (for example ~/Development) and click Search. It finds forgotten plaintext secrets:

• .env and variants (templates like .env.example are left out);
• .p8, .p12, .pfx, .pem, .key, .jks and .keystore keys;
• SSH keys (id_rsa, id_ed25519, …) and service account JSON;
• signing and secrets *.properties, .sentryclirc, *secret*.xcconfig and .txt notes that look like secrets.

It skips node_modules, .git, Pods, build and the like. In the review you choose what to save and in which project, and you see what is already in the vault. If you want, the originals go to the Trash after they are imported.

Import from another manager

In Add › Import from another manager, choose the exported file: CSV from Apple Passwords, Chrome, Firefox, 1Password or Bitwarden, or JSON from Bitwarden (unencrypted). Logins become Credentials (with 2FA, if any), notes become Secure Notes and folders become projects. Duplicates are skipped. Cards and identities are not imported.

Shares Pro to createLite to open

To give someone a secret without pasting it into a chat:

1. In the secret, click the share icon (Share in an encrypted file).
2. Choose how long it stays valid: 1 hour, 1 day or 7 days.
3. Create file… creates a .safe8bit file and shows the passphrase (SBSH-…). Send the file by AirDrop, Slack or email, and the passphrase through a different channel.

The fields, the attachment and the notes are included. The history, the project and the tags are left out. Passkeys and SSH keys can't be shared. The passphrase is not stored anywhere.

The recipient opens the file with a double-click, or in Add › Open share, pastes the passphrase and clicks Save to vault. By default, it goes into the Shared project and the file goes to the Trash. Opening works in Lite. After it expires, the file is rejected.

iCloud

In Settings › iCloud, turn on Sync the vault with iCloud. The vault goes to your iCloud already encrypted: Apple only sees encrypted data. On your other Macs, open Safe8bit and choose Use the iCloud vault.

• The master password and the Emergency Kit work on every Mac. Touch ID is set up on each one.
• If two Macs change the vault at the same time, the changes are merged secret by secret. The most recent edit wins, and the other one stays in the history.
• If iCloud already has a different vault, you choose between Use the iCloud one on this Mac (the local one is kept as a backup) and Replace the iCloud one with this one.

Emergency Kit

It is the only way to recover the vault if you forget the master password. Create it in Settings › Emergency Kit › Create Emergency Kit….

1. The app generates a recovery key (SBRK-…) and shows it only once.
2. Print it or save the PDF, and put it somewhere safe, away from the Mac.
3. Check I’ve kept the key somewhere safe and click Done.

To recover: on the lock screen, click Forgot your password? Use the Emergency Kit, type the key (uppercase, spaces and hyphens don't matter) and choose a new master password.

Creating a new kit invalidates the previous one. The kit protects you against forgetting the password, not against losing the Mac: for that, use Time Machine or iCloud.

Settings

Terminal: how it works Pro

Homebrew installs the safe8bit command along with the app. Each command opens the vault just for that request and asks for Touch ID (or the master password, if there's no Touch ID). Values never appear on screen, unless you ask for them with read, otp or env.

Where the variables come from

A project gives variables to the terminal in two ways:

• Secrets of type .env: the whole contents go in as they are.
• Fields with a variable name: in the app, you give a field a name like STRIPE_SECRET_KEY and that field becomes the STRIPE_SECRET_KEY variable.

First come the secrets without an environment (the base), then the ones from the environment you chose with -e. If the same variable appears in both, the environment's one wins.

Which project is used

Without -p, safe8bit looks for a project with the name of the current folder, or of a folder above it. In ~/Development/Shop/apps/web, it finds the Shop project and picks the .env for apps/web, if there is one. With -p Shop you choose the project by hand.

Common options

safe8bit run

Runs a command with the project's variables in its environment. No .env is left on disk, and safe8bit hands over to your command, so no copy of the vault stays in memory.

$ safe8bit run -e prod -- npm start
safe8bit: 6 variables from Shop · Prod (Stripe + Supabase + .env)
$ safe8bit run -p Shop -e dev -- python manage.py runserver

Everything after -- is your command, just as you would type it.

safe8bit env

Writes the project's .env to the screen or to a file, for tools that can only read a file.

$ safe8bit env -e prod -o .env.production
# export to the current shell
$ eval "$(safe8bit env -e dev --export)"

safe8bit mount

Creates the .env as a pipe: whatever opens it gets the project's variables, but nothing is written to disk. It asks for Touch ID once.

# mount ./.env until Ctrl-C
$ safe8bit mount -e dev
# unmount automatically in 8 hours
$ safe8bit mount config/.env --for 8h
# list what is mounted
$ safe8bit mounts
# unmount the ones in the current folder
$ safe8bit unmount

It works with tools that open and read the file: python-dotenv 1.1 or later, dotenv (Node) and docker compose. Next.js and Vite refuse pipes; there, use safe8bit run -- npm run dev.

unmount and mounts work without a license, so you can always undo a mount.

safe8bit read and safe8bit otp

They print a value or the current 2FA code. The reference is safe8bit://Project/Secret/Field.

$ safe8bit read "safe8bit://Shop/Supabase/API Key"
$ safe8bit read "safe8bit://Shop/App Store Connect/attachment" -o AuthKey.p8
$ safe8bit otp safe8bit://Shop/GitHub

The attachment field (or anexo) returns the file attached to the secret, such as a .p8 key. With -o, the file gets 600 permissions.

safe8bit list

Shows projects, secrets and variable names, never the values. It is safe to run in front of other people or an AI agent.

$ safe8bit list -p Shop
Stripe  [API Key] prod
    API Key → $STRIPE_SECRET_KEY, Webhook → $STRIPE_WEBHOOK_SECRET
apps/web/.env  [.env file] dev
    DATABASE_URL, NEXT_PUBLIC_SUPABASE_URL

safe8bit test

Asks each service whether the project's keys still work, with a read-only request that costs nothing. It knows OpenAI, Anthropic, Stripe, GitHub, Vercel and Supabase.

$ safe8bit test
  ✓ Stripe › API Key
  ~ OpenAI › API Key: out of quota
  ✗ GitHub › Token: denied (401)

After rotating a key in the app, confirm the new one with safe8bit test -p PROJECT -s SECRET.

safe8bit push

Sends the project's variables (the same ones as run) to Vercel's Environment Variables: prod goes to Production, staging to Preview and dev to Development.

# show what would change
$ safe8bit push --to vercel -e prod --dry-run
$ safe8bit push --to vercel -e prod

• It creates the variables that are missing and updates the ones that already exist. It never deletes variables on Vercel.
• A variable that is shared by several environments on Vercel gets split: the other environments keep the value they had.
• Before sending, it tests the keys like safe8bit test. If any service rejects a key, it sends nothing.
• The Vercel project and team come from .vercel/project.json (the one vercel link creates). The token comes from the project's Vercel secret or, if there isn't one, from another project.

safe8bit license

Tells you whether Pro is active, who the license belongs to and until when it is valid. It always works, with or without a license.

$ safe8bit license
Version: Pro, licensed to ana@example.com, valid until Nov 13, 2027.

Without a license, or with an expired one, the Pro commands stop and tell you where to activate or renew.

Git Guard Pro blocksLite logs

A pre-commit hook compares the new lines in each commit against the values in the vault. If it finds one, Pro blocks the commit before the key reaches GitHub. In Lite, it warns you and lets it through.

# in the current repository
$ safe8bit guard install
# in every repository in that folder
$ safe8bit guard install ~/Development
$ git commit -m "config"
1 value from the vault in this commit. Commit blocked.

Git Guard doesn't open the vault on every commit, so it doesn't ask for Touch ID. It uses an index of fingerprints (HMAC-SHA256) of the values, with a key that only this Mac's Secure Enclave can derive. The values are not in the index, and values shorter than 8 characters are left out.

Shield for AI agents Pro blocksLite logs

It hooks into Claude Code and Cursor and sees each request from the agent before the agent carries it out:

• blocks reading .env files, keys and credential files;
• blocks reading files that contain vault values and writing those values into code;
• asks you before commands that reveal secrets, such as printenv or safe8bit read.

In Lite, the Shield logs what it would have blocked and lets the agent carry on.

# in the agents it finds (~/.claude, ~/.cursor)
$ safe8bit shield install
# only in Claude Code
$ safe8bit shield install --claude
# protected agents and latest blocks
$ safe8bit shield status
$ safe8bit shield uninstall

safe8bit shield scan

Looks for forgotten keys in the agents' instructions and configuration: CLAUDE.md, AGENTS.md, .mcp.json and the configuration files of Claude, Cursor, Codex and Gemini.

$ safe8bit shield scan ~/Development

SSH Agent Pro

SSH keys stay in the vault and never leave it. Every ssh or git push asks for your Touch ID, even with the app closed.

1. In SSH Agent (or Settings › SSH Agent), turn on Use Safe8bit keys (ssh, git). If macOS asks, allow Safe8bit in Login Items.
2. Click New key and choose Generate Ed25519 key or Import file…. Ed25519, ECDSA P-256 and RSA are accepted; keys with a passphrase are not.
3. Copy the configuration the app shows into ~/.ssh/config. It looks like this:

Host *
  IdentityAgent "~/Library/Group Containers/8H697DPSV4.com.erik.safebit/agent.sock"

4. Put the public key on GitHub (or the server) and test it: ssh -T git@github.com.

In Ask for Touch ID you choose how often: Always (the default), once every 15 minutes, 1, 4 or 8 hours, or until the screen locks. By default, approvals are forgotten when the screen locks or the Mac sleeps. The prompt tells you which app wants to use which key.

Without a Pro license, the agent keeps running but doesn't offer any keys.

Lite and Pro

Without a license, or with an expired one, the vault and all the secrets are still there. safe8bit license, unmount and mounts always work. See pricing.

Security

• Encryption: the vault is a single file encrypted with AES-256-GCM. The key is derived from the master password with Argon2id (256 MiB of memory, 4 passes). There is no plaintext metadata: without the password, not even the project names can be read.
• Touch ID: the vault key is protected by the Mac's Secure Enclave and only comes out with your fingerprint.
• Almost no network: the app has no telemetry. Once a day it reads safe8bit.com/appcast.xml to check for a new version (turn this off in Settings › Lock › Updates); the update is only installed when you click Install, and it must be signed by Safe8bit. Other than that, only safe8bit test and safe8bit push contact the services you choose.
• Where it is: ~/Library/Group Containers/8H697DPSV4.com.erik.safebit/Library/Application Support/SafeBit/vault.sbv, with 600 permissions. Time Machine backs it up, already encrypted.
• On screen: the windows don't appear in screenshots or screen sharing. The terminal never shows values, except the ones you ask for with read, otp or env.

Questions

How do I move the vault to a new Mac?

Turn on iCloud on both Macs (Settings › iCloud) and, on the new Mac, choose Use the iCloud vault. Without iCloud, copy vault.sbv to the same place on the new Mac (or restore it from Time Machine) and open it with the master password.

safe8bit run says it can't find the project.

The folder name doesn't match the name of any project. Use -p NAME, or rename the project to match the folder. safe8bit list shows the project names.

The project has no variables.

The terminal only sees secrets of type .env and fields with a variable name. See Environments and variables.

Next.js or Vite ignore the mounted .env.

They refuse pipes. Use safe8bit run -- npm run dev.

Can I use safe8bit in a script or in CI?

On your Mac, yes: when Touch ID isn't available, use --password-stdin. On CI servers, no, because the vault lives on the Mac. For Vercel, use safe8bit push.

What happens when Pro expires?

The app goes back to Lite. All the secrets stay, the Pro commands stop, and Git Guard and the Shield keep running, but only log.

Still have questions?

Write to suporte@safe8bit.com.