Installing & Authenticating Agent Providers¶

SASE normally orchestrates an existing coding-agent CLI; the exception is the bundled fakey testing provider. You need at least one supported real provider CLI installed and authenticated for production work. This page collects the install command, the authentication command, and a link to each vendor's canonical documentation for every provider SASE currently supports. Claude Code, Codex CLI, OpenCode, Qwen Code, and Grok Build are npm packages (so installing them needs node and npm on your PATH; OpenCode's section also links its vendor installer), while the Antigravity CLI and Muse Code use their own install methods, shown in their sections below. SASE can install most providers for you with sase agent-cli install: every npm-packaged CLI installs via npm install -g <package>, and Muse Code installs from its provider-declared install script. The Antigravity CLI is the one built-in provider you install yourself.

sase doctor — specifically sase doctor -C llm.auth -v — is the authoritative readiness check. It prints the same per-provider install and auth hints documented here, so if this page and sase doctor ever disagree, trust the doctor output and open an issue. Vendor docs may list additional installer and account options; the snippets below intentionally match SASE's doctor hints.

Installed provider CLIs are also launchable interactively with sase tmux-agent (or t in Launch Control). Those windows are unmanaged agent CLIs, not SASE agents — they do not appear in sase agent list.

If Launch Control or sase doctor reports a provider as disabled, that is routing policy, not a missing install. A hard disable blocks SASE automatic routing and explicit %model requests for that provider until expiry or clearing; a soft disable only steers pools away from it. Usage-limit detection can hard-disable Claude for a week and Grok Build for 48 hours automatically. Interactive tmux Agent windows still launch a hard-disabled CLI. See Provider routing and Usage-Limit Auto-Disable.

Instruction delivery¶

The current bundle rollout records intended instructions for diagnostics. With the default instruction_shadow_render flag on, each root provider invocation renders its memory-built bundle and manifest into <artifacts>/instructions/ and exports SASE_INSTRUCTIONS_FILE for that call, then restores it. Current providers do not read that variable, so argv, prompts, and the files they already load stay the same. The manifest alone does not prove that a provider loaded the bundle's contents. This stage is called E2 in the implementation. See Instruction Bundles.

Verifying instruction delivery¶

sase instructions verify shows what each provider's SASE runs and native helpers actually loaded, read from the providers' own session records — never from anything SASE wrote. The default window is the newest 20 runs per provider from the last 7 days (-n, maximum 200, and --since change that). The command reports; it does not gate (exit 0 even when rows show bugs). A bad --since or --until value exits 2. See Instruction Bundles for the memory-built bundles behind these columns.

Column	Meaning
`manifest`	Observed sessions with a shadow manifest for the same provider (`k/N`; agy counts runs).
`contract`	Loaded sources carrying the `SASE Final Declaration` heading (`N×`, with the spread when mixed).
`home`	The current `~/AGENTS.md` first H1 was loaded.
`project`	The run workspace-root `AGENTS.md` first H1 was loaded.
`directive`	The provider's single-turn directive marker was present.
`native-SASE-full`	Natively loaded files that carry the contract.
`foreign`	Claude auto-memory, or Grok's memory flag as `k/N`.
`helpers`	Helper sessions by type, template presence, `sase final` attempts, and accepted declarations.

A session counts as covered when its run holds a manifest for the same execution provider rendered no later than the session start (5 s of skew allowed). sase instructions verify -c prints the per-provider-purpose coverage table: manifests, sessions, covered, up to 10 uncovered (agent, session) pairs, shadow-failure (.error.json) counts, and warm/cold render_ms p50/p95. With -a NAME, each observed root session also gets its intended-vs-observed section table: every included manifest section with the count of loaded sources whose text contains it, split into native and explicit channels (frame and heading-only sections are skipped; ◌ marks partial or unverifiable sessions such as agy).

Symbols: ✓ present, ✗ absent, ◌ unverifiable (agy reports every instruction column as ◌, with directive presence only when the conversation record exposes the prompt).

Channels are counted separately as native versus explicit: natively loaded files are Claude instructions attachments, the Codex # AGENTS.md instructions block, Muse rules_file records, and Grok agents_md_files; explicit channels are the Claude prompt_snapshot append text, the Codex developer message, the Grok <human_rules> block in system_prompt.txt, and prompt prefixes. sase doctor -D -C instructions runs the same scoreboard as a deep-only group (instructions.delivery WARNs on rows that break contract 1×, project ✓, directive ✓, or native-full ≤ 1; instructions.helpers WARNs on any accepted helper declaration; instructions.coverage WARNs on observed sessions without a shadow manifest or any shadow failure).

Root and helper agents¶

Only the root SASE agent — the provider turn SASE launched — submits the final declaration; native subagents and forked helpers return their result to their parent instead (decision helpers-return-roots-declare). Mechanical enforcement exists only where a provider exposes a helper channel. Everything else relies on that contract sentence. Limits by provider capability, not hidden:

Provider	Helper coverage
Claude	Helper template plus PreToolUse guard; live probes confirm forked (depth-2) helpers carry `agent_id`, so the guard covers forks. Kill switch: `sase flag disable claude_helper_channel`. Full surface list: Instruction Inventory.
Codex	Children inherit the process-level `developer_instructions`, so the sentence covers them; 0 spawns observed so far. No guard.
Grok	Subagents get nothing; sentence only, with the child channel deferred.
Muse, agy	No helper coverage.

Claude Code¶

Anthropic's Claude Code CLI (claude). This is SASE's highest-priority autodetect provider.

Install¶

npm install -g @anthropic-ai/claude-code

Authenticate¶

SASE doctor hint: run claude and complete the login flow.

Alternatively, Claude Code honors API-key / token variables such as ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, and CLAUDE_CODE_OAUTH_TOKEN — see the canonical docs for the full, current list.

Canonical docs: https://code.claude.com/docs

Native helpers¶

Native subagents inherit the root's environment, so SASE delivers a packaged helper template (# SASE Helper Instructions) plus a PreToolUse guard that denies their root-only operations (sase final …, turn-ending commands, root-only skills); forked helpers carry agent_id and are covered too. Kill switch: sase flag disable claude_helper_channel. Details: Claude Code Integration.

Codex CLI¶

OpenAI's Codex CLI (codex).

Install¶

npm install -g @openai/codex

Authenticate¶

SASE doctor hint: run codex login.

Alternatively, Codex honors OPENAI_API_KEY — see the canonical docs for details.

Canonical docs: https://developers.openai.com/codex/cli

OpenCode¶

The open-source OpenCode CLI (opencode).

Install¶

install from https://opencode.ai/docs

SASE can also install it from its npm package with sase agent-cli install opencode (npm install -g opencode-ai).

Authenticate¶

SASE doctor hint: run opencode auth login.

OpenCode can also read provider API keys from the environment (for example ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, ZHIPU_API_KEY, and other *_API_KEY variables) — its canonical docs list the current set.

Canonical docs: https://opencode.ai/docs

Qwen Code¶

Alibaba's Qwen Code CLI (qwen).

Install¶

npm install -g @qwen-code/qwen-code

Authenticate¶

SASE doctor hint: run qwen and complete the login flow.

Qwen Code can also use API-key access through variables such as DASHSCOPE_API_KEY, QWEN_API_KEY, or OPENROUTER_API_KEY — see the canonical docs for the current list.

Canonical docs: https://github.com/QwenLM/qwen-code

Muse Code¶

Meta's Muse Code CLI (muse). SASE never auto-detects it, because muse is a generic executable name. Select it with llm_provider.provider: muse, %model:muse/<model>, or SASE_MUSE_PATH. Model-alias routing is separate: whichever shipped size aliases currently include a Contributor member can select it whenever a muse executable is available — and the Contributor model trains on its inputs and outputs. See Muse Code Integration and the generated shipped size-alias defaults for how to opt out.

Install¶

sase agent-cli install muse

SASE downloads https://dev.meta.ai/install.sh itself over HTTPS, shows the URL, the SHA-256 digest of exactly what it downloaded, the exact shell-free command, and the target directory ($MUSE_INSTALL_DIR, default ~/.local/bin), and only then runs it after your confirmation. It passes MUSE_UPGRADE_MODE=1, which suppresses the installer's export PATH=... appends — SASE never edits your shell startup files. If the install directory is not on your PATH, SASE prints the exact export line to add yourself. Use -n/--dry-run to see the whole plan, digest included, without executing anything.

Authenticate¶

SASE doctor hint: run muse login, or set META_API_KEY.

Update¶

Muse is self-updating through its own launcher, so sase agent-cli update muse runs MUSE_SYNC_UPDATE=1 muse --version, which updates the launcher and the binary and then reports the resulting version. Latest versions come from Muse's channel endpoint rather than npm, and versions compare exactly rather than by PEP 440 — Muse's release ids (0.1.0-R708.1) are not PEP 440 versions, and a semver comparison would report "no known updates" forever.

SASE always launches agent runs with MUSE_NO_AUTO_UPDATE=1 so Muse cannot swap its own binary mid-run; update it through sase agent-cli instead.

Subscription usage¶

Muse collects subscription usage — its 5-hour session window and its weekly window — through a local probe against muse serve (Muse's MSP session host). The probe makes no model call and spends no tokens: it opens an ephemeral, shell-less host, starts a session on Muse's built-in echo provider, and reads the usage the host learns in response. It aborts without sending a turn if the host does not report an echo session with no model, so a future Muse that ignores the request can never cost a real model turn on a refresh tick.

The probe runs on the normal background cadence (llm_provider.usage_metrics.refresh_seconds, or active_refresh_seconds while Muse is in active use, never faster than Muse's 180-second polling floor), costs about three seconds of wall clock per refresh, and follows the same eligibility rules as every other provider: Muse must be resolvable and either referenced by a model alias or explicitly enabled. The user-facing switch is llm_provider.usage_metrics.providers.muse.enabled. Inspect the result with sase usage list -p muse. A host that has not yet reported any usage — for example a logged-out one — is shown as no observation rather than as 0% used.

Canonical docs: https://developer.meta.com/ai/resources/blog/build-with-muse-code/

Grok Build¶

xAI's Grok Build CLI (grok). Default provider autodetection never selects it, because the executable name collides with grok-dev (a stale community CLI that also uses ~/.grok/) and with Homebrew's deprecated, unrelated grok regex tool. Select the provider explicitly with llm_provider.provider: grok or %model:grok/<model> (see the generated Built-in Model Catalog for current names); use SASE_GROK_PATH when you also need to choose the executable. Model-alias routing is separate: whenever a grok executable is available, whichever shipped size aliases currently target Grok can select it (see the generated shipped size-alias defaults).

Routing availability checks only whether the executable exists; it does not verify that the binary is Grok Build. Run sase doctor before launching. Its bounded grok --version probe reports a distinct, actionable identity-mismatch finding; point SASE_GROK_PATH at the @xai-official/grok binary before continuing if that warning appears.

Install¶

npm install -g @xai-official/grok

@xai-official/grok is an npm trampoline: npm install -g places a shim on PATH, but the real Grok Build binary it downloads on first run lives under ~/.grok/bin/, not node_modules.

Authenticate¶

SASE doctor hint: run grok login (or grok login --device-code on a headless host), or set XAI_API_KEY.

Update¶

sase agent-cli update grok runs Grok Build's own self-update (grok update).

SASE always launches agent runs with --no-auto-update so Grok cannot swap its own binary mid-run; update it through sase agent-cli instead.

Execution posture¶

SASE runs Grok with --permission-mode bypassPermissions and no sandbox profile — the same posture SASE already uses for Codex and OpenCode. This is powerful local execution: Grok can read, write, and run shell commands anywhere the SASE process can, without per-action approval prompts.

Effort ceiling¶

Grok models accept only low, medium, high, and xhigh for --effort (see the generated Built-in Model Catalog for the current model names). %effort:none, %effort:minimal, and %effort:max raise a clean SASE error rather than a Grok process crash. The generated shipped size-alias defaults show the effort each alias target carries. A user-configured Codex target that pairs an alias-borne @max is best-effort: max is logged and skipped and the CLI runs at its own default effort instead of erroring.

Usage is best-effort¶

Grok's streaming-messages-json output is a projection of its own internal usage ledger. Subagent turns can set an internal "usage incomplete" flag that the projection drops silently, and an interrupted turn can under-count. Text and tool records are unaffected, and cost reporting (total_cost_usd) does work on the OAuth login path.

Instruction delivery¶

SASE runs Grok in untrusted workspaces with no --trust flag, so Grok loads no native instruction files (agents_md_files stays empty in the session's prompt_context.json). SASE generates no GROK.md shim. Instead, every Grok invocation passes --rules: the SASE single-turn directive (opening with SASE single-turn instructions for Grok:), followed by the project root AGENTS.md text exactly once in SASE-managed projects (the directive alone elsewhere). CLAUDE.md is never sent, so the content is delivered once, not twice. The home layer is not delivered; that arrives with the E3 bundle.

Rules payloads larger than 120 KiB fail fast with an actionable error instead of a silent exec failure (Linux rejects a single argv element above 128 KiB). To restore the no---rules argv while investigating a regression, run sase flag disable grok_rules_delivery on the execution host. That sunset kill switch is superseded once E3's delivery cutover lands.

Privacy¶

Prompts, workspace context, and tool results are sent to xAI. Non-enterprise Grok Build sessions are not zero-data-retention by default; review Grok Build's own privacy and telemetry controls (including /privacy, [telemetry] settings, and Zero Data Retention for enterprise accounts) before pointing SASE at Grok Build on a workspace with sensitive contents. See https://docs.x.ai/build/settings for the current controls. SASE does not set or manage any of these settings on your behalf.

Canonical docs: https://docs.x.ai/build/overview

Antigravity CLI¶

Google's Antigravity CLI (agy). There is no separate "Gemini CLI" provider in SASE; GEMINI.md exists only because Antigravity reads it for workspace context.

Install¶

curl -fsSL https://antigravity.google/cli/install.sh | bash

Authenticate¶

SASE doctor hint: run agy and complete the login/trust onboarding.

Alternatively, Antigravity honors GEMINI_API_KEY and GOOGLE_API_KEY — see the canonical docs for details.

Subscription usage¶

Antigravity collects subscription usage — its Gemini weekly and 5-hour windows plus the Claude/GPT weekly and 5-hour windows — through a local /usage probe. The probe makes no model call and spends no tokens: it runs agy -p /usage --output-format json --mode plan --sandbox --print-timeout 15s in print mode with stdin closed, which answers without starting an agent turn. It requires agy >= 1.1.11 (older builds would run /usage as a real paid turn, so the collector refuses them). A logged-out CLI prints Authentication required… to stderr and then blocks on an OAuth paste prompt; the collector watches stderr and returns logged-out promptly instead of waiting out the deadline. Its log file stays in the probe's managed temp dir rather than ~/.gemini/…, and auto-update is disabled for the probe spawn.

The probe runs on the normal background cadence (llm_provider.usage_metrics.refresh_seconds, or active_refresh_seconds while agy is in active use, never faster than its 120-second polling floor), costs about three to five seconds of wall clock per refresh, and follows the same eligibility rules as every other provider: agy must be resolvable and either referenced by a model alias or explicitly enabled. The Gemini buckets are model_family-scoped to gemini and the Claude/GPT buckets to 3p. The user-facing switch is llm_provider.usage_metrics.providers.agy.enabled. Inspect the result with sase usage list -p agy.

Canonical docs: https://antigravity.google/docs/cli-install

Fakey Testing Provider¶

The deterministic fakey CLI is bundled with SASE for launch, failure, retry, and UI testing. It requires no separate installation or authentication and is deliberately placed last in provider autodetection. It is also hidden from sase's TUI model picker and %model completion menu, so select it explicitly with a model such as %model:fakey-large or llm_provider.provider: fakey; do not use it for production coding work.

Because Fakey is bundled and internal, it is also absent from sase agent-cli inventories and the Admin Center's Updates tab Agent CLIs section. That management visibility is separate from routing and diagnostics: explicit fakey selection, the fakey console script, provider autodetection metadata, and sase doctor checks remain supported.

For demos and hermetic end-to-end tests, SASE_LLM_EXEC_PROVIDER=fakey dispatches through fakey while preserving the requested provider/model in display metadata. Run artifacts record the dispatched provider as exec_llm_provider.

See the fakey reference for scenarios and environment controls.

Verify¶

After installing and authenticating at least one provider, confirm SASE can find and use it:

sase doctor -C llm.auth -v

Expect the provider to report ready. sase doctor is read-only and does not call provider APIs, so it verifies that the CLI is on your PATH and that local auth evidence exists — it cannot confirm your token is still valid. If the check reports a missing executable or an authentication gap, re-run the relevant install/auth step above and check again.

If a provider CLI lives at a non-standard path, point SASE at it with the provider's SASE_<PROVIDER>_PATH override environment variable — SASE_CLAUDE_PATH, SASE_CODEX_PATH, SASE_OPENCODE_PATH, SASE_QWEN_PATH, SASE_AGY_PATH, SASE_MUSE_PATH, SASE_GROK_PATH, or SASE_FAKEY_PATH. sase doctor, routing availability, sase agent-cli, and tmux Agent honor every one of these. Agent runs honor them too, with one current exception: the Claude provider always launches claude from PATH, so keep a working claude on PATH even when SASE_CLAUDE_PATH is set. For deeper integration details (model mapping, per-provider environment variables, retry/fallback behavior), see the LLM provider reference.

Subscription Usage¶

Subscription usage is a machine-local view of included provider allowance windows — for example, the remaining share of a session or weekly plan window, which models share it, when that window resets, and when SASE last observed it. It is separate from per-agent token usage and from usage-limit auto-disable: a low observation does not itself disable routing.

Inspect the cache without provider I/O via sase usage / sase usage list. Use sase usage refresh to submit or join bounded durable probes; foreground mode waits and then renders the updated cache.

sase usage
sase usage list -p codex --verbose
sase usage refresh

sase's TUI exposes the same cache from Launch Control: press u, or choose Open Providers · Usage from the command palette. See Providers · Usage.

Observations are dated best-effort readings from each provider's own CLI, not guarantees of remaining capacity. Periodic collection runs on the scheduler's 60-second usage routine and probes inline, so it creates no proc rows; user-triggered refreshes still submit visible procs. Collection is on by default; opt out with llm_provider.usage_metrics.enabled: false, or per provider on a host that shares an account with another machine. See Subscription Usage.

Inventory and Updates¶

sase agent-cli is the inventory, install, and update surface for independently manageable provider CLIs on this machine. Internal or bundled providers can opt out when they are not separately installed or updated. A bare sase agent-cli means sase agent-cli list.

sase agent-cli list            # manageable provider CLIs, versions, and install methods
sase agent-cli list -v         # add resolved executable paths, docs URLs, and probe errors
sase agent-cli update codex    # update one CLI
sase agent-cli update -a -n    # preview every planned command without running anything
sase agent-cli install muse    # install a CLI from the install script its provider declares
sase agent-cli install muse -n # show the URL, digest, command, and target; execute nothing

list shows each CLI's resolved binary, installed version, latest known version, install method, and an ↑ marker when an update is available. A CLI that is not installed shows its install hint instead. The footer summarizes how many of the supported CLIs are installed and whether any updates are known. Latest versions come from the npm registry — or, for a channel-versioned CLI such as Muse Code, from the provider-declared JSON endpoint — and are cached: -o/--offline uses only the cache and never contacts the network, while -r/--refresh bypasses the cache. -j/--json emits a stable machine-readable envelope. Most CLIs compare versions with PEP 440 semantics; a provider whose release ids are not PEP 440 (Muse Code) declares exact comparison instead, so "different from what I have" is precisely "there is an update".

update takes CLI names (provider, binary, or display name) or -a/--all for every installed CLI; a bare sase agent-cli update with neither is a usage error. Commands run sequentially and without a shell. -n/--dry-run prints the exact command or skip reason for each CLI and changes nothing.

SASE only automates updates it can identify safely, and it never guesses an update command. sase agent-cli itself never runs sudo; when a manual step needs root, an agent must go through a human-reviewed sudo request instead:

Install method	Behavior
npm, writable global root	Runs `npm install -g <package>@latest`.
npm, non-writable global root	Skipped as manual, with the exact command to run under an npm setup owned by your user.
Self-managed with a self-update	Runs the provider's own declared update command, with any env overlay it declares.
Homebrew	Skipped as manual, with the `brew upgrade <package>` command to run.
Bundled visible provider	Skipped; update it with the package that ships that provider.
Not installed, or method unknown	Skipped, with the install hint or a note that SASE will not guess an update command.

Anything already at its latest known version is reported as an explicit already up to date skip rather than being reinstalled. Skips carry the provider's canonical docs URL where one is known.

install takes CLI names and installs each from the install script or npm package its provider declares. For a script CLI, SASE fetches the script itself over HTTPS into a 0o600 temp file with a timeout and a size cap, refuses non-HTTPS URLs and redirects off HTTPS, computes its SHA-256, and shows the URL, digest, byte count, env overlay, target directory, and the exact bash <tmpfile> command before running it — never curl | bash, and never through a shell. For an npm CLI, SASE checks that npm is on PATH and that the global root is writable (otherwise the CLI is skipped with the exact command to run under an npm setup owned by your user), then shows the package, the exact npm install -g <package> command, and the targeted global bin directory with its on-PATH status before running it — never with sudo. Running an installer always needs confirmation: pass -y/--yes or answer the interactive prompt. -n/--dry-run prints the plan, digest included, and executes nothing. An already-installed CLI is skipped unless you pass -f/--force, and a CLI whose provider declares neither a script nor an npm package is skipped with the manual command to run instead. After a successful install SASE re-probes the version, reports where the binary landed and whether that directory is on PATH, and prints the exact export line to add when it is not. SASE never edits your shell startup files.

Runs from sase agent-cli install and sase agent-cli update are journaled with the same bounded history used by sase's TUI, ,U, and ,E at ~/.sase/logs/agent_cli_updates.jsonl. Set SASE_AGENT_CLI_UPDATE_JOURNAL_MAX_BYTES to override that file's maximum size; runs where no command reaches a terminal outcome are not recorded.

This command manages the provider CLIs only. Use sase update to upgrade SASE itself and its plugins.

The same inventory is available inside sase's TUI, as the Agent CLIs section of the SASE Admin Center's Updates tab, which adds marked multi-select updates, inline installs for missing CLIs with * mark-all, and confirmation previews. See the Updates tab for that surface.