# /cli.md # Authsia CLI Bring Authsia to your terminal. Install, wire a workspace, connect an MCP client, guard a terminal, approve agents, then audit. Commands stay short; each guide carries the rules. Prefer the app? On macOS, [Vault → New Item dropdown → Import from Files](/docs/app/vault#import-from-files) previews secret scraping and SSH adoption before you save selected items. SSH adoption recognizes equivalent symlinked paths when annotating SSH config. Replace originals defaults on and writes quoted authsia:// object URIs for custom shell exports such as ~/.gamesx-env; turn it off to save without file changes. UI imports offer an optional Overwrite existing value choice for matching passwords, API keys, and SSH keys. UI imports and CLI scrape retain only the latest backup for each source file on each machine. A later import or scrape also replaces any original baseline that Workspace setup kept for that file. Failed cleanup of an older copy stays tracked for retry on the next backup without failing the import. Environment-tagged items stay separate from untagged imports and never conflict. SSH overwrites keep the stored key’s host restrictions. Shell scanning skips computed values; the app lets you choose Password or API Key for detected credentials. App imports use a verified bundled helper. One vault approval covers the selected items, required backups, and SSH storage verification; it grants no reusable CLI session. ## Use cases - [Keep plaintext out of repos](/docs/cli/workspace): Initialize commit-safe authsia:// refs and resolve them in the child process. - [Connect local coding agents](/docs/cli/mcp): Six fixed MCP tools and no secret-return path. The client launches Authsia. - [Manage and protect local MCP](/docs/cli/mcp-proxy): Use the local portal for existing STDIO protection and authenticated localhost Streamable HTTP. - [Approve scoped agent access](/docs/cli/agent-jit): Folder, capability, and TTL — then revoke from Access Center or a paired iPhone. ## Quickstart If you are installing Authsia for the first time, [start here](/docs/get-started). quick path ``` # install app + CLI brew install --cask james-liang-cs/authsia/authsia # prepare the repo authsia workspace init authsia workspace status authsia agent init --agent codex # run commands through Authsia authsia workspace run -- npm test authsia mcp configure --client codex authsia guard ``` ## Guides ### Workspace and terminal - [Install and check readiness](/docs/cli/install) - [Workspace workflow](/docs/cli/workspace) — init, env select, run, resolution order - [Guarded terminal](/docs/cli/guarded-terminal) — PATH shims; agents leave the boundary at launch `authsia workspace env remove` can remove stale bindings even when unrelated MCP configuration needs repair. Vault items and MCP settings stay unchanged. ### Agents and MCP Before `authsia mcp start` or restart, unlock the Authsia app. A locked app reports the unlock-and-retry step; this is separate from tool-call JIT approval. On non-sandboxed macOS builds, installing or updating the CLI enables shell completion automatically. Enabling CLI access or opening Settings with access enabled repairs completion when the CLI is installed. Open a new terminal to load it. Sandboxed builds require manual shell configuration. Workspace setup and update group selected secret migrations and rollback backups into one approval. Env files are rewritten after storage succeeds; local previews and rules-only updates need no vault approval. Workspace setup also merges Copilot hooks into existing compatible settings automatically, preserving custom settings and adding only missing Authsia hooks. Platform-only CLI environment markers preserve matching hook sub-agent identity. Generated agent instructions set those variables directly before `authsia`, without an `env` executable. Claude Code and Codex MCP hooks capture only caller metadata for list, execution, and revocation; MCP server and invocation IDs remain separate. Missing or competing candidates display as sub-agent unknown. Attribution is display-only and never changes authorization. After upgrading, rerun `authsia agent init --agent claude` in existing Claude projects, or `authsia agent init --agent codex` in Codex projects. Restart the coding client and its MCP connection after refreshing hooks. Codex setup adds and trusts the MCP hook automatically. Cursor and Codex wraps store launcher arguments separately and share case-insensitive upstream policy names. For the official `npx @modelcontextprotocol/server-filesystem` launch, Protect makes the selected managed workspace its single exposed filesystem root and shows that scope for confirmation. Other MCP arguments are preserved. Connected stdio proxies notify clients when catalog or policy changes affect their tool list. Cursor STDIO protection binds the selected project's configuration to its absolute workspace using `WORKSPACE_FOLDER_PATHS`, avoiding unresolved launch hints. The global fallback stays unpinned. After Protect, Finish setup in Cursor explains enable and reload steps for the Workspace source (STDIO) or User source (HTTP); Authsia cannot perform or verify those steps. Disabled direct entries must be protected before enabling. Visual Studio Code protection creates a bound project entry in `.vscode/mcp.json`; confirmed repair migrates older global entries and leaves the global fallback protected and unpinned. Open the project folder, restart through MCP: List Servers , and run MCP: Reset Cached Tools . Devin remains unpinned and uses its launch context. Claude Code, including its VS Code extension, passes its project directory to the proxy at runtime. Codex CLI and its VS Code extension use their own session launch context. Neither needs a generated global project pin; conflicting proxy workspace hints fail closed. MCP Manager shows protection per client in Servers. Managed wraps retain a safe launch definition for reviewed recovery in another workspace; older Context7 entries offer the official preset without requiring manual command entry. Catalog capture defaults all recorded tools to allow when policy is empty. Existing policy choices are preserved. Review permissions in MCP Manager > Edit policy. Verified audit export includes management changes; Activity reports its bounded retention separately. Allow tools reuse admitted server access; Approve tools ask on every invocation over STDIO and HTTP. Denied tools stay hidden. Activity records received calls and shows reviewed policy changes separately, including the changed tools, actor class (currently native, not caller identity), and time. Authorization refusals are Denied; disabled CLI access retains the cliAccessDisabled reason. MCP setup and launch commands require MCP Integrations in Authsia Settings > Developer Access . If it is off, enable it in the app and retry. Status, diagnostics, and stop remain available. Codex IDE chat initialization accepts unsupported experimental capability objects without changing tool policy. HTTP startup GET probes do not request JIT; admission starts with the first permitted tool call. Removing Codex HTTP routing also removes its nested header tables. - `authsia agent init --agent codex` — install project rules and attribution hooks, then automatically trust only Authsia’s exact hooks through the local Codex CLI; reload Codex afterward. Setup reports if `/hooks` review is still needed - [Local MCP server](/docs/cli/mcp) — configure and serve Authsia’s six tools - [MCP Manager](/docs/cli/mcp-proxy) — portal, STDIO coverage, and localhost Streamable HTTP - [Agent JIT approvals](/docs/cli/agent-jit) — scope, cleanup, automation credentials. Recognized agents such as `agy` reuse approved grants across command shells until agent exit, expiry, or revocation. Runs with no file findings emit no file-inspection or cleanup warning ### SSH and audit Verified host-bound SSH requests support once or duration approval on the Mac and an opted-in paired iPhone. Access Center shows and revokes active grants; `authsia lock` revokes grants matching the current terminal or observed caller. An automation credential use is consumed before SSH signing. - [SSH signing](/docs/cli/ssh) - [Audit and recovery](/docs/cli/audit) ## Reference - [Compact command map](/docs/cli/reference). Local `authsia --help` remains the option source of truth. ## Related topics - [Developer quickstart](/docs/get-started) - [Use the app](/user-guide.html) - [Security model](/security.html) - [AI-readable docs](/docs/ai-readable-docs) # /docs/ai-readable-docs.md # AI-readable docs Point coding agents at a curated index instead of scraping the HTML site. The index lists guides, not secrets, seeds, or private keys. ## llms.txt The site publishes a [llmstxt.org](https://llmstxt.org) index at [/llms.txt](/llms.txt). Use it to discover pages before fetching them. Concatenated Markdown lives at [/llms-full.txt](/llms-full.txt). Each HTML guide also has a sibling Markdown file with the same path and a `.md` suffix, for example [/docs/get-started.md](/docs/get-started.md) and [/cli.md](/cli.md). ## In a coding agent - ### Fetch the index Read `https://authsia.clarionstack.com/llms.txt` (or this origin’s `/llms.txt`). - ### Open one guide Prefer the `.md` URL for the topic you need. Do not load the entire `llms-full.txt` unless the task spans many pages. - ### Stay on the public contract These pages describe product behavior. They are not a substitute for `authsia --help` on the installed CLI. ### Do not paste secrets Never put Keychain material, seeds, private keys, or OTP codes into prompts, fixtures, or documentation fetches. ## Related topics - [Documentation home](/docs/) - [Developer quickstart](/docs/get-started) - [Local MCP server](/docs/cli/mcp) # /docs/app/access-center.md # Access Center See who can use the vault, for how long, and revoke without editing project files. ### Remote JIT Approve or deny from a paired iPhone when you are away from the Mac. ### Investigation flags Info / Review / Warning are local display cues. They do not revoke or authorize. ### Click to focus Insights summarize recent access by item and folder so you can drill in quickly. ## MCP proxy grants Access Center’s MCP proxy filter lists runtime admission and proxy grants. Server setup, protection coverage, and catalogs live in [MCP Manager](/docs/cli/mcp-proxy). Open it from the Local MCP strip on that filter. Calls that never received a grant — for example a denied or unavailable upstream — appear in MCP Manager Activity with inspector Grants: None recorded. They are rejected before Authsia creates a grant. ## Related topics - [Agent JIT approvals](/docs/cli/agent-jit) - [MCP Manager](/docs/cli/mcp-proxy) - [Local MCP server](/docs/cli/mcp) - [Agent-safe workflows](/docs/app/agents) # /docs/app/agents.md # Agent-safe workflows Keep plaintext out of prompts, diffs, and terminal output agents can observe. ### Without JIT Unlock as a human or supply a scoped automation credential. Agents must stop when access is missing — not fall back to plaintext commands. ### With JIT Confirmed agent context uses scoped folder grants for `exec` and `list`. Deny or expiry ends the path. ### Need the commands? Agent launch, access create/revoke, and guarded shell live in the CLI guides. [Open agent JIT](/docs/cli/agent-jit) ## Related topics - [Secure AI agents](/docs/get-started/secure-agents) - [Local MCP server](/docs/cli/mcp) - [Access Center](/docs/app/access-center) # /docs/app/first-run.md # First run Install once, launch once, then enable only the CLI surface you need. ### Offline by default Vault data stays on your Mac through Apple security services. ### Narrow folders early Team/API, Production, Infra/SSH — grants later mirror these boundaries. ### App-only when needed Disable CLI on items that should never leave the app UI. ## Quick checks - `authsia status` for bridge, shell, session, and SSH agent. - `authsia doctor` when setup looks stale. - `authsia lock` or revoke in Access Center to end sessions. ## Related topics - [Developer quickstart](/docs/get-started) - [Install the CLI](/docs/cli/install) - [Vault](/docs/app/vault) # /docs/app/vault.md # Vault as an access boundary Folders and CLI toggles are the main safety controls. ## Import from files in the app On macOS, open Vault → New Item dropdown → Import from Files and choose Scan for Secrets or Adopt SSH Keys. The source starts at ~/.zshrc for secrets or ~/.ssh for SSH keys, so you can preview immediately. Edit the path or use Browse to choose another source; Use Default restores the suggested path. Choose a destination folder, preview the proposed changes, select items, choose Password or API Key for each ordinary credential, then confirm Save and Apply Changes. The reference preview updates to match the chosen category. Shell expressions and computed values are skipped. Preview does not write to the vault or source files. Replace originals after saving is checked by default. Clear it to save only, leaving source files, SSH config, and shell integration unchanged. Replacement supports literal exported assignments in custom shell files such as ~/.gamesx-env, writing quoted authsia:// object URIs without command substitution. Matching CLI-enabled passwords and API keys can be reused on retry. For an existing password, API key, or SSH key in the destination folder, select Overwrite existing value to replace its saved value; this is off by default. The overwrite choice is tied to the reviewed item and included in the single approval. Only one source can be selected to overwrite each existing item. Ambiguous matches and items with CLI access disabled are skipped. Environment-tagged items never count as conflicts. Item IDs, other metadata, and SSH access restrictions are preserved. Imports retain only the latest source-file backup per machine, removing older copies (including a Workspace setup original) after the new snapshot is stored. One vault approval covers the selected items, required backups, and SSH storage verification. Newly scanned secrets and adopted SSH keys have CLI access enabled by default. Conflicts without an overwrite choice are skipped. Scrape backs up and rewrites supported environment and shell files; SSH adoption verifies vault storage before replacing local private keys with Authsia stubs. Changed source files require a new preview. ## Prefer references Put `authsia://` refs in scripts and env files. Secrets resolve only at approved runtime. ## SSH via the agent Git and SSH should sign through Authsia’s agent — not by exporting private keys into the shell. See [Secure SSH & Git](/docs/get-started/secure-ssh). ## Copy Path stays shell-ready Copy Path yields `export NAME='authsia://…'` so pasted refs stay visible to child commands. ## Related topics - [First run](/docs/app/first-run) - [Workspace Center](/docs/app/workspace) - [Workspace CLI](/docs/cli/workspace) - [Security model](/security.html) # /docs/app/workspace.md # Workspace daily loop Create once from the app, then open terminal, guarded terminal, or agents from the same folder. ### Commit-safe config `.authsia/workspace.json` holds name, folder, env files, and agent rules — not plaintext secrets. ### Nearest workspace wins Commands search upward for workspace config. A nested config is a separate workspace. ### Env before depth Active Production tags beat deeper Default items. Same-tier ties fail closed. ### Parent stays clean Guarded launches inject plaintext only into new child processes. ## Terminal equivalents ``` authsia workspace status authsia workspace run -- npm test authsia guard authsia unguard authsia workspace agent --tool codex --dry-run ``` ## Related topics - [Workspace CLI](/docs/cli/workspace) - [Secure local development](/docs/get-started/secure-local-development) - [Access Center](/docs/app/access-center) # /docs/cli/agent-jit.md # Agent JIT approvals Agents ask through Authsia. You grant a folder, capability, and TTL — then revoke from Access Center or a paired iPhone. **Tree only** The grant follows descendants of the approved directory. Siblings and symlink escapes do not inherit. `$HOME` or `/` stays exact — no children. **Display only** Attribution never changes authorization. Missing or competing sub-agent candidates show as unknown. ### Scope Named folder covers descendants, never ancestors or siblings. Root is root-only; workspace bindings select it explicitly with `folder=%2F`. ### Allowed JIT permits scoped `list` and `exec` only — with caller, TTL, and CLI checks. ### Not JIT `access create` makes reusable automation credentials. Separate path from JIT grants. ### Human vs agent TTY alone is not human auth. Eligible IDE terminals pair with an app-displayed code. Agent evidence still routes to JIT. Recognized agent processes such as `agy` reuse approved grants across command shells, including commands with a terminal. A command shell exiting does not revoke the grant; agent exit, expiry, or explicit revocation ends reuse. Caller, workspace, item, and capability checks still apply. **Pairing, hooks, and setup** Generated agent instructions set `AUTHSIA_AGENT_PLATFORM` and `AUTHSIA_AGENT_INVOKES_AUTHSIA` directly before `authsia`; they do not invoke an `env` executable. ### Copilot Merges Authsia hooks into compatible settings. Preserves custom hooks. Invalid JSON gets repair guidance. ### Codex Installs rules and hooks, then trusts Authsia’s exact hook definitions. Rerun `authsia agent init --agent codex` to repair. Custom and disabled hooks stay. ### Claude After upgrading, rerun `authsia agent init --agent claude` in existing projects, then restart the client and MCP connection. ### Paired list A paired human’s direct `list` reuses the normal session only when Bridge reports that pairing. The Bridge does not open Agent JIT for that pairing. ### Post-exit file inspection After Agent JIT authorizes a secret-bearing `exec` or `workspace run`, Authsia conceals matched injected values in observed files as ` `. ### Rewritten Exact injected values plus one-layer Base64, URL-safe Base64, hex, percent/form, shell, HTML, and JSON. Encoded payloads are invalidated, not left recoverable. ### Skipped Binary, non-UTF-8, oversized, and symlink writes. No recursive decode or archive expansion. Human CLI and automation credentials do not start observation. ### Warnings None when there are no file findings. Warnings remain for detected secrets and inspection failures. Child exit status is preserved. ### Network Best-effort outbound TCP and connected UDP metadata under Activity → Network. Not blocking. Never payloads, URLs, headers, DNS, or secrets. ## Commands ``` authsia workspace agent --tool codex --goal "Fix checkout" --dry-run ``` ``` authsia workspace run -- npm test ``` ``` authsia access create --name codex --scope Team/API --ttl 15m --allow exec ``` ``` authsia env profile add --name prod --folder Team/API --folder Team/Web authsia access create --name codex --env prod --ttl 15m --allow exec ``` ``` authsia access create --name codex-ssh --scope Team/API --ttl 15m --allow ssh ``` ``` authsia access revoke authsia lock ``` ``` authsia status authsia lock ``` ## Related topics - [Access Center](/docs/app/access-center) - [Agent-safe workflows](/docs/app/agents) - [Local MCP server](/docs/cli/mcp) # /docs/cli/audit.md # Audit and recovery Review attribution without secret values. Repair when refs drift from the vault. ``` authsia audit list --format table authsia audit export --format ndjson --out-file events.ndjson authsia audit export --verify --out-file events.json ``` ``` authsia workspace status authsia workspace update --dry-run authsia workspace reset --dry-run ``` Use `authsia doctor` when setup looks stale, and `authsia lock` to end sessions. ## Related topics - [Workspace CLI](/docs/cli/workspace) - [Access Center](/docs/app/access-center) - [Command reference](/docs/cli/reference) # /docs/cli/guarded-terminal.md # Guarded terminal PATH shims for common tools. Humans get convenient resolution; agent harness invocations do not inherit workspace secrets implicitly. ### Agents leave the shim at launch Workspace Agent, app menu, printed commands, and hand-typed `claude`, `code`, `codex`, `cursor`, or `devin` start without guard markers. The parent tab stays guarded. ``` authsia guard ``` Run `authsia setup --repair` once and open a new terminal first. ``` authsia status --verbose ``` ### Active Shim count is live in this tab. ### Stale Guard metadata and `PATH` disagree. ### Inactive Inside a launched agent session. Agent launchers start unguarded; they are not routed through `workspace run`. ``` authsia unguard ``` ``` eval "$(authsia workspace guard --tool rails --print-env)" ``` ``` authsia workspace run --shell -- 'curl "$API_KEY"' ``` ## Default tool families npm, pnpm, yarn, python, pip, docker, aws, gcloud, az, kubectl, helm, terraform, tofu, terragrunt, pulumi, ansible-playbook. ## Related topics - [Workspace CLI](/docs/cli/workspace) - [Secure AI agents](/docs/get-started/secure-agents) - [Command reference](/docs/cli/reference) # /docs/cli/install.md # Install and check readiness Homebrew for the released app and CLI. Existing DMG installs can be adopted without reinstalling. ``` brew install --cask james-liang-cs/authsia/authsia ``` ``` brew install --cask --adopt james-liang-cs/authsia/authsia ``` ``` open /Applications/Authsia.app authsia setup --status authsia setup --repair authsia doctor ``` ## After install Launch the app once so the Bridge can register. Open a new terminal after `setup --repair`. Confirm `authsia status` before connecting MCP clients or enabling a guarded tab. On non-sandboxed macOS builds, installing or updating the CLI enables shell completion automatically. Enabling CLI access or opening Settings with access enabled repairs completion when the CLI is installed. Open a new terminal to load it. Sandboxed builds require manual shell configuration. ## Related topics - [Developer quickstart](/docs/get-started) - [First run](/docs/app/first-run) - [Workspace CLI](/docs/cli/workspace) - [Verify a release](/verify.html) # /docs/cli/mcp-proxy.md # MCP Manager Gate workspace-declared local MCP servers through the STDIO proxy or the app-owned localhost Streamable HTTP manager. Credentials stay behind native admission and Keychain references. **Unlock first** `authsia mcp start` and restart need an unlocked Authsia app. That prompt is not tool-call JIT. **Cursor scope** If a project server is missing, open that folder in Cursor and select its workspace — not User. Do not add a global duplicate. A wrapped client never launches the upstream itself. Direct launches skip this path and are existence-only findings. ## How Authsia rewrites MCP config Authsia never silent-rewrites a client file. MCP Manager Protect connection / Protect a client and `authsia mcp wrap --write` show the current entry, the replacement, and a SHA256 checksum. You confirm; `--yes` or the native sheet applies the write. `authsia mcp configure` prints a user-global fallback and does not write. The coding tool’s launch is replaced so it starts Authsia. The real child command is declared in workspace policy. For the recognized `npx @modelcontextprotocol/server-filesystem` launch, the selected managed workspace replaces all previous directory arguments as the server’s single exposed root. The confirmation names this scope; other packages and ambiguous argument forms keep their original arguments. Protect or re-protect also updates an existing filesystem declaration after native confirmation, preserving tool policy, credential bindings, and the catalog. Removing protection retains that declaration; upgrades do not widen its scope automatically. A Cursor project wrap looks like this (from an Authsia-Demo workspace Protect of `codegraph`): Client file before Protect .cursor/mcp.json · scanned ``` { "mcpServers": { "codegraph": { "command": "codegraph", "args": ["serve", "--mcp"] } } } ``` Client file after Protect .cursor/mcp.json · wrapped ``` { "mcpServers": { "codegraph": { "command": "/Applications/Authsia.app/Contents/Helpers/authsia", "args": ["mcp", "proxy"], "env": { "AUTHSIA_MCP_LAUNCH": "[\"codegraph\",\"codegraph\",\"serve\",\"--mcp\"]", "AUTHSIA_MCP_UPSTREAM": "codegraph", "WORKSPACE_FOLDER_PATHS": "/Users/you/PlayGround/Authsia-Demo" } } } } ``` Env What it does `AUTHSIA_MCP_UPSTREAM` Names the workspace declaration. Company allowlists match `authsia mcp proxy` without enumerating every server. `WORKSPACE_FOLDER_PATHS` Pins Cursor STDIO to that project’s absolute folder so the proxy does not guess another workspace. `AUTHSIA_MCP_LAUNCH` Review-only recovery metadata (name, command, args). The proxy still launches from workspace policy. Never credentials, tool policy, catalogs, or grants. The child is declared in that workspace’s `.authsia/workspace.json`. Neighboring servers stay. Wrap does not copy client-side environment values; the preview names how many there were. Secret refs stay in workspace policy as `authsia://`. .authsia/workspace.json · mcpUpstreams ``` { "mcpUpstreams": [ { "name": "codegraph", "command": "codegraph", "args": ["serve", "--mcp"], "transport": "stdio" } ] } ``` Client Protect writes Cursor STDIO Selected project’s `.cursor/mcp.json` with that folder’s absolute path in `WORKSPACE_FOLDER_PATHS`. VS Code STDIO Bound project override in `.vscode/mcp.json`. Claude Code Scanned project or user file. Local scope uses `projects[root].mcpServers` in `~/.claude.json`. Protect a client May insert the proxy launch when a JSON client does not already name the server. Codex STDIO still needs a scanned entry. HTTP enrollment User-local client config only — never a repository MCP file — to `http://127.0.0.1:8788/mcp/{server-id}`. ### Unwrap restores the launch, not the old env Remove protection and `authsia mcp unwrap --write` restore command and argv from that row’s exact workspace declaration after the same diff and checksum. Workspace policy stays. Client environment values from before protection cannot be recovered, and declared `authsia://` refs are not copied into the direct launch. A changed client file or restore command is refused. ## Global connections, workspace-specific protection A global client entry makes a server available across projects. Each Authsia workspace still decides how that server runs. ### Global client config Shared launch in Codex, Claude, or another client. Wrapped STDIO starts `authsia mcp proxy` with `AUTHSIA_MCP_UPSTREAM`. ### Project client config May override matching global entries. Check the effective, overridden, or conditional label in Manager. ### Workspace policy Real command, args, tool policy, and secret bindings live in that workspace’s `.authsia/workspace.json`. ### Same name, two workspaces A global Playwright proxy can serve `project-a` and `project-b`, but both need their own declaration. If only `project-a` has one, Manager shows Playwright as unconfigured in `project-b`. The Servers table shows each effective client’s protection status next to its name — including mixed protected, bypassing, and unconfigured connections. ### Set up another workspace - ### Select and discover Choose the target workspace and discover its servers. - ### Use existing setup Open the already-wrapped server, pick the source workspace, and review launch plus tool policy. - ### Confirm Creates an independent declaration. Later edits are not synchronized. - ### Bind secrets and admit Add required secret bindings, reload the client, then make a permitted call. **Not copied** Secret bindings, runtime grants, and recorded catalogs. Relative launch paths resolve in the target workspace. **Fallback** Saved launch from a managed wrap, or the official Context7 preset for older Context7 entries. Recovered launches copy no tool permissions. ### Which workspace runs ### STDIO order Explicit `--workspace`, then a safe `WORKSPACE_FOLDER_PATHS` or `CLAUDE_PROJECT_DIR` hint, then the proxy working directory. Conflicting hints stop startup. ### Manager filter Changing the workspace filter does not switch a running client’s workspace. ### HTTP A protected HTTP endpoint belongs to one workspace and server. It does not switch when the client changes directories. Client After Protect Cursor Enable the **Workspace source** (STDIO) or **User source** (HTTP) under Customize → Manage scope, then Reload. A working global Playwright source does not prove the project filesystem source is enabled. Repair needed: missing or placeholder `WORKSPACE_FOLDER_PATHS`. VS Code Open the project folder, restart via MCP: List Servers, then MCP: Reset Cached Tools. Repair creates a project override and clears the old global binding. Claude Code Reads `CLAUDE_PROJECT_DIR` at runtime. No fixed project path is added. Codex Uses Codex MCP config and the session working directory, independent of VS Code’s MCP host. Start a session in the new project when switching. Devin Unpinned. Uses launch context. Unresolved or ambiguous proxy workspace hints stop startup rather than selecting another project’s policy. ## What it gates Declare a no-shell stdio command or a validated loopback HTTP URL in the commit-safe workspace file. STDIO clients launch `authsia mcp proxy`; HTTP clients use the manager’s protected endpoint. Authsia starts or forwards only after approval. ### Launchers Wrap splits `npx`, `npm exec`, `pnpm dlx`, and `bunx` into an executable and args. No shell. Legacy joined commands split on the next catalog write. ### Names `Playwright` and `playwright` share a declaration. Conflicting case variants need explicit reconciliation; permissions are never merged automatically. ### Live catalog Connected stdio proxies recheck the visible catalog once per second and send `notifications/tools/list_changed`. An older Authsia binary needs one client restart. ### Credentialed Uses secret JIT. ### Empty catalog Credential-less empty policy needs local admission before a short discovery probe. Automatic discovery runs only with an entirely empty declared environment. ### Admission TTL Defaults to 30 minutes, company-capped, expires absolutely. Renews only through a fresh client-originated approval. ### Pinned catalog Lists from policy without launching the child. ### Out of scope Remote HTTP/HTTPS/SSE stay on the company gateway. Direct launches that skip Authsia are existence-only findings. ### MCP Integrations is off by default Enable it in Settings → Developer Access . Client config cannot turn it on. While off, `configure`, `wrap`, `unwrap`, `declare`, `catalog`, `serve`, `proxy`, `start`, and `restart` fail. Help, `status`, `doctor`, `activity export`, `stop`, and portal revocation still work. ## Allowlist Authsia in managed agent settings Deploy two things: an administrator-enforced launch policy, and client configuration that connects through Authsia. Copying a user config file is not enforcement. **Binary** Signed app at a company-controlled path. Examples use `/Applications/Authsia.app/Contents/Helpers/authsia`. **Launch** `mcp proxy` plus `AUTHSIA_MCP_UPSTREAM`. Keep `--upstream` and fixed workspace args out of shared launches. Allow `mcp serve` for Authsia’s own tools. **Not admission** These policies do not approve an upstream or replace native JIT. Five clients from `authsia mcp configure` on macOS. Vendor docs checked 8 Sep 2026 — validate the deployed client version. ### Claude Code Deploy this JSON through managed settings, for example MDM installing `/Library/Application Support/ClaudeCode/managed-settings.json`: managed-settings.json ``` { "allowManagedMcpServersOnly": true, "allowedMcpServers": [ { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "serve"] }, { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "proxy"] } ] } ``` **Claude Code matching rules** Exact command matching lets users add new proxy server names without changing this allowlist. The managed-only flag prevents user allowlists from broadening it. Avoid name-only rules; deny rules still win. Deploy an exclusive `managed-mcp.json` only if IT owns a fixed server catalog. See [managed MCP controls](https://code.claude.com/docs/en/managed-mcp) and [file locations](https://code.claude.com/docs/en/mcp). ### Codex Deploy requirements through `/etc/codex/requirements.toml`, cloud-managed requirements, or the macOS MDM preference `com.openai.codex:requirements_toml_base64`. Use a client supporting structured command matchers. This example approves the configured names `authsia` and `jira`: requirements.toml ``` [mcp_servers.authsia.identity] command = { executable = "/Applications/Authsia.app/Contents/Helpers/authsia", args = [ { match = "exact", value = "mcp" }, { match = "exact", value = "serve" }, ] } [mcp_servers.jira.identity] command = { executable = "/Applications/Authsia.app/Contents/Helpers/authsia", args = [ { match = "exact", value = "mcp" }, { match = "exact", value = "proxy" }, ] } ``` **Codex matching and plugins** Both the configured server name and identity must match. Repeat the proxy block for each extra name. Structured matchers check executable, argument count, and order — not environment or working directory. Put generated launches in `~/.codex/config.toml`. For a rollout using only direct configuration, `features.plugins = false` disables plugin-bundled MCP. See the [config reference](https://learn.chatgpt.com/docs/config-file/config-reference) and [managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration). ### Cursor Enterprise In the team dashboard's MCP Configuration , add these two command entries: Cursor enterprise MCP commands ``` /Applications/Authsia.app/Contents/Helpers/authsia mcp serve /Applications/Authsia.app/Contents/Helpers/authsia mcp proxy ``` **Cursor matching and permissions** Matches the full command plus arguments — use the exact deployed path. The allowlist does not install servers; distribute generated entries to `~/.cursor/mcp.json` or the project file. `permissions.json` / `mcpAllowlist` is tool auto-run, not launch policy. See [enterprise MCP](https://prod.cursor.com/docs/enterprise/model-and-integration-management) and [permissions](https://prod.cursor.com/docs/reference/permissions). ### VS Code with GitHub Copilot VS Code 1.132+: deploy the Claude-shaped JSON through Copilot managed settings, or policies `ChatAllowedMcpServers` and `ChatAllowManagedMcpServersOnly`. Do not paste those names into ordinary workspace settings. **VS Code versions and ChatMCP** Allow/deny policies need 1.130; managed-only needs 1.132. Leave `ChatMCP` at `all` for this pattern. Distribute into the user-profile `mcp.json` or project `.vscode/mcp.json`. Verify with Developer: Policy Diagnostics. See [enterprise AI settings](https://code.visualstudio.com/docs/enterprise/ai-settings). ### Devin Desktop ### Distribution, not proven prevention Authsia prints `~/.config/devin/mcp_config.json` via `authsia mcp configure --client devin`. No verified administrator command allowlist. Cloud Devin MCP settings do not enforce local Desktop. ### Distribute connections and verify the rollout From each declared workspace, print the matching client configuration: print only · no write ``` authsia mcp configure --client claude authsia mcp configure --client codex authsia mcp configure --client cursor authsia mcp configure --client vscode authsia mcp configure --client devin ``` Print only — merge, do not replace unrelated settings. The fallback names the upstream only. A Cursor project Protect write also sets `WORKSPACE_FOLDER_PATHS` and `AUTHSIA_MCP_LAUNCH`; see [How Authsia rewrites MCP config](#rewrite). printed user-global fallback ``` { "mcpServers": { "codegraph": { "command": "/Applications/Authsia.app/Contents/Helpers/authsia", "args": ["mcp", "proxy"], "env": { "AUTHSIA_MCP_UPSTREAM": "codegraph" } } } } ``` Before broad deployment, verify on a pilot Mac: - Reload the client and confirm it received the managed policy. Check project entries as well as user-global entries. - Confirm an approved proxy connection reaches Authsia admission and a permitted tool works after approval. - Confirm a harmless direct MCP fixture is blocked by the client policy, including under an approved server name. A doctor finding alone is not proof of enforcement. - Add another wrapped server: Claude, Cursor, and supported VS Code should accept the shared command; Codex needs that server name added to requirements. - Run `authsia mcp doctor` from every target workspace, resolve effective direct launches, then confirm revocation stops an admitted STDIO child. Record redacted results only. ### STDIO allowlists do not cover HTTP Approve the exact enrolled `http://127.0.0.1:8788/mcp/{server-id}` URL. Do not allow the original upstream URL or every loopback endpoint. Remote MCP stays a company-gateway decision. ## Print proxy entries From a managed workspace, `authsia mcp configure` prints declared upstreams as separate proxy entries. A wrapped entry is declared and routed through Authsia, not pre-approved. ``` authsia mcp configure --client vscode ``` ## Declare an upstream If a STDIO proxy launch has no workspace policy yet, declare the child command first. For a validated loopback HTTP endpoint, use [--url under MCP Manager](#manager). ``` authsia mcp declare --server codegraph --command codegraph --arg serve authsia mcp declare --server codegraph --command codegraph --arg serve --yes ``` ``` authsia mcp proxy --upstream jira ``` ## Wrap and unwrap See [How Authsia rewrites MCP config](#rewrite) for the file-level before and after. Previews keep child env keys and replace every value. If the scanned entry already set child environment, name tools under `mcpUpstreams.tools.allow` instead of automatic catalog recording. ``` authsia mcp wrap --write --server jira ``` Unwrap previews both entries plus checksum, then restores command and argv from that row’s workspace declaration. Old client env cannot be recovered. Reopen the client after restoring. ``` authsia mcp unwrap --write --server jira authsia mcp unwrap --write --server jira --yes ``` ## Catalog capture and policy review Allow tools reuse admitted server access. Approve tools require native approval on every STDIO or HTTP invocation, even when the server is already running. A cold STDIO call may also ask for server admission or credential access. After upgrading Authsia, restart client MCP connections so the proxy and app both support per-call approval. Deny tools are hidden from clients. Only calls received by Authsia appear as denied attempts; a chat request for an unavailable tool creates no MCP call record. Activity records policy changes separately. Open a configuration-change row to see the reviewed changes, such as `edit_file: Allow → Deny`, the recorded actor class (`native`, not caller identity), and time. Reviewed summaries preserve line breaks up to 4,000 characters. Approval and admission refusals are `denied` / `approvalDenied`; disabled CLI access is `denied` / `cliAccessDisabled`. A lost session is `upstreamUnavailable`, not a workspace-policy denial. Tool names in those summaries are searchable and included in the Activity metadata export. Capture starts the child once behind admission and records metadata. **Empty policy** Recorded tools default to allow. Empty-policy calls do not discover or start servers. **Existing policy** Choices are preserved. New tools need classification in Edit policy. **Activity** At most 30 days, 2,000 events, 1 MiB. Rows are not HMAC verification. Manager writes need a Bridge audit intent. ``` authsia mcp catalog --server codegraph --write ``` ``` authsia mcp doctor authsia mcp doctor --json --home /tmp/fleet-home ``` `mcp doctor` prints scanned launches plus a verdict. Exit 2 means an effective or conditional bypass. Unreadable client files are skipped. ``` authsia mcp activity export --json --unowned ``` `mcp activity export` copies redacted proxy command-history rows. Filters: `--since`, `--upstream`, `--workspace`, `--unowned`. ## MCP Manager and localhost HTTP ``` authsia mcp start authsia mcp status --json authsia mcp stop authsia mcp restart ``` ### Portal `127.0.0.1:8787` from the signed app with MCP Integrations on. ### Protected HTTP `127.0.0.1:8788/mcp/{server-id}`. Stop ends forwarding and portal sessions; STDIO proxies keep running. ### Discover Scans client configs without starting servers. Protect and HTTP enrollment write only after native confirmation. ### HTTP GET Startup GET is local `405` — no JIT, no credentials, no upstream. The first permitted tool call requests admission. ### Loopback only `http` plus `localhost`, `127.0.0.1`, or `::1`, with an explicit port. First HTTP declaration advances the workspace to schema v3. ``` authsia mcp declare --server internal --url http://127.0.0.1:9000/mcp --allow search --approve create --deny delete --yes ``` Optional upstream headers stay Keychain references and resolve after admission. Activity records server, tool, attribution, and coarse outcome — not payloads or credentials. ### Visibility boundary Wrapped calls record the MCP tool name only — not arguments or results. A direct or unadmitted config entry is existence-only: Authsia cannot audit its calls, stop it on revoke, or prevent its launch. This local stdio and localhost HTTP layer complements a company MCP gateway’s SSO and remote policy; it does not replace the gateway. ## Access Center ### Revoke Ends the process group. ### Grants Access Center lists runtime admission and proxy grants. Open MCP Manager from the Local MCP strip. ### Coverage Manager Servers for wrap status. Activity for observed calls with Grants: None recorded. ## Related topics - [Local MCP server](/docs/cli/mcp) - [Agent JIT approvals](/docs/cli/agent-jit) - [Access Center](/docs/app/access-center) - [Secure AI agents](/docs/get-started/secure-agents) - [Command reference](/docs/cli/reference) # /docs/cli/mcp.md # Local MCP server The Model Context Protocol (MCP) lets local coding agents use Authsia without receiving your secrets. Connect Codex, Claude Code, Cursor, Devin Desktop, or VS Code; the client manages the local server while Authsia keeps its existing approvals, Keychain access, audit, and masking. Do not start `authsia mcp serve` from an agent terminal. The client owns the process. ### MCP Integrations is off by default Enable it in Settings → Developer Access . Client config cannot turn it on. While off, setup and launch commands fail. Help, `status`, `doctor`, and `stop` still work. ## Use a user-global client entry Print the fallback for the installed Authsia binary, then add those entries in the client. The command never embeds credentials or a repository path. ### With upstreams Declared servers appear as separate `mcp proxy` entries. Otherwise the output is serve-only. ### Precedence Project-scoped Claude, Cursor, and VS Code entries outrank matching user-global entries. Declarations never cross repository roots. ``` authsia mcp configure --client vscode ``` ## Let the MCP client launch Authsia Your MCP client starts `authsia mcp serve` itself. Authsia checks its app-level MCP setting on every tool call and fails closed while disabled. Do not start it from an agent terminal; use the client’s MCP controls if the tools are missing or disconnected. ### Gate a third-party MCP To wrap, catalog, or proxy a workspace-declared stdio upstream, or to protect localhost Streamable HTTP, see [MCP Manager](/docs/cli/mcp-proxy). ## Six fixed tools ### Fixed tools `authsia_status`, `authsia_workspace_inspect`, `authsia_list`, `authsia_exec`, `authsia_access_status`, and `authsia_access_revoke`. ### One workspace at a time One global client entry works across initialized Authsia workspaces. Workspace tools use the active repository and remain unavailable until one is selected. ### No secret-return tool MCP can inspect safe workspace state, list scoped metadata, and run approved commands. Empty item categories return an empty page, not an operation failure. MCP cannot read or return plaintext secrets, global audit history, or Vault administration data. ### Approval remains independent For metadata listing and credential-dependent execution, Authsia uses the same scoped Agent JIT approval on your Mac or paired iPhone. Client-side tool approval is only a convenience; it never grants secret access. Grant status and revocation are limited to the current MCP server instance. After adding the entry, reload or restart the client and confirm that `authsia_status` appears in its tool picker before starting an agent task. ## Related topics - [MCP Manager](/docs/cli/mcp-proxy) - [Secure AI agents](/docs/get-started/secure-agents) - [Agent JIT approvals](/docs/cli/agent-jit) - [Access Center](/docs/app/access-center) - [Command reference](/docs/cli/reference) # /docs/cli/reference.md # Compact command map Orientation only. Local `authsia --help` remains the option source of truth. Command Use it for Example status App, bridge, Direct CLI session or IDE pairing, shell, guarded-terminal, and SSH agent state authsia status --format json workspace Repo setup, refs, guarded runs, sync, reset authsia workspace run -- npm test agent init Install setting-aware agent rules plus supported command-attribution and sub-agent-lineage hooks authsia agent init --agent codex mcp configure Print-only recipe plus a table of that client's current launches authsia mcp configure --client codex mcp start Start the app-owned MCP Manager and open its authenticated portal authsia mcp start mcp status Report manager, registry, portal, and localhost HTTP readiness authsia mcp status --json mcp stop Stop manager listeners without stopping existing STDIO proxies authsia mcp stop mcp restart Restart manager listeners and invalidate portal sessions authsia mcp restart mcp wrap Declare and protect one scanned local MCP launch after review; plan redacts env values authsia mcp wrap --write --server jira mcp declare Declare a STDIO child command or validated localhost HTTP endpoint authsia mcp declare --server internal --url http://127.0.0.1:9000/mcp --allow search --yes mcp unwrap Preview and restore a protected launch while retaining workspace policy authsia mcp unwrap --write --server jira mcp catalog Record what a declared local MCP server advertises, so clients list its tools without starting it authsia mcp catalog --server codegraph --write mcp serve Bind a validated workspaceRoot tool input or safe launch context authsia mcp serve --workspace /path/to/repo mcp proxy Admit one workspace-declared stdio MCP; secret refs use Agent JIT authsia mcp proxy --upstream jira mcp doctor Default table of scanned launches plus a verdict; exit 2 on effective or conditional bypass. JSON v2 includes host, version, MCP Integrations, and audit integrity authsia mcp doctor --json mcp activity export Copy redacted MCP proxy command-history rows authsia mcp activity export --json --unowned guard Activate guarded mode in the current shell authsia guard unguard Restart the current tab in normal terminal mode authsia unguard exec Resolve selected items or, with shell integration, shell-local authsia:// refs into one child process API_KEY=authsia://… authsia exec -- npm start list Metadata-only vault listing; scraped items default to this machine authsia list api-keys --format table completion Shell scripts and metadata suggestions; automation uses list permission eval "$(authsia completion zsh)" read Resolve one authsia:// secret reference authsia read "authsia://api-key/Stripe/key" add api-key Store API keys without a username field authsia add api-key --name Stripe --key - edit Update fields, move to a folder, or move any editable vault item to Root with --clear-folder authsia edit password GitHub --clear-folder convert Move password-style tokens into API Keys authsia convert password Stripe --to api-key ssh Adopt, generate, sign, and configure SSH keys authsia ssh adopt --path ~/.ssh --dry-run access Manage automation access credentials authsia access list --format table audit Local access history authsia audit list ## Related topics - [CLI overview](/cli.html) - [Install](/docs/cli/install) - [Developer quickstart](/docs/get-started) # /docs/cli/ssh.md # SSH signing Adopt keys into Authsia, then let Git and SSH use the local agent. Headless signing uses a separate SSH-only credential; shell integration and `authsia exec` obtain Bridge-issued, process- or terminal-bound leases without writing the bearer into the runtime grant file. The SSH agent consumes an automation credential use before signing. If signing fails, that use remains spent. ## Adopt SSH keys in the app On macOS, open Vault → New Item dropdown → Import from Files → Adopt SSH Keys. Preview the keys in ~/.ssh, choose a destination folder, and select keys. One vault approval stores and verifies each key before its local private key becomes an Authsia stub; SSH config annotations recognize equivalent symlinked key paths. Clear Replace originals after saving to store keys without changing local files. An existing SSH key in the destination folder is replaced only when you select Overwrite existing value, and its host restrictions are kept. See [Import from files](/docs/app/vault#import-from-files) for the full flow. ``` authsia ssh adopt --path ~/.ssh --dry-run authsia ssh adopt --path ~/.ssh --yes --folder Infra/SSH ``` ``` eval "$(authsia init zsh)" SSH_AUTH_SOCK="$HOME/.authsia/agent.sock" ssh-add -L ``` ## Scoped approvals Verified host-bound SSH authentication can be approved once or for the configured SSH session duration, locally or from an opted-in paired iPhone. Reusable grants bind the key, trusted destination, SSH user, and live caller. Review and revoke them in Access Center. `authsia lock` revokes matching SSH JIT grants for the current terminal or observed caller, in addition to clearing the legacy terminal approval-session status. ## Related topics - [Secure SSH & Git](/docs/get-started/secure-ssh) - [Vault](/docs/app/vault) - [Agent JIT approvals](/docs/cli/agent-jit) # /docs/cli/workspace.md # Workspace workflow Repo config stays commit-safe. Secrets live in the vault; each developer picks one local environment. Authsia resolves refs in the child process, not the parent shell. ### Preview Review env files before anything is written. ``` authsia workspace init --dry-run ``` ### Apply Store selected secrets and write refs. ``` authsia workspace init ``` ### Run Resolve at the Authsia boundary. ``` authsia workspace run -- npm test ``` Applying selected workspace secrets asks for one Workspace Secret Migration approval covering the selected items, destination folder, environment tags, and rollback backups. It grants no reusable CLI session. If approval is denied or storage fails, env files remain unchanged. The app's local preview and rules-only updates need no vault approval. ## Select one environment List Default, workspace tags, and env bindings, then select one. Named envs use exact-tagged and All items; Default stays inactive until you `use Default` or clear. ``` authsia workspace env list authsia workspace env use Production authsia workspace env use Default ``` Remove a stale binding with `authsia workspace env remove NAME authsia://...`. Removal works even when unrelated MCP configuration is invalid; it preserves vault items, other bindings, and MCP settings. Normal workspace operations still require valid configuration. ## Override one run Does not change the saved workspace environment. ``` authsia workspace run --environment Production -- npm test authsia workspace run --default-only -- npm test ``` ## Resolution order Searches upward for the nearest `.authsia/workspace.json`. Conflicts fail closed. Guarded shims reuse this order on every command after you change the active environment. ### Metadata without interrupting for approval `workspace env use`, `workspace env list`, `workspace env validate`, and secret-bearing `workspace run` planning stays metadata-only for configured CLI-enabled refs. At the secret boundary, direct-human runs batch every supported requested item into one approval before creating the normal terminal session. Secret values never appear in either view. ## Related topics - [Workspace Center](/docs/app/workspace) - [Guarded terminal](/docs/cli/guarded-terminal) - [Secure local development](/docs/get-started/secure-local-development) # /docs/get-started.md # 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. The parent shell keeps references only. Secrets resolve in the approved child. ## 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) # /docs/get-started/secure-agents.md # Secure AI agents Agents can read any file they can open. Keep `authsia://` refs in those files, and let Authsia resolve secrets only after you approve a scoped grant. Refs stay in the repo. Secrets move only after you grant scoped access. ## Non-negotiables - Do not run `get` / `read` in an agent context if that would print a secret. - Files agents inspect should contain refs, not plaintext. - Approved `exec` or `workspace run` puts the secret in the child only. - When access is missing, the agent must stop — not fall back to plaintext commands. ## Choose a path Use this When Guide Agent JIT The agent needs scoped `list` or `exec` for a folder and TTL you approve each time (or until expiry). [Agent JIT](/docs/cli/agent-jit) MCP tools The client should call Authsia through six fixed tools, with no secret-return tool. [Local MCP server](/docs/cli/mcp) MCP Manager A workspace-declared local STDIO or localhost HTTP MCP should run only after admission or secret JIT. [MCP Manager](/docs/cli/mcp-proxy) Automation credential A reusable, named credential for scripts — not the JIT grant path. [access create](/docs/cli/agent-jit) ## Launch from a workspace Workspace Agent launches, app menu launches, and hand-typed `claude`, `code`, `codex`, `cursor`, `devin-desktop`, or `devin` start the agent child without guard markers. Authsia restores the pre-guard PATH for that child while leaving the parent tab guarded. ``` authsia workspace agent --tool codex --goal "Fix checkout" --dry-run ``` Install setting-aware agent rules plus command-attribution and sub-agent-lineage hooks with `authsia agent init --agent codex`, then open `/hooks` in Codex to review and trust them. Workspace Setup offers the same Codex integration, shows both generated paths, and keeps any manual hook-merge steps visible until you dismiss them. Enable MCP Integrations in Settings > Developer Access before connecting a client. Client configuration cannot turn this on. ## Approve and revoke A grant covers the approved directory and its descendants, never siblings or symlink escapes. A grant at `$HOME` or `/` stays at that exact directory. Revoke from Access Center, a paired iPhone, or `authsia access revoke`. See [Access Center](/docs/app/access-center) and [Agent-safe workflows](/docs/app/agents). ## Related topics - [Local MCP server](/docs/cli/mcp) - [Agent JIT approvals](/docs/cli/agent-jit) - [Guarded terminal](/docs/cli/guarded-terminal) - [Security model](/security.html) # /docs/get-started/secure-local-development.md # Secure local development Keep credentials in the Authsia vault, commit `authsia://` refs, and resolve secrets only in the child that needs them. Pick one path. Do not export resolved secrets into the parent shell. ## Choose a path Use this When Guide workspace run One command or script should receive resolved env from the nearest workspace. [Workspace CLI](/docs/cli/workspace) authsia guard You want an interactive tab where npm, docker, aws, and similar tools resolve through shims. [Guarded terminal](/docs/cli/guarded-terminal) authsia exec You already exported `authsia://` refs in this shell, or you are selecting specific items. [Command reference](/docs/cli/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 - ### Init refs Scan env files, store selected secrets, write commit-safe refs. Preview with `--dry-run`. - ### Select one environment Named envs use exact-tagged and All items. Default stays inactive until you `use Default` or clear. - ### 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](/docs/app/workspace). ## Related topics - [Developer quickstart](/docs/get-started) - [Vault](/docs/app/vault) - [Workspace CLI](/docs/cli/workspace) - [Guarded terminal](/docs/cli/guarded-terminal) # /docs/get-started/secure-ssh.md # Secure SSH & Git Keep private keys in the vault. Git and SSH should sign through Authsia’s agent — not by exporting keys into the shell. Private keys stay in the vault. The agent signs; the shell never holds the key file. ## Adopt keys Preview, then import existing keys into a vault folder such as Infra/SSH. ``` authsia ssh adopt --path ~/.ssh --dry-run authsia ssh adopt --path ~/.ssh --yes --folder Infra/SSH ``` ## Point SSH at Authsia Enable shell integration and confirm the agent lists identities. ``` eval "$(authsia init zsh)" SSH_AUTH_SOCK="$HOME/.authsia/agent.sock" ssh-add -L ``` Headless signing uses a separate SSH-only credential. Shell integration and `authsia exec` obtain Bridge-issued, process- or terminal-bound leases without writing the bearer into the runtime grant file. ## Git Use the same agent for `git fetch`, `git push`, and SSH-based remotes. Do not copy private key files into agent-readable workspace paths. ## Approvals For direct host-bound SSH authentication, a session-based key offers Allow Once , Allow for the configured SSH duration , and Deny . The reusable approval is scoped to the key, trusted server host key, SSH username, and the live terminal, IDE, or coding-agent process. The Git operation shown in the prompt is context for the decision; it does not restrict repositories, branches, or server commands. Authsia only offers scoped or remote approval when the server key is already trusted for that host in your standard user or system `known_hosts` file. Unknown hosts, custom known-host files, host certificates, traditional non-host-bound authentication, and forwarded agents continue to use local per-key approval. The existing SSH Approval Session Duration setting controls local and paired-iPhone reusable approvals. Enable Approve SSH requests on paired iPhone under remote approval settings to opt in. Pairing by itself does not enable SSH approval. The Mac remains online, keeps the private key and passphrase, verifies the signed phone decision, and issues the grant. Access Center shows active and historical SSH approvals with their key, destination, caller identity, approval source, expiry, and use count. Revoke one there, or use Revoke all access to end every active SSH approval. `authsia lock` also revokes SSH JIT grants matching the current terminal or observed caller, while clearing the legacy terminal approval-session status. ## Automation Create a separate SSH automation credential when a script needs signing without an interactive session: ``` authsia access create --name codex-ssh --scope Team/API --ttl 15m --allow ssh ``` ## Related topics - [SSH signing CLI](/docs/cli/ssh) - [Vault](/docs/app/vault) - [Agent JIT approvals](/docs/cli/agent-jit) - [Security model](/security.html) # /docs/index.md # Secure developer workflows with Authsia Keep secrets in your Mac Keychain. Let terminals, Git, MCP, and coding agents request scoped access only when you approve. [Developer quickstart](/docs/get-started) [Use the app](/user-guide.html) [CLI overview](/cli.html) ## Get started Install once, then pick the surface you need: app, CLI, or a workflow guide. - [Developer quickstart](/docs/get-started): Install Authsia, add vault items, initialize a workspace, and run a command through the CLI. - [Use the Mac app](/user-guide.html): First run, vault folders, Workspace Center, Access Center, and agent-safe habits. - [Authsia CLI](/cli.html): Workspace env refs, guarded terminals, MCP, agent JIT, SSH signing, and audit. ## Develop locally Store secrets in the vault, commit references, and resolve them only in approved child processes. - [Secure local development](/docs/get-started/secure-local-development): Compare workspace run, guarded terminal, and exec so plaintext stays out of the parent shell. - [Workspace CLI](/docs/cli/workspace): Init commit-safe refs, select one environment, and run npm, tests, or scripts through Authsia. - [Guarded terminal](/docs/cli/guarded-terminal): PATH shims for npm, docker, aws, and kubectl. Humans get resolution; agents do not inherit secrets implicitly. - [Vault boundaries](/docs/app/vault): Folders and per-item CLI toggles decide what can ever leave the app. ## Secure agentic workflows Give coding agents scoped, time-boxed access without putting credentials in prompts, config files, or LLM context. - [Secure AI agents](/docs/get-started/secure-agents): Start here for Codex, Claude Code, Cursor, and other local agents. JIT grants, MCP tools, and workspace rules. - [Local MCP server](/docs/cli/mcp): Six fixed tools and no secret-return path. The client launches Authsia; approvals stay in Access Center. - [MCP Manager](/docs/cli/mcp-proxy): Use the local portal for existing STDIO protection and authenticated localhost Streamable HTTP. - [Agent JIT approvals](/docs/cli/agent-jit): Approve folder, capability, and TTL from Access Center or a paired iPhone, then revoke anytime. - [Access Center](/docs/app/access-center): Agent grants, human sessions, and investigation flags — without editing project files. ## Authenticate with SSH & Git Keep private keys in the vault. Git and SSH sign through the local Authsia agent. - [Secure SSH & Git](/docs/get-started/secure-ssh): Adopt keys, point SSH_AUTH_SOCK at Authsia, and sign without exporting private keys into the shell. - [SSH signing CLI](/docs/cli/ssh): Adopt existing keys, enable shell integration, and use a separate SSH-only credential for headless signing. ## Security and verification Offline-first by default. Confirm a release before you trust a download. - [Security model](/security.html): How CLI, agents, SSH, and Chrome autofill enter through local boundaries before human approval. - [Verify a release](/verify.html): Check DMG hash, signing, notarization, Gatekeeper, and the bundled CLI. - [AI-readable docs](/docs/ai-readable-docs): Point coding agents at llms.txt so they can search these guides without scraping HTML. # /security.md # Security that matches how developers actually work Secrets leak from env files, shell history, agent prompts, and long-lived SSH keys. Authsia keeps them in your Mac vault and only releases scoped access after you approve. ## Problems Authsia is built for ### Plaintext in repos `.env` values get committed, copied into tickets, or pasted into agent chats. ### Secret-filled shells Exported keys sit in parent shells, child tools, and accidental `env` dumps. ### Agents with too much Coding agents can read any file they can open unless access is gated. ### Keys without an owner SSH keys on disk and silent CLI access leave no clear who/when trail. ## Security model CLI, agent, SSH, and Chrome callers enter through authenticated local boundaries before Bridge policy and human approval authorize access. CLI and agent values go only to an approved child process. Chrome autofill uses its own browser session: the installed native host validates the page context and launches only the same-team bundled CLI before Bridge approval reaches the local Keychain. Standard app path: `/Applications/Authsia.app/Contents/Helpers/AuthsiaNativeHost`. ## How risk drops in practice ### Commit-safe workspace refs Stop shipping secrets in env files. Before: `API_KEY=sk-live-...`. With Authsia: `API_KEY=authsia://...`. ### Guarded terminal Keep plaintext out of the parent shell. Shims resolve into the tool child. See [Guarded terminal](/docs/cli/guarded-terminal). ### Agent JIT approvals - Agent requests scoped `exec` or list access. - You approve folder, capability, and TTL in Access Center — or from a paired iPhone. - Grant expires or you revoke it; audit keeps who asked without secret values. ### SSH signing in the vault Git and SSH sign through the Authsia agent. Private keys stay in the vault. See [Secure SSH & Git](/docs/get-started/secure-ssh). ## What stays local ### Keychain-backed vault Secrets and related metadata use Apple Keychain stores on your Mac. ### Item-level CLI toggles Keep highly sensitive items app-only even when CLI Access is on. ### Local audit, no secret dump Review who accessed what without exporting resolved secret values. ## Verify a release Official macOS builds use Apple Developer Team ID `33M8QU65SP`. Check DMG hash, signing, notarization, Gatekeeper, and bundled CLI in the [verify guide](/verify.html). ## Report a vulnerability Report privately to the maintainer. Do not open a public issue. Never include real secrets, seeds, private keys, or OTP codes. Include the app version, platform, a synthetic reproduction, and the expected authorization result. ## Related topics - [Agent JIT approvals](/docs/cli/agent-jit) - [Local MCP server](/docs/cli/mcp) - [Verify a release](/verify.html) # /user-guide.md # Use Authsia on your Mac App setup, vault boundaries, the workspace daily loop, Access Center, and agent-safe runs — without a wall of prose. [Get started](/docs/app/first-run) [CLI overview](/cli.html) ## Guides - [First run](/docs/app/first-run): Install once, launch once, add items, then enable only the CLI surface you need. - [Vault](/docs/app/vault): Folders and per-item CLI toggles are the main safety controls. Prefer authsia:// refs. - [Workspace Center](/docs/app/workspace): Create once from the app, then open terminal, guarded terminal, or agents from the same folder. - [Access Center](/docs/app/access-center): See who can use the vault, for how long, and revoke without editing project files. - [Agent-safe workflows](/docs/app/agents): Keep plaintext out of prompts, diffs, and terminal output agents can observe. ## Quick path - Install with Homebrew or the Mac disk image, then launch Authsia once. - Create folders that match later grants. Leave CLI off on app-only items. - Initialize a workspace from the app or `authsia workspace init`. - Approve agent requests in Access Center. Revoke when the task is done. ## Related topics - [Developer quickstart](/docs/get-started) - [CLI overview](/cli.html) - [Security model](/security.html)