First run

Install and start

Install fd0 on each machine that should hold secrets. The hosted service at fd0.sh is the default backend; self-hosted clients use the same binaries with a different [sync].server.

There are two ways in, and they are not exclusive. Take fd0 Desktop if you want the app — the installer can hand it the fd0 and fd0-agent commands too. Take the CLI alone on servers and machines where a window would never open.

$ curl -fsSL https://fd0.sh/install | sh

The installer asks whether to install Desktop or the CLI. For a CLI install, it also asks whether to include YubiKey support. Run the same command again to update: your current product and flavor are selected by default, and nothing changes until you confirm.

Install fd0 Desktop

Download fd0 Desktop →

Signed DMGs for macOS and AppImage, DEB, and RPM builds for Linux, on x64 and arm64. Downloading the DMG or AppImage directly installs the app and its bundled agent; it does not claim the fd0 command. Use the script below when it should.

$ curl -fsSL https://fd0.sh/install | sh -s -- --desktop

This installs one versioned bundle containing fd0 Desktop, the CLI, and the agent. The fd0 and fd0-agent commands point into that bundle, so an app update updates all three together. Desktop manages passwords, general secrets, SSH hosts and keys, kubeconfigs, and Talos contexts through the same local agent.

The desktop installer verifies SHA-256 for every install and always authenticates the release manifest. If Cosign is missing it downloads a pinned Cosign 3.0.6 binary and checks its hard-coded hash first, so you do not install release tooling by hand. On macOS it also verifies the app signature and the Gatekeeper assessment before replacing anything.

$ curl -fsSL https://fd0.sh/install-desktop | sh -s -- --system
$ curl -fsSL https://fd0.sh/install-desktop | sh -s -- --version=desktop-v1.2.3
$ curl -fsSL https://fd0.sh/install-desktop | sh -s -- --uninstall

--system installs for every user — /Applications on macOS, /usr/local/bin on Linux — instead of the per-user default. --version=desktop-vX.Y.Z pins a release, and going backwards also needs --allow-downgrade. --uninstall removes the app and its managed command wrappers and restores any standalone fd0 commands it displaced. It does not remove ~/.fd0 or your vault data. Add -y to skip the confirmation prompt.

Install the CLI

$ brew install cosign   # macOS or Linuxbrew
$ cosign version

The CLI-only installer requires Cosign to authenticate release manifests. Install it first.

$ curl -fsSL https://fd0.sh/install | sh -s -- --flavor=standard
$ fd0 version
fd0 <version> standard

The installer picks Linux or macOS, amd64 or arm64, verifies SHA-256, authenticates the manifest against the exact fd0 release workflow and tag with Cosign, and writes fd0 plus fd0-agent to ~/.local/bin. It doubles as the upgrade path: it detects an existing install, prints current → new, and asks before touching anything.

--system installs into /usr/local/bin and --prefix=DIR installs anywhere else. --version=vX.Y.Z pins a release (with --allow-downgrade to move backwards), --flavor=auto|standard|yubikey chooses the build, --yubikey is the shortcut for the PIV one, and -y skips prompts and keeps the non-interactive default on the CLI unless a product or flavor is selected explicitly. FD0_VERSION and FD0_FLAVOR provide the same version and flavor choices from the environment.

Install the YubiKey flavor

$ curl -fsSL https://fd0.sh/install | sh -s -- --yubikey
$ fd0 version
fd0 <version> yubikey

The YubiKey flavor includes PIV support in both fd0 and fd0-agent. Use it on machines that should enroll or unlock with a YubiKey.

Update the client

$ fd0 update --check
$ fd0 update
$ fd0 update --flavor=yubikey

fd0 update updates fd0 and fd0-agent from the latest client release. It verifies the archive checksum and requires Cosign authentication. It keeps the installed flavor by default: standard stays standard, yubikey stays yubikey. Use --flavor only to switch deliberately. If the agent is running, restart it after the update with fd0 agent restart.

Automatic update resolution never downgrades. Installing an explicitly selected older release requires --allow-downgrade in addition to the version.

In a Desktop-managed installation, plain fd0 update opens Desktop under Support and starts the app updater. Desktop-specific version, flavor, prefix, and downgrade flags are rejected because the app, CLI, and agent update as one signed bundle.

Windows is not supported yet. The binaries cross-compile, but the agent socket path has not been validated on Windows.

Teach your coding agent about fd0

fd0 ships an agent skill in the same repository. Installing it lets Claude Code and other skill-aware runtimes recognise "save this deploy key" or "share the prod password with bob" as fd0 work, and reach for the right command instead of guessing at one.

$ bunx skills add k2b-dev/fd0.sh

The installer copies skills/fd0/ into your agent's skill directory — usually ~/.claude/skills/fd0/. The skill loads on the next session. If your runtime uses npm rather than Bun, npx skills add k2b-dev/fd0.sh does the same thing, and copying the directory by hand works just as well.

The skill covers the whole surface — vaults and scopes, the password manager, SSH, Kubernetes and Talos, sharing, recovery and the failure modes worth knowing. It carries no secrets and needs no access to your vault; it only teaches the agent which command to run.

Create a vault

$ fd0 init
$ fd0 unlock
$ fd0 scope create --label work
$ fd0 secret set API_TOKEN "secret-value" --scope work
$ fd0 sync

fd0 init creates your identity and seals the vault under a passphrase. fd0 unlock starts the agent. fd0 sync publishes encrypted events to the configured primary and pulls changes from other devices.

Configure another backend

$ mkdir -p ~/.fd0
$ cat >~/.fd0/config.toml <<'EOF'
[sync]
server = "https://fd0.example.com"
interval = "1h"
on_unlock = true
EOF

← Previous

Concepts

Desktop app