Secure local development

Keep credentials in the Authsia vault, commit authsia:// refs, and resolve secrets only in the child that needs them.

Choose a path

Use this When Guide
workspace run One command or script should receive resolved env from the nearest workspace. Workspace CLI
authsia guard You want an interactive tab where npm, docker, aws, and similar tools resolve through shims. Guarded terminal
authsia exec You already exported authsia:// refs in this shell, or you are selecting specific items. Command reference

Do not export resolved secrets into the parent shell, paste them into tickets, or leave them in .env files agents can read.

Workspace loop

  1. Init refs

    Scan env files, store selected secrets, write commit-safe refs. Preview with --dry-run.

  2. Select one environment

    Named envs use exact-tagged and All items. Default stays inactive until you use Default or clear.

  3. Run at the boundary

    authsia workspace run -- npm test injects plaintext only into the new child. The parent stays clean.

Resolution order

One-run flags beat the active named env. Then the nearest managed env-file directory. Then the deepest vault folder. Same-tier ties fail closed. Guarded shims reuse this order after you change the active environment.

From the app

Create the workspace once in Workspace Center, then open Terminal, Guarded terminal, or Agent tools from the same folder. Health shows Ready or Needs attention. Nested .authsia/workspace.json files are separate workspaces; commands search upward and the nearest config wins.

See Workspace Center.