Language / 语言: English · 中文

Build with agents in the terminal. Extend the same host through reviewed, versioned packages.

Quick start · Cognitive packages · A3S Code · Components · Readiness · Development

a3s is the umbrella command for the A3S developer platform. A base install contains A3S Code. Other native products and A3S Use capabilities keep their own release and lifecycle boundaries.

a3s
├── code        interactive or non-interactive coding agent
├── plugin      reviewed cognitive-package lifecycle (gated preview)
├── use         Browser, Office, OCR, and installed Use capabilities
├── compose     multi-service applications delegated to A3S Box
└── components  install · upgrade · inspect · repair · uninstall

The release source has regression coverage for the boundaries that matter to the package host:

These tests support the preview claim. They do not replace the release gates in Release readiness.

The product entry is the a3s binary. Interactive Code is a3s code, not a separate a3s-code install. Pick one channel and keep updates on that channel.

# macOS or glibc Linux (x86_64 / aarch64) — official installer
curl --proto '=https' --tlsv1.2 -fsSL \
  https://raw.githubusercontent.com/A3S-Lab/CLI/main/install.sh \
  | A3S_MODIFY_PATH=1 sh

# Windows x64 — PowerShell 5.1 or newer
$env:A3S_MODIFY_PATH = '1'
irm https://raw.githubusercontent.com/A3S-Lab/CLI/main/install.ps1 | iex

# macOS or Linux with Homebrew (preferred package-manager path)
brew tap a3s-lab/tap https://github.com/A3S-Lab/homebrew-tap
brew install a3s
# Equivalent: brew install a3s-lab/tap/a3s

# Any host with a Rust toolchain (CLI crate only; companions may be incomplete)
cargo install a3s --locked

Do not run brew install a3s-code for the umbrella CLI. That formula is the legacy standalone a3s-code binary and does not provide a3s.

The installers compare the two official release repositories during the current migration, select the newer stable SemVer, verify the GitHub-published SHA-256, reject unsafe archive members, validate a3s --version, and activate the binary, bundled target-specific Moli runtime, and a3s-webview companion as one recoverable operation. They never use sudo or UAC. Omit A3S_MODIFY_PATH=1 to leave shell profiles and the user PATH unchanged. Homebrew installs the same companions from the CLI archive, so a separate a3s-webview formula is not required.

Default locations: ~/.local/bin (Unix installer), Homebrew bin/ (brew), %LOCALAPPDATA%\Programs\a3s\bin (Windows). Overrides: A3S_VERSION, A3S_INSTALL_DIR, A3S_GITHUB_TOKEN.

Supported release targets today: macOS 12+ (aarch64 / x86_64), glibc Linux (x86_64 / aarch64), Windows x64. Not shipped: musl/Alpine, Windows ARM, Mingw, Cygwin.

Intel macOS 12 is supported by the standalone installer above. The native macOS sandbox uses the operating system's built-in Seatbelt boundary and does not require Node.js or an npm runtime.

# Standalone macOS / Linux installer channel
a3s self update

# Homebrew
brew update && brew upgrade a3s

# Cargo
cargo install a3s --locked

# Windows — re-run the installer (in-place self-update is not supported)
irm https://raw.githubusercontent.com/A3S-Lab/CLI/main/install.ps1 | iex

# Homebrew
brew uninstall a3s

# Standalone Unix installer (no uninstaller script)
rm -f ~/.local/bin/a3s ~/.local/bin/a3s-webview
rm -rf ~/.local/bin/moli
# Remove any PATH line added when A3S_MODIFY_PATH=1 was used.

# Cargo
cargo uninstall a3s

# Windows installer channel
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Programs\a3s"
# Remove that directory from the user PATH if it was added.

Uninstalling the binary does not delete ~/.a3s/ (or the Windows equivalent).

a3s --version
a3s code

The first a3s code launch creates ~/.a3s/config.acl when no configuration exists. Inspect the selected ACL configuration with:

a3s config path
a3s config show
a3s config validate

A3S 0.14.0 contains the gated cognitive-package host. Prepare and inspect A3S Use explicitly when first-use installation is not appropriate:

a3s install use --source release
a3s use doctor --json
a3s use capabilities --json

--offline and A3S_NO_AUTO_INSTALL=1 are strict no-download boundaries. Monorepo-level install docs live in the a3s README Installation section.

A cognitive package is an npm-like, SemVer distribution unit owned by A3S Use. It has a stable <publisher>/<name> identity, an ACL manifest, a required README, optional package dependencies, and any combination of six surface contracts:

acme-research/
├── a3s-use-extension.acl   identity · version · dependencies · surfaces
├── README.md               required package documentation
├── tools/                  executable Tasks or long-lived Services
├── releases/               content-bound Tool and MCP descriptors
├── flows/                  A3S Flow TypeScript workflow sources
├── skills/                 SKILL.md files and supporting content
├── ui/                     integrity-bound static assets
└── okf/                    Open Knowledge Format bundles

The complete package generation—not an individual file—is the install, upgrade, enable, disable, and uninstall unit. Dependencies install before dependents, unused dependencies uninstall in reverse order, and one successful cutover publishes one new capability generation.

The package format accepts all six surfaces. The current Code host does not pretend that every execution adapter is ready:

Required surfaces fail closed when their adapter or evidence is unavailable; they never silently downgrade to a different provider.

The resident CLI contributes verified managed MCP servers, Skills, provider-qualified Runtime Tool Tasks, digest-bound Knowledge Surface readiness, dependency-closed local Flows, and path-free UI bindings through one Core atomic catalog cut. UI and Flow dependencies consume canonical Use surface IDs and require the versioned Use completeness marker, including for an empty dependency set; the host never reparses package ACL or infers authority from static assets. A Tool- or MCP-dependent UI/Flow and an OKF-dependent Flow resolve only against a value from the same exact package generation. Built-in Browser/OCR MCP wrappers and use_knowledge_search retain typed compatibility owners after that atomic publication; queryability is not inferred from Knowledge Surface readiness. Any missing dependency fails the candidate batch without advancing the current catalog. OCR is the one non-leased host-built-in overlay while its ONNX Runtime ABI differs from the optional local embedding ABI; its verified Skill still publishes through the atomic catalog.

With an explicitly trusted Registry configured, metadata can be searched without downloading package archives. Mutations create an immutable plan before they change the active generation:

a3s plugin search research
a3s plugin inspect acme/research

# Interactive review and apply
a3s plugin install acme/research --channel stable
a3s plugin upgrade acme/research
a3s plugin disable acme/research
a3s plugin enable acme/research
a3s plugin uninstall acme/research

# Non-interactive two-step apply
a3s --output json plugin disable acme/research --dry-run
a3s --output json plugin apply <operationId> \
  --plan-digest <planDigest> \
  --yes

CLI, /packages, and the management MCP are presentation adapters over one A3S Use PluginManagerService. Search, inspection, installed state, immutable planning, durable apply, and replay therefore expose the same Use-owned typed contracts and the canonical user/current scope. The standard MCP publishes the exact ten-tool manager-v4 inventory; its apply tool remains fail-closed because an MCP request is never treated as trusted user confirmation. Interactive CLI and TUI review additionally share one deterministic read-only projection of the exact immutable envelope. It names the plan identity and digest, candidate/prior package graph, selected Registry or retained installed source, every transition and complete permission ceiling, provider and Workspace impact evidence, and the exact confirmation boundary. Standard machine JSON responses remain unchanged.

Every lifecycle mutation requires the current catalog-v3 evidence and a complete cognitive-package lock. The shared service persists a PluginHostPlanResult before mutation and accepts only its operation ID, planDigest, and exact confirmation at apply. Code injects Registry access, ACL policy, lifecycle/Runtime/UI composition, and the confirmation boundary; Use alone owns package resolution, plan persistence, mutation, and replay. Package content cannot select a Runtime provider or prebind host authority.

For a locked graph, A3S Use derives the candidate lifecycle generations and Grant/provider evidence, the host evaluates policy over that complete plan, and Use regenerates the evidence with the final authority. Planning rejects provider identity/build, capability, workload semantics, enforcement, authority, scope, or revision drift. The v3 operation record persists the canonical Registry source revision, planning bundles, exact Grant snapshot, and complete reviewed provider evidence alongside the plan and confirmation.

Reviewed enablement uses its own schema-v2 durable plan record. It stores the installed signed planning bundle, exact Grant snapshot, and package-to-provider generations—not process-local Runtime clients. Apply reconnects the configured providers and must reproduce the reviewed evidence. Disable carries an empty candidate selection and lets A3S Use retire from the exact binding receipt; re-enable reconstructs activation from the retained bundle. This remains valid after manager restart and does not refetch Registry targets.

At apply, Plugin Manager reconstructs only the Registry identities frozen in the lock, re-derives the Grants, lifecycle generations, host assignments, and Runtime selection from current evidence, and requires an exact match with the reviewed provider record before it creates the lifecycle factory or downloads the package archive. It then invokes A3S Use in-process with ReviewedCognitivePackageAuthorizationProvider. Use must reproduce the same operation ID, plan digest, package transitions, impact, state revision, lock, Grants, and provider evidence before it may mutate. Missing evidence, an older schema, or an unlocked plan is rejected during planning; apply has no subprocess mutation fallback.

The Grant snapshot is bound to the plan's exact canonical user/current scope and durable state revision. Scope, revision, prebound impact/provider evidence, or final authority drift fails before apply. A signed OCI Tool Task regression proves that missing assignment and changed provider build fail before archive or lifecycle mutation, while restoring the reviewed build persists the exact Grant receipt without launching a child mutation and replays idempotently. Upgrade binds both the exact installed and candidate locks; upgrade and uninstall retain dependencies still owned by another installed root graph.

Managed Workspace enable and disable now use an explicit two-step protocol. The host persists PluginHostEnablementPlanRequest and its exact plan-v4 or terminal NoChange result, then accepts only the existing digest-bound PluginHostApplyRequest. A confirmed apply reconstructs ReviewedCognitivePackageAuthorizationProvider, and A3S Use reproduces the same plan before its enablement and Grant saga may mutate. Permission-bearing packages therefore use the same prepare, cutover, drain, retirement, and crash recovery path as their reviewed graph lifecycle. Package bytes and the dependency graph do not change.

Local CLI and TUI schema-v3 enable/disable use the same reviewed two-step contract. Planning persists the complete User-scoped Use envelope and returns either planned with an operation ID and canonical digest or terminal no-change without synthetic mutation identity. Apply revalidates policy, lifetime, digest, and exact confirmation before durable intent, then resumes or replays only the recorded saga after intent. a3s plugin apply accepts these enablement plans as well as install, upgrade, and uninstall plans.

In Code TUI, /packages is available only while the agent is idle. It pages the same typed installed-package state as CLI/MCP and shows Use-owned desired and observed values separately. Enter creates a plan without mutating; the review shows the complete operation ID, canonical digest, expected package generation, expiry, package graph, source, transition, permission, provider, impact, state, and confirmation evidence before Enter/y can apply that exact identity. Up and Down scroll the complete review; Esc/n cancels, an identity-free NoChange refreshes without apply, and the panel remains locked while a confirmed apply is in flight. /plugin remains a separate local Claude/Codex Skill switch and does not manage A3S Use packages.

Code TUI observes one capability watcher per process:

verified install   → generation N+1 → ready surfaces appear
reviewed disable   → generation N+2 → callable surfaces withdraw and drain
reviewed enable    → generation N+3 → exact installed surfaces return
verified upgrade   → generation N+4 → old evidence is replaced atomically
verified uninstall → generation N+5 → package surfaces withdraw and drain

An installed OKF surface is indexed as immutable, non-executable content; Code does not paste the package into the system prompt. A promoted projection binds the exact User or Workspace scope, package and surface identity, lifecycle generation, package and bundle digests, projection receipt, and index digest. Only one generation of a surface may be active in a scope.

When at least one projection is active, current and newly attached TUI sessions receive the read-only use_knowledge_search tool. Disable or uninstall removes the tool when no managed Knowledge remains. A query snapshots the live Registry generation, deduplicates its projections into exact package, manifest, and lifecycle-generation identities, and acquires every corresponding published Registry lease before SQLite access. Those leases remain held through backend search and final Registry revision verification, so a query accepted before cutover participates in lifecycle drain and blocks prior-generation retirement until it finishes. Missing leases and conflicting projection digests fail closed. A racing cutover is retried once against the replacement revision; stale results are never returned as current context. Every hit carries its exact concept path, source digest, package generation, projection receipt, and index digest.

The composed adapter inherits the Use default storage policy for every complete User or Workspace scope: 512 MiB of receipt-accounted expanded content, 256 retained projections, 32 generations per surface, and 256 removal tombstones. Staging checks the whole scope atomically; receipt-owned removal frees quota, prunes tombstones, vacuums SQLite, and truncates its WAL. Operators can inspect non-secret allocation evidence through a3s use knowledge usage --json; an exact Workspace query also requires --scope-kind workspace --scope-id <id>.

Use also exposes scope-bound operator commands through the same transparent a3s use proxy:

a3s use knowledge audit --json
a3s use knowledge backup ./workspace.a3s-okf-backup \
  --scope-kind workspace --scope-id workspace/acme --json
a3s use knowledge verify-backup ./workspace.a3s-okf-backup \
  --scope-kind workspace --scope-id workspace/acme --json
a3s use knowledge repair-search-index --yes \
  --scope-kind workspace --scope-id workspace/acme --json

Audit verifies SQLite, foreign keys, receipts, accounting, scope identity, and FTS integrity. Repair only rebuilds the derived FTS rows after authoritative state passes validation. Backup is non-overwriting and its bounded manifest and database digest can be verified offline, but it is neither a Registry signature nor a whole-product recovery artifact. Coordinated restore is not implemented; copying a snapshot into live state is unsupported.

Registry URL and trust identity belong to host configuration, never to an untrusted package. A mirror or private source can be added, disabled, or replaced without changing resolver code:

a3s registry add packages https://packages.example.org/a3s/ \
  --root-sha256 <root-sha256> \
  --trusted-root ./root.json \
  --yes
a3s registry refresh packages
a3s registry list # copy the current revision before each mutation
a3s registry disable packages --revision <current-revision> --yes
a3s registry replace packages https://mirror.example.org/a3s/ \
  --root-sha256 <mirror-root-sha256> \
  --trusted-root ./mirror-root.json \
  --revision <current-revision> \
  --yes
a3s registry enable packages --revision <current-revision> --yes

state/use/registries.acl is the only Registry source document used by CLI, TUI, plan, and apply. Every mutation uses revision CAS. Install may select an enabled source with --registry-name; upgrade and uninstall remain pinned to installed provenance. Installed receipts remain pinned to the Registry identity that supplied them. Replacing a source does not rewrite those receipts; an upgrade fails closed until provenance is restored or explicitly migrated. The official production Registry root is not yet public, so these commands currently require a source the operator deliberately trusts.

The resident watcher uses the typed A3S Use capability Registry as its lease authority. The Use CLI response envelope remains schema v1 and its serialized Registry remains schema v2 for status, diagnostics, MCP serving, non-resident commands, and the OCR compatibility overlay. Code validates both forms and rejects an older Registry instead of confusing transport compatibility with capability compatibility.

Code configuration and plugin authorization are intentionally separate. The workspace ACL may configure the agent, while only an explicit operator config or the user-level config may authorize plugin operations. TUI and the management MCP retain that distinction end to end.

flow.json is a hermetic design-envelope fixture for exact installed-Flow identity checks. Production Code does not author or deploy Flows through a resident /flow surface: FullCompatibility stages package-owned Flows into Core FlowBinding values via projection_adapter / preflight only. Non-resident a3s code flow run is not wired. See A3S Use Component Platform.

a3s code is an agentic developer workspace, not only a chat prompt. It keeps conversation, tool execution, approvals, workspace changes, memory, and verification evidence in one semantic transcript.

Everyday commands:

a3s code
a3s code resume
a3s code exec --mode auto "Fix the focused test and verify it"
a3s code exec --mode plan --tool-policy read-only "Review this workspace"
a3s code exec --web-search enabled "Compare the current published guidance"
a3s code exec --mode auto --tool-policy local-workspace --model provider/model "Fix this offline task"
a3s code exec --image before.png,after.png "Compare these screenshots"
a3s code research --web "compare Tokio and async-std"
a3s code sandbox status
a3s code sandbox setup  # Probes the native platform boundary
a3s code schedule enable daily-triage --every 1d
a3s code schedule notifications
a3s code remote diff <execution-id> --organization <organization-id>
a3s top --json

Each a3s code exec run auto-saves its transcript in the same workspace-scoped session store used by a3s code, a3s code resume, and a3s code session.

Ordinary a3s code exec performs read-only discovery of an already-ready A3S Use installation. If found, Code atomically publishes its verified managed-MCP/Skill/Runtime-Task/UI generation and stops the short-lived watcher before the first Run. If Use is missing, the command keeps the no-Use path and does not contact the component release service. A3S Desktop uses a reserved required host mode: it negotiates that exact capability before launch and rejects a successful result unless capabilityRuntime proves the frozen Code catalog, exact Use snapshot cursor, surface counts, and Runtime Task catalog digest. One trusted process-owned Plugin Manager serves both reviewed Task dispatch and opaque HTTP MCP route resolution until after the Session closes. The scoped cut does not start built-in MCP, compatibility Knowledge, Flow, or Plugin Manager presentation projection.

See Code editor and CI integrations for extension installation, Action usage, exact permission profiles, and the deliberately closed automation boundary.

Semantic workspace retrieval is disabled by default. Configure it only in the user ACL or a deliberately selected --config file; an automatically discovered workspace .a3s/config.acl may disable inherited retrieval but cannot enable it or choose an endpoint. The embedding model is a separate provider route from default_model, so a DeepSeek chat route does not become an embedding endpoint implicitly. Exact, glob, incremental BM25, and RRF are the model-free CPU baseline. Builds with the optional local-cpu-embedding feature can instead admit a revision- and SHA-256-bound ONNX model from a trusted local_cpu block. The zero-configuration local_cpu {} form asks A3S Power to install the locked ~23 MiB MiniLM/ONNX bundle on first use, verify every file before atomic commit, and reuse it offline. This artifact download never authorizes workspace source egress. --offline and A3S_NO_AUTO_INSTALL=1 forbid a missing first-use install; an explicit artifact_manifest remains available for self-managed model bundles. Interactive TUI startup exposes the locked descriptor without preparing the bundle: provisioning, full artifact admission, and ONNX construction begin only after the first frame when background semantic indexing submits real work. a3s code exec remains eager so a one-shot command reports missing local artifacts before running its requested turn. Official release archives enable that feature on Linux x64/ARM64, Windows x64, and Apple Silicon. Intel macOS retains model-free and remote retrieval because the pinned ONNX Runtime no longer ships that target. Native CI exercises a digest-locked model on every enabled target, and x64 builds fail before model loading when the CPU lacks the x86-64-v3 baseline. Local inference uses two-input microbatches and one process-wide native job to bound peak memory and cancellation recovery. RRF-only is the ranking default. A trusted ACL can explicitly add a typed deterministic_reranker block with bounded candidate, feature, fingerprint, and scratch limits; primitive mode/algorithm selectors and workspace-layer overrides are rejected before source/provider egress. It can also select exactly one typed line, fixed_window, or recursive chunking block. Omission preserves line chunking, recursive separator lists and overlap are Core-validated, primitive/custom selectors are rejected, and non-text files are not split or embedded. a3s config show reports backend availability and its non-sensitive unavailable reason, the artifact mode/readiness/revision, the bounded semantic-readiness timeout, effective chunking, and the versioned rerank algorithm without secrets. The CLI configures the manifest-backed chunk catalog once per host workspace; per-session retrieval options cannot override it, while every session keeps an isolated ephemeral vector index. The TUI footer exposes asynchronous retrieval readiness without polling Core on the 120 FPS render path. /status expands that snapshot into indexed and catalog coverage, vector memory/revisions, embedding batch efficiency, first ready latency, and non-text admission counts. Unified search calls in semantic and hybrid mode render verified-result, algorithm, channel, rerank, and explicit fallback evidence; Ctrl+T retains those diagnostics and the complete result body. Machine-readable code exec results expose the same bounded state without credentials, endpoints, vectors, or source text. See Workspace semantic retrieval, the real DeepSeek ACL-host evaluation, the local CPU model admission guide, and the cross-project WSR roadmap.

a3s code harness runs the immutable Agent release process declared by an admitted .a3s/asset.acl manifest. The manifest is authoritative for the HTTP port, readiness and liveness paths, shutdown deadline, protocol version, capability requirements, external secret slots, and artifact identity; the only host override is the listen interface.

a3s code harness --manifest /app/.a3s/asset.acl
a3s code harness --manifest /app/.a3s/asset.acl --listen 127.0.0.1

The version-one service exposes the manifest-declared health paths plus:

Manifest and compatibility admission, required external-secret checks, configuration loading, and Agent initialization complete before the release port is bound. With --json or --output jsonl, invalid protocols and unsupported capability levels retain their stable Agent release error codes. Health and structured error responses contain no secret values or release identity. SIGINT and SIGTERM make readiness false before draining requests and close the Harness within health.shutdown_grace_seconds.

The closed manifest schema, storage boundaries, compatibility rules, and breaking-change policy are documented in the A3S Code Agent release contract.

Useful TUI inputs:

@src/main.rs                  attach a workspace file
! cargo test -p my-crate      run a direct shell turn
/status                       inspect session, model, modes, and token usage
/ide                          open the workspace browser and editor
/desktop                     open this workspace in the latest A3S Desktop
/fork worktree               create an isolated branch, workspace, and session
/worktree handoff            emit a SHA-256-bound binary Git patch + manifest
/permissions                  change next-turn mode or review exact grants
/use status                   inspect Use setup and live capabilities
/packages                     review enable/disable for installed cognitive packages
/goal <outcome>               start a durable goal (maker→verifier; evidence-gated)
/loop schedule daily-triage 1d  run an audited L1 report loop in the background

Press / to browse the grouped command palette. Search matches command names, descriptions, and common concepts such as git or auth; a misspelled or unknown slash command is rejected locally with suggestions instead of being sent to the model.

Interactive startup constructs one complete session before terminal handoff. Fresh launches create only their new session id; resume uses only the saved session path and refuses to replace unreadable history with an empty session. An explicit resume <session-id> probes that id directly and enumerates other sessions only when it must print a missing-session diagnostic. The initial session and every in-process session rebuild share one lazy file-backed Memory handle: opening the TUI does not decode index.json; the first real recall, write, or inspection initializes it once. Resumed histories larger than 128 semantic entries paint their newest window first while retaining every entry; Page Up, Ctrl+Home, or mouse-wheel navigation toward older output hydrates the complete transcript. Status-bar branch discovery reads .git/HEAD directly, including linked-worktree indirection, and never starts a Git subprocess. The command prints an immediate Loading workspace… indicator while it builds the correctness-critical session. Its first TUI frame retains a non-blocking loading line while background services converge, with the editor already ready for input. A macOS PTY regression enforces a three-second process-to-first-frame ceiling.

Evolution memory synchronization, native WebView discovery or installation, A3S Use preparation, configured MCP transports, native sandbox initialization and probing, status-bar and picker metadata, interrupted-run recovery, repository manifest discovery and watcher registration, and workspace embedding all wait on one explicit first-frame flush acknowledgement. Before manifest activation, workspace operations retain their direct local fallback. The manifest gate is the first recorded post-frame operation and opens before the shared gate releases independently spawned background waiters. No fixed sleep estimates renderer progress. The initial session already owns a fail-closed sandbox proxy, so an early standard Bash call waits briefly for readiness and then returns a preparation error; it never falls through to unreviewed host execution. MCP tools hot-plug into the active session when each server is ready and are projected again after model or effort session rebuilds. Codex trust roots and TLS connectors are loaded on the first network request, and its OAuth refresh client is created only after an unauthorized response.

Set A3S_CODE_STARTUP_TRACE=1 to print content-free phase timings to stderr:

A3S_CODE_STARTUP_TRACE=1 a3s code

The trace records foreground phases through terminal_handoff, then the exact first_frame_flushed and first_deferred_operation ordering milestones. It contains only static phase/operation names and elapsed milliseconds. See Startup, Sessions, And Safety for the measured baseline and phase definitions.

TUI and a3s code exec share the same verified local process sandbox. Default and Auto run ordinary Bash calls inside that boundary; Plan exposes no Bash. An explicit require_escalated request never escapes silently: Default asks for the exact host command and Auto denies it. If sandbox preparation or its native capability probe fails, Bash is denied in every mode. Catastrophic commands and credential or control paths remain hard denials in every case.

The sandbox is implemented in Rust and invokes only the native OS isolation boundary: Seatbelt on macOS, user/PID/network namespaces plus seccomp on Linux, and AppContainer plus a kill-on-close Job Object on Windows. There is no Node.js, npm package, sidecar runtime, or one-time elevated setup. Linux requires bubblewrap and usable unprivileged user namespaces; macOS and Windows need no additional sandbox package. The CLI probes the real OS boundary before use. The TUI attaches a fail-closed proxy before terminal handoff and marks it ready only after the post-frame probe succeeds; code exec keeps the eager probe. Neither path ever falls back silently to an unsandboxed process.

For unattended repository work that must retain full local coding capability without public network access, code exec --mode auto --tool-policy local-workspace exposes workspace reads, Code Intelligence, bounded edits, structured local Git, and governed batch, program, task, workflow, and Skill execution. Host Web/download/Runtime/Knowledge/managed-Tool/MCP entry points and unknown dynamic tools stay hidden and denied. Bash appears only after the native sandbox probe succeeds, cannot escalate to the host, and uses the sandbox's empty network allowlist; delegated and Skill runs inherit the same boundary. The structured Git tool has no fetch, push, pull, or clone operation.

The sandbox denies network egress and local listeners, limits writes to the workspace and a private scratch directory, protects repository/control metadata, hides common credential stores and nested .env* files, scrubs the ambient environment, and rejects credential hard-link aliases. Delegated and Skill child runs inherit the same frozen sandbox and permission snapshot.

Audited L1 engineered loops can run through a workspace-local singleton worker:

a3s code schedule enable daily-triage --every 1d
a3s code schedule run daily-triage
a3s code schedule status
a3s code schedule notifications
a3s code schedule disable daily-triage

The worker atomically claims each due run, skips missed-interval replay storms, records interrupted work without silently rerunning uncertain effects, and keeps pending notifications until the TUI or CLI renders and acknowledges them. Its internal execution profile exposes bounded workspace reads, git status/log, and writes only the selected loop's STATE.md, RUN_LOG.md, and reports/ artifacts. Shell, network access, MCP, Runtime, delegation, package execution, unknown tools, denylisted paths, and the active ACL configuration remain closed.

The worker stays detached after the launching terminal exits. Opening the TUI restarts it when enabled schedules exist; after an operating-system reboot, use the TUI or a3s code schedule start to resume local schedules.

The base installation contains the umbrella CLI and A3S Code. Optional products remain separately released:

a3s list
a3s info use --versions --sources
a3s install use --source release --dry-run --json
a3s install use --source release --plan-digest <reviewedSha256> --json
a3s upgrade use --yes
a3s doctor use
a3s uninstall use --yes

Downloaded releases are checked for target, manifest, digest, ownership, and health before the active receipt changes. Mutating batches use a cross-process lock and durable checkpoints; an interrupted or failed upgrade leaves the previous healthy generation available.

The primary Code session receives use_knowledge_search only while a managed OKF projection is active; Default, Plan, Auto, and research evidence collection treat it as bounded read-only retrieval. Exact managed Runtime Tasks appear as conservative use_tool_* tools only while their snapshot generation and named reviewed provider are available. The dedicated Use worker receives only verified package Skills, mcp__use_*, and use_tool_* tools. It has no workspace shell, unrelated MCP access, or recursive delegation. Package mutations and open-world operations return to the parent confirmation stream.

Configuration uses A3S ACL—not TOML or HCL. Resolution checks an explicit A3S_CONFIG_FILE, workspace .a3s/config.acl, then ~/.a3s/config.acl.

a3s model list
a3s model current
a3s model use codex/gpt-5.6-sol
a3s model use openai/my-model --scope workspace
a3s auth list
a3s auth login os

Account-owned providers keep control of their login state; A3S does not copy their account tokens into config.acl, command output, logs, or the browser.

The public 0.14.0 CLI is usable for A3S Code and carries the cognitive-package architecture as a gated preview, not a production package platform. Promotion still requires all of the following:

• publish and operationally validate the official Registry trust root;
• complete cross-platform crash injection and real-registry multi-root shared dependency lifecycle coverage;
• run the full real-process cross-platform reviewed-enablement and watcher convergence matrix for CLI and TUI;
• finish managed OKF rollback, coordinated restore and authority recovery, backup rotation, and distributed placement; exact published-generation query leases, scope quota, bounded retention, tombstone GC, integrity audit, derived-index repair, and verifiable scope-local backup are implemented in the composed SQLite backend;
• complete real-provider production qualification for release-backed OCI Tasks, long-lived Tool Services, and HTTP MCP. A trusted Linux ACL can explicitly compose the shared Box provider and private Gateway for all three; the default remains unassigned and there is no fallback. The injected OCI Task path now proves install plus offline, restart-safe reviewed disable/re-enable, provider-drift recovery, and exact receipt-backed Task invocation after Manager restart. Accepted calls now lease their published generation through output capture and Runtime cleanup, while hide rejects new calls. The snapshot-v2 watcher now projects exact Tasks into TUI when their reviewed provider is present. The private Gateway regression proves reviewed-path health, standard MCP initialize, durable route restart, admission drain, and exact receipt-owned removal; Use contract tests prove Service retirement for uninstall and prior-generation cleanup. The Linux real-process gate additionally proves retained N/N+1 Tool and MCP routing, host restart, independent Tool and MCP provider-process loss, same-generation endpoint rebinding, sibling isolation, drain, exact removal, and no residual Runtime or PID state. Non-Linux provider composition and the cross-platform recovery matrix remain open;
• close the remaining native Windows six-surface and failure-injection package-lifecycle parity; and
• finish reviewed Activity rendering and backend bindings with generation-aware readiness and sandbox composition in CLI, TUI, and native hosts; and
• define production scheduling, recovery, and retention for Flow beyond the current single-node local runtime.

Until those gates close, unavailable capabilities remain visible as unavailable and fail closed.

Work in this repository directly or through the A3S monorepo's pinned crates/cli submodule. Do not create a Rust workspace at the monorepo root.

The lockfile pins published crates to exact versions and the composable Code, Flow, Memory, and Search companions to immutable git revisions. Release preflight verifies every revision and every platform Moli archive before an archive or crate is published.

cargo fmt --all -- --check
cargo test --lib
cargo test --tests
cargo clippy --all-targets --all-features -- -D warnings

Focused package-host gates:

cargo test --lib use_registry::tests:: --no-fail-fast
cargo test --bin a3s tui::panels::packages::tests --no-fail-fast
cargo test \
  generation_watch_hot_plugs_skill_mcp_runtime_task_flow_and_knowledge_across_tui_replacement
cargo test --lib \
  active_run_pins_native_use_skill_generation_across_atomic_cutover
cargo test --lib \
  use_registry::runtime_tasks::tests --no-fail-fast
cargo test --bin a3s \
  scoped_agent_discovers_and_invokes_only_the_reviewed_runtime_task
cargo test --lib \
  use_registry::knowledge::tests --no-fail-fast
cargo test --lib \
  atomic_flow_preflight_failure_leaves_the_current_generation_unchanged
cargo test --lib \
  atomic_flow_resolves_its_runtime_tool_in_the_same_exact_package
cargo test --lib \
  durable_run_is_idempotent_path_free_and_survives_package_removal
cargo test --lib \
  code_host_preflights_flow_and_persists_exact_generation_binding
cargo test --lib \
  signed_okf_install_upgrade_restart_query_and_uninstall_use_code_host
cargo test --lib \
  reviewed_managed_runtime_graph_rejects_drift_and_persists_exact_grant
cargo test --lib \
  signed_workspace_install_is_exact_fenced_and_replayable_after_restart
cargo test --lib \
  reviewed_managed_runtime_graph_rejects_drift_and_persists_exact_grant
cargo test --lib plugin_manager::operation
cargo test --lib plugin_manager::managed_host
cargo test --lib components::cognitive_lifecycle

The real separate-process Use integration is orchestrated from the monorepo so its Cargo outputs stay isolated:

just use-hotplug-e2e

• CLI reference
• CLI product design
• CLI technical architecture
• A3S Use Component Platform
• Applet UI projection parity (Desktop UiHost reference)
• Plugin authorization policy
• Code Intelligence
• Workspace Retrieval ACL-host evaluation
• DeepResearch evidence-first design
• Immutable Agent release contract
• A3S Use website
• A3S Use package contracts

a3s self update --check
a3s self update
a3s upgrade use

a3s update and a3s update <component> remain compatibility aliases but are deprecated. The TUI /update saves the current session, updates the CLI, and resumes it. Component upgrades preserve their owning provenance.

A3S CLI is licensed under the MIT License. Release archives retain the licenses and provenance notices of their bundled components.