# /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.

## 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

### Agents and MCP

- `authsia agent init --agent codex` — install project rules plus command-attribution and sub-agent-lineage hooks; review them in Codex `/hooks`

- [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

### SSH and audit

- [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 decisions

On the MCP proxy tab, Access Center also lists recent proxy decisions that never created a grant — for example a denied or unavailable upstream. Those rows use the declared upstream name, honor the workspace filter, and sit in the same glass card treatment as grant rows. 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.

## 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.

The same active agent grant follows that agent session into descendant directories of the directory that was approved. Sibling trees and symlink escapes do not inherit it. A grant approved at `$HOME` or `/` stays at that exact directory and does not cover children.

### 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 automatically through an app-displayed code bound to a host-derived TTY and live shell; the pairing survives `cd`. A paired human’s direct `list` reuses the normal session only when the Bridge reports that pairing for the current caller; the Bridge does not open Agent JIT for that pairing. Agent evidence still routes to JIT. When the Bridge already requires a list grant, the CLI still runs list JIT preflight even if it does not recognize the agent by name.

### Post-exit file inspection

After an Agent JIT grant authorizes a secret-bearing `exec` or `workspace run`, Authsia inspects bounded observed files and automatically replaces eligible exact injected values plus supported one-layer Base64, URL-safe Base64, hexadecimal, percent/form, shell, HTML, and JSON representations. Each matched representation becomes ` `; surrounding content is preserved and encoded payloads are intentionally invalidated rather than left recoverable. Binary, non-UTF-8, oversized, and symbolic-link writes are skipped quietly. Recursive decoding and archive expansion remain outside this boundary. Ordinary human CLI sessions and reusable automation credentials do not start file observation or cleanup. A healthy event watcher inspects only event-reported file paths and ignores generated trees such as `build` and `node_modules`; bounded fallback discovery runs only when the watcher cannot start. Agent-granted cleanup has no flag or opt-out. Rewriting is descriptor-hardened but not crash-atomic, and no inspection or cleanup warning changes the child’s exit status.

For confirmed secret-bearing Agent JIT runs, Authsia also records best-effort outbound TCP and connected UDP endpoint metadata for the launched child and verified descendants. Access Center shows it under Activity → Network with explicit Observed, Partial, or Unavailable coverage. This is bounded investigation evidence — not traffic blocking or inspection — and never stores payloads, URLs, headers, DNS payloads, or secret values.

## 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 boundary at launch

Workspace Agent launches, app menu launches, printed commands, goal handoffs, and hand-typed `claude`, `code`, `codex`, `cursor`, `devin-desktop`, or `devin` start the agent child without guard markers. Authsia restores the pre-guard `PATH` and removes every stale `authsia-guard-*` entry while leaving the parent tab guarded. Shells owned by the launched agent skip Auto-guard; ordinary IDE terminals remain guarded.

```
authsia guard
```

Run `authsia setup --repair` once and open a new terminal first.

```
authsia status --verbose
```

The `Guarded Terminal` line reports `Active` with the shim count, `Stale` when guard metadata and `PATH` disagree, or `Inactive (agent session)` inside a launched agent. `--verbose` lists shimmed tool names, with agent launchers (`claude`, `codex`, …) called out separately from mediated tools since they start unguarded rather than 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.

## 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 existing STDIO proxy or the app-owned localhost Streamable HTTP manager. Credentials stay behind native admission and Keychain references.

## What it gates

Declare a no-shell stdio command or a validated loopback HTTP URL, optional `authsia://` references, and optional tool allow/approve/deny names 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.

- A credentialed server uses secret JIT.

- An empty-policy, credential-less catalog requires local admission before its short discovery probe. Automatic discovery runs only with an entirely empty declared environment.

- Local admission defaults to 30 minutes, has a company-manageable maximum, expires absolutely, and can be renewed only through a fresh client-originated approval.

- Pinned catalogs list from policy without launching the child.

- Remote HTTP, HTTPS, SSE, and URL MCP remain on the company gateway. Direct client launches that skip Authsia are existence-only findings, not a gated path.

Enable MCP Integrations in Settings > Developer Access first. Client configuration cannot turn this on.

## Allowlist Authsia in managed agent settings

Deploy two things: an administrator-enforced policy that restricts MCP launches, and client configuration that connects through Authsia. Copying a user configuration file alone does not enforce company policy. This guide covers the five clients supported by `authsia mcp configure` on macOS. Vendor policy documentation checked September 8, 2026; validate the deployed client version before rollout.

Install the signed Authsia app at a company-controlled path and enable **MCP Integrations** in **Settings > Developer Access**. The examples assume `/Applications/Authsia.app/Contents/Helpers/authsia`; replace it everywhere if your fleet uses another path. Declare each upstream and its tool/secret policy in the target workspace's `.authsia/workspace.json`.

The standard client launch uses `mcp proxy` with `AUTHSIA_MCP_UPSTREAM` naming the declaration. Keep `--upstream` and fixed workspace arguments out of these shared launches. The child command stays in Authsia workspace policy. Allow `mcp serve` too when exposing Authsia's own MCP tools. These launch policies do not approve an upstream or replace native admission.

### Claude Code

Deploy this JSON through managed settings, for example MDM installing `/Library/Application Support/ClaudeCode/managed-settings.json`:

```
{
  "allowManagedMcpServersOnly": true,
  "allowedMcpServers": [
    { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "serve"] },
    { "serverCommand": ["/Applications/Authsia.app/Contents/Helpers/authsia", "mcp", "proxy"] }
  ]
}
```

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 intends to own a fixed server catalog: it prevents users from adding new wrapped entries. See [Claude Code managed MCP controls](https://code.claude.com/docs/en/managed-mcp) and [managed 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`:

```
[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" },
] }
```

Both the configured server name and identity must match. Replace `jira` with the generated name and repeat its block for each additional proxy entry. A two-entry policy does not cover arbitrary future names. Structured matchers check executable, argument count, and order; string-only `identity.command` does not restrict arguments. Neither checks environment or working directory. See [Codex configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference).

Requirements restrict availability; they do not install connections. Put generated launches in `~/.codex/config.toml`. Managed defaults alone are insufficient enforcement. Review plugin-bundled MCP separately through `plugins.<plugin>.mcp_servers`; for a rollout using only direct configuration, `features.plugins = false` in requirements disables plugins. See [Codex managed configuration](https://learn.chatgpt.com/docs/enterprise/managed-configuration).

### Cursor Enterprise

In the team dashboard's **MCP Configuration**, add these two command entries:

```
/Applications/Authsia.app/Contents/Helpers/authsia mcp serve
/Applications/Authsia.app/Contents/Helpers/authsia mcp proxy
```

Cursor matches the full command plus arguments. Use the exact deployed path rather than a broad wildcard. Disable permission for user MCPs outside admin-defined command/URL patterns when requiring Authsia-only launches. Set per-server tool and network controls for your upstreams, and pilot native Bridge connectivity under the selected sandbox mode. The allowlist does not install servers: distribute generated entries to `~/.cursor/mcp.json` or the project `.cursor/mcp.json`. See [Cursor enterprise MCP controls](https://prod.cursor.com/docs/enterprise/model-and-integration-management) and [user MCP extensions](https://prod.cursor.com/docs/mcp).

`permissions.json` / `mcpAllowlist` controls tool auto-run approval; it is not a substitute for the enterprise server launch policy. See [Cursor permissions reference](https://prod.cursor.com/docs/reference/permissions).

### VS Code with GitHub Copilot

For VS Code 1.132 or later, deploy the Claude-shaped JSON above through **Copilot managed settings**: `allowedMcpServers` with the two exact `serverCommand` entries and `allowManagedMcpServersOnly: true`. Alternatively, deliver equivalent values through VS Code enterprise policies `ChatAllowedMcpServers` and `ChatAllowManagedMcpServersOnly`. Do not paste these policy names into ordinary workspace settings.

Individual allow/deny policies require 1.130; managed-only enforcement requires 1.132. Copilot managed allowlists replace the equivalent device policy, so keep delivery channels consistent. Leave `ChatMCP` at `all` for this manually configured pattern; `none` disables MCP, while `registry` requires a separate approved-registry deployment. Distribute connections into the user-profile `mcp.json` or project `.vscode/mcp.json`, using Authsia's VS Code output with its `servers` map. Verify applied policy with **Developer: Policy Diagnostics**. See [VS Code enterprise AI settings](https://code.visualstudio.com/docs/enterprise/ai-settings).

### Devin Desktop

Authsia generates local connections for `~/.config/devin/mcp_config.json` with `authsia mcp configure --client devin`. Distribute that configuration and check it for drift. We have not verified a documented Devin Desktop administrator-enforced command allowlist equivalent to the controls above. Treat this as configuration distribution and detection, not proven prevention of direct launches. Confirm enforcement options with your vendor before using Devin Desktop for a mandatory Authsia-only deployment; cloud Devin MCP settings do not establish local Desktop enforcement.

### Distribute connections and verify the rollout

From each declared workspace, print the matching client configuration:

```
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
```

Use only the output for the installed client. This prints configuration; it does not deploy company policy. Claude uses `~/.claude.json`, Codex and Cursor use the paths above, Devin uses its local config, and VS Code uses its profile's `mcp.json`. Merge entries rather than replacing unrelated settings. A typical Claude/Cursor proxy connection looks like this; `jira` must already be declared in that workspace:

```
{
  "mcpServers": {
    "jira": {
      "command": "/Applications/Authsia.app/Contents/Helpers/authsia",
      "args": ["mcp", "proxy"],
      "env": { "AUTHSIA_MCP_UPSTREAM": "jira" }
    }
  }
}
```

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.

These examples permit STDIO connections only. For Authsia's protected localhost HTTP flow, separately approve the exact enrolled `http://127.0.0.1:8788/mcp/{server-id}` URL using the client's URL policy, and retain Manager-issued authentication. Do not allow the original upstream URL or every loopback endpoint. Remote MCP remains a separate company-gateway decision. Authsia gates traffic routed through it; client MCP policy does not enforce OS-wide process restrictions or make editable workspace declarations centrally immutable.

## 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

Wrap and Protect previews keep child env keys and replace every value. A scanned entry that already set child environment is not followed by automatic catalog recording — name tools under `mcpUpstreams.tools.allow` instead.

```
authsia mcp wrap --write --server jira
```

Remove protection previews the protected and restored entries plus their checksum before writing. It restores only from that row’s exact workspace declaration and leaves workspace policy in place. Client-side environment values from before protection cannot be recovered, and declared environment values — including `authsia://` references — are not copied into the direct launch. Reopen the client after restoring it.

```
authsia mcp unwrap --write --server jira
authsia mcp unwrap --write --server jira --yes
```

## Catalog without starting the child

Record what a declared local MCP server advertises so clients can list its tools without launching it.

```
authsia mcp catalog --server codegraph --write
```

```
authsia mcp doctor
authsia mcp doctor --json --home /tmp/fleet-home
```

`mcp doctor` prints a table of scanned launches plus a verdict. It exits 2 on an effective or conditional bypass. JSON is schema version 2 and includes host, user, Authsia version, MCP Integrations, and audit integrity. Unreadable or oversized client files are skipped and do not fail.

```
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
```

Run `authsia mcp start` from the signed Authsia app with MCP Integrations enabled. The portal binds to `127.0.0.1:8787`. Protected local Streamable HTTP uses `127.0.0.1:8788/mcp/{server-id}`. Stopping the manager ends HTTP forwarding and portal sessions; it leaves existing STDIO proxy processes and independently running HTTP servers running.

Discover servers scans supported client configs without starting them. Configure in Authsia prepares a declaration; Protect a client and HTTP enrollment write client config only after native confirmation. HTTP enrollment is limited to user-local Claude Code, Codex, and Cursor files; a conflicting project entry blocks enrollment.

```
authsia mcp declare --server internal --url http://127.0.0.1:9000/mcp --allow search --approve create --deny delete --yes
```

Only explicit loopback HTTP endpoints are accepted (`http` plus `localhost`, `127.0.0.1`, or `::1`, and an explicit port). The first HTTP declaration advances that workspace to schema version 3, which older software rejects. Optional upstream headers remain Keychain references and are resolved after admission. Activity contains server, tool, attribution, and coarse outcome without raw protocol data 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

Grant revocation terminates the process group. On the MCP proxy tab, Access Center also lists recent proxy decisions that never created a grant — for example a denied or unavailable upstream. Those rows use the declared upstream name, honor the workspace filter, and sit in the same glass card treatment as grant rows. They are rejected before Authsia creates a grant.

## 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.

MCP integrations are off by default. Enable MCP Integrations in Settings > Developer Access before connecting a client. Client configuration cannot enable this app-level control.

## Use a user-global client entry

Print the user-global fallback for the exact installed Authsia binary, then add the printed entries in your client’s MCP settings. From a managed workspace, declared upstreams appear as separate proxy entries; otherwise the output stays serve-only. The read-only report groups existing user-global and project entries by workspace and labels the exact path, scope, and effective, overridden, or conditional precedence. Project-scoped Claude, Cursor, and VS Code entries outrank matching user-global entries, and declarations never cross repository roots. Replace `vscode` with `codex`, `claude`, `cursor`, or `devin` as needed. The command never embeds credentials or fixes a repository path.

```
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.

```
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
```

## 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.

### 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
```

## 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
```

## 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.

### 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.

## 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.

## 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.

## 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.

## 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.

## 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.

## 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 on GitHub. Never include real secrets, seeds, private keys, or OTP codes. Read [SECURITY.md](https://github.com/james-liang-cs/authsia/blob/main/SECURITY.md) and the public [TRUST.md](https://github.com/james-liang-cs/authsia/blob/main/TRUST.md) map.

## 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)