# 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](/docs/get-started/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.

```
brew install --cask james-liang-cs/authsia/authsia
```

```
brew install --cask --adopt james-liang-cs/authsia/authsia
```

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

```
authsia setup --status
authsia doctor
```

If setup looks stale, run `authsia setup --repair` and open a new terminal. Full install options: [Install the CLI](/docs/cli/install).

## 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](/docs/app/vault) and [First run](/docs/app/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.

```
authsia workspace init --dry-run
authsia workspace init
authsia workspace status
```

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

```
authsia workspace env list
authsia workspace env use Production
```

Full workflow: [Workspace CLI](/docs/cli/workspace) and [Workspace Center](/docs/app/workspace).

## Step 4: Run through Authsia

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

```
authsia workspace run -- npm test
```

For an interactive tab that shims common tools:

```
authsia guard
```

Agent harness launches do not inherit workspace secrets implicitly. See [Guarded terminal](/docs/cli/guarded-terminal).

## Choose a first workflow

- [Secure local development](/docs/get-started/secure-local-development): Workspace run, guarded terminal, exec, and environment selection.

- [Secure AI agents](/docs/get-started/secure-agents): JIT grants, MCP tools, and keeping plaintext out of agent context.

- [Secure SSH & Git](/docs/get-started/secure-ssh): Adopt keys and sign through the Authsia agent.

- [Command reference](/docs/cli/reference): Compact map of authsia commands. Local --help stays canonical.

## Related topics

- [Use the app](/user-guide.html)

- [CLI overview](/cli.html)

- [Security model](/security.html)