Your First Garden

With the binaries installed, softfig onboard turns an empty machine into a working garden: it sets your passphrase, shows a recovery phrase once, and writes an encrypted genesis commit.

Have something to write on

softfig onboard prints a 12-word recovery phrase exactly once. Record it offline before you continue.

1. Run the wizard

softfig onboard prompts for a passphrase, so it needs a terminal.

softfig onboard

Flag	Default	Meaning
--garden-root PATH	~/soft-fig_garden	where the plaintext view mounts
--state-root PATH	~/.local/share/softfig/<garden-dir-name>/ (honors $XDG_DATA_HOME)	where the encrypted .softfig/ store lives
--machine NAME	system hostname	machine identity stamped into the skeleton
--customize	off	interactively pick which concept dirs to include
--yes	off	accept defaults and skip the concept-dir prompts (the passphrase still needs a terminal)

Onboarding refuses to run if a garden already exists at the state root.

2. Passphrase and recovery phrase

The wizard asks for a master passphrase twice, then prints the recovery phrase.

• The passphrase unlocks the garden day to day.
• The recovery phrase is a second door in, used with softfig vault recover if you forget the passphrase. It is never stored in plaintext.

Lose every way in and the garden is gone

Without the passphrase or the recovery phrase, the contents are unrecoverable. Once the garden is up, read Recovery & escrow: you can choose a different recovery shape, and a small escrow file is worth copying everywhere.

3. What onboard did

The scaffold is born in FUSE: the embedded skeleton is encrypted straight into the state root as the genesis init commit, and no plaintext ever lands on disk. It also writes a small keeper.toml pointer (under .softfig/ at the garden root and beside the state) telling the daemon where the state lives. Until the daemon mounts the garden, the garden root holds only that pointer.

4. Start the daemon and unlock

If onboard-device.sh enabled the systemd unit, the daemon is already running, locked. Otherwise start it yourself. Unlocking mounts the garden.

# if the unit is enabled:
systemctl --user status softfig-keeperd    # running, locked

# ...or run it in the foreground (use a second terminal for the next command):
softfig daemon start --garden ~/soft-fig_garden

# then, once per boot:
softfig daemon unlock                        # prompts for your passphrase

The garden stays mounted until the daemon stops or locks. Check it any time with softfig daemon status.

5. Look around

ls ~/soft-fig_garden
# CLAUDE.md  config/  inbox/  journal/  meta/  packages/  services/  ...
cat ~/soft-fig_garden/CLAUDE.md    # the root map that routes any question

Before unlock that ls shows no garden files; stop the daemon and they vanish again, because plaintext exists only through the mount.

FUSE needs a real machine

The mount can’t come up inside a sandboxed or container build. Run this check on the actual device.

Most concept directories are deliberately thin stubs. Growing them is the practice; see Make It Your Own.

6. Your first Claude session

Open Claude Code from the garden root, so its always-loaded CLAUDE.md gives the session the map:

cd ~/soft-fig_garden && claude

Make it a habit with an alias:

alias garden='cd ~/soft-fig_garden && claude'

Claude can read the garden as soon as it is unlocked. To let it write through soft-fig’s verbs, do the one-time softfig-mcp registration.

Next

• Working with Claude and the Starter Prompts
• Seal & Reveal for secrets
• Recovery & escrow so you can always get back in
• Deploy Dotfiles