Developer quickstart

Install the Authsia app and CLI, put secrets in the vault, initialize a workspace, then run a command through Authsia so the parent shell stays clean.

Before you begin

Authsia is macOS-only for the CLI, Bridge, SSH agent, and Chrome native host. Vault data stays on your Mac through Apple security services. There is no cloud broker for secret access.

This guide is for local development. For how to choose among workspace run, guarded terminal, and exec, see Secure local development.

Step 1: Install the Authsia app

Install the released app and CLI with Homebrew, or download the Mac disk image from the website.

Open /Applications/Authsia.app once so the Bridge can register. Then check readiness:

If setup looks stale, run authsia setup --repair and open a new terminal. Full install options: Install the CLI.

Step 2: Add vault items

Create folders that match how you grant access later — for example Team/API, Production, Infra/SSH. Add API keys and other secrets there.

• Leave CLI off on items that should never leave the app UI.
• Prefer authsia:// references in env files and scripts. Secrets resolve only at approved runtime.
• Copy Path yields a shell-ready export NAME='authsia://…' line.

Details: Vault and First run.

Step 3: Initialize a workspace

From the repo root, preview then apply. Authsia stores selected secrets in the vault and writes commit-safe refs into env files. .authsia/workspace.json holds name, folder, env files, and agent rules — not plaintext secrets.

Select one named environment when the repo has more than Default:

Full workflow: Workspace CLI and Workspace Center.

Step 4: Run through Authsia

Resolve refs in a child process. The parent shell keeps references only.

For an interactive tab that shims common tools:

Agent harness launches do not inherit workspace secrets implicitly. See Guarded terminal.

Choose a first workflow