Open-source coding infrastructure for developers who want agentic speed without giving up control.

Quick start · Documentation · 简体中文

Apollo Code brings an agentic coding loop to the command line while keeping trust, permissions, credentials, and sandbox state visible. It is designed around explicit provider boundaries, recoverable file changes, machine-readable output, and native isolation helpers.

Important

Apollo Code is in active early development. A stable npm release has not been published; install it from source for evaluation and development. Interfaces and behavior may change before the first stable release.

Table of contents

• Why Apollo Code
• What works today
• Quick start
• Usage
• Configuration and security
• How it fits together
• Development
• Roadmap and project status
• Contributing and support
• License

Why Apollo Code

Control by default	Built for real workflows	Open at every layer
Explicit trust Resolve directory trust before any provider, tool, or session starts.	Recoverable sessions Resume durable turns and preview guarded file restoration.	Provider-neutral core Keep adapters and routing outside the agent loop.
Granular permissions Approve writes, commands, and network access independently.	Native isolation Use Rust-powered sandbox, search, and filesystem helpers.	Composable runtime Extend through namespaced plugins, skills, tools, and MCP.
Visible security state Inspect credentials, sandbox tier, trust, and runtime health.	Automation-ready Stream versioned NDJSON without ANSI or TUI frames.	Inspectable architecture Follow boundaries across TypeScript packages and Rust crates.

What works today

The current CLI includes:

• interactive Ink TUI and line-mode chat;
• one-shot prompts and NDJSON output for scripts;
• directory trust rules and project-configuration approval;
• provider credential login/logout with secure storage;
• permission checks, native sandbox integration, and runtime diagnostics;
• session history, resume, and guarded restore flows;
• local plugin install, enable, disable, diagnose, list, and uninstall commands;
• local telemetry inspection, redacted export, and clearing;
• configurable provider/model routing, including role-based candidates.

See the CLI reference for the authoritative command surface and the security model before using Apollo on sensitive repositories.

Quick start

Prerequisites

• Node.js 20.19 or newer
• pnpm 11.10.0 (declared through Corepack)
• Rust 1.71 or newer when building the native crates locally

Build from source

git clone https://github.com/JS-mark/apollo-code.git
cd apollo-code
corepack enable
pnpm install --frozen-lockfile
pnpm build
node apps/cli/dist/apollo.js --help

The workspace package version is currently 0.0.0; it is not a published release. Follow the installation guide for release and native-binary details.

Start your first session

node apps/cli/dist/apollo.js chat

On first use in a directory, Apollo asks you to trust the canonical workspace path before initializing the runtime. Choose Anthropic during onboarding and enter the credential only in Apollo's masked prompt, or authenticate explicitly:

node apps/cli/dist/apollo.js login anthropic
node apps/cli/dist/apollo.js doctor --strict

Read the first-run guide for trust scopes, headless behavior, and sandbox checks.

Usage

Interactive chat is the default when stdin and stdout are terminals:

node apps/cli/dist/apollo.js
node apps/cli/dist/apollo.js chat

Force the line-mode fallback:

node apps/cli/dist/apollo.js chat --no-tui

Run a one-shot prompt and emit NDJSON without ANSI frames:

node apps/cli/dist/apollo.js chat "summarize this repository" --json

Inspect runtime state or manage a previous session:

node apps/cli/dist/apollo.js status --json
node apps/cli/dist/apollo.js history list
node apps/cli/dist/apollo.js resume <session-id>
node apps/cli/dist/apollo.js restore <session-id> --dry-run

Save durable project knowledge and pin selected memories into future prompts:

node apps/cli/dist/apollo.js memory add --id package-manager --tag tooling --content "Use pnpm"
node apps/cli/dist/apollo.js memory pin package-manager
node apps/cli/dist/apollo.js memory list --scope project --pinned --json

Pinned memories are bounded and injected as untrusted advisory data. Current user and system instructions always take precedence. Use memory unpin or memory delete --yes to stop future injection.

Use apollo help or the CLI reference for all commands. The JSON output reference documents the automation contract.

Configuration and security

User configuration lives in ~/.apollo/config.toml. Configuration layers are applied in this order: built-in defaults, global configuration, approved project configuration, environment values, then CLI flags. Project configuration is not loaded in non-interactive runs unless you pass --trust-project-config; sensitive routing, authentication, endpoint, and telemetry-sink keys are rejected from project configuration.

Example role routing in the trusted global configuration:

[router]
type = "role"

[router.default]
provider = "anthropic"
model = "claude-sonnet-4-5"

[router.roles.coder]
provider = "anthropic"
model = "claude-sonnet-4-5"
priority = 100

Security-relevant behavior:

• directory trust does not grant write, command, or network permission;
• headless runs fail on untrusted directories unless --trust-workspace is supplied explicitly;
• credentials are stored in the OS keychain or encrypted fallback store, not project files;
• --dangerously-no-sandbox requires explicit risk confirmation and is unsuitable for release acceptance;
• telemetry stays local unless an exporter is explicitly configured.

For details, see directory trust and first run, the security model, and sandbox troubleshooting.

How it fits together

Terminal / automation
        │
        ▼
  apps/cli ──────── interactive UI, commands, JSON output
        │
        ▼
 packages/core ──── session and agent loop
   │      │      │
   │      │      └── tools, permissions, context, storage
   │      └───────── provider router and provider adapters
   └──────────────── plugin, skill, and MCP runtimes
        │
        ▼
 crates/* ───────── native sandbox, search, and filesystem helpers

The TypeScript packages keep the agent loop, providers, tools, permissions, storage, UI, plugins, and native bridge separated. The Rust workspace contains apollo-sandbox, apollo-search, and apollo-fs. For the detailed design, read the architecture specification.

Development

Install dependencies and run the standard local checks:

corepack enable
pnpm install --frozen-lockfile
cargo test --workspace
pnpm typecheck
pnpm test
pnpm build
pnpm format:check

Build optimized native binaries with cargo build --workspace --release. For local native diagnostics, build the Rust workspace and point Apollo to the three binaries:

cargo build --workspace
pnpm --filter apollo-code build
APOLLO_NATIVE_SANDBOX_BINARY="$PWD/target/debug/apollo-sandbox" \
APOLLO_NATIVE_SEARCH_BINARY="$PWD/target/debug/apollo-search" \
APOLLO_NATIVE_FS_BINARY="$PWD/target/debug/apollo-fs" \
node apps/cli/dist/apollo.js doctor --strict

An unavailable Anthropic credential can still make strict diagnostics fail after the native binaries build successfully. See authentication troubleshooting.

Roadmap and project status

Apollo Code is progressing through repository-defined capability levels. The current public package is not released, and some future-facing design documents describe work beyond the shipped CLI. The implementation and tests are the source of truth.

Current planning and evidence are maintained in:

• the milestone specification;
• release readiness evidence;
• the capability traceability document.

Notably, registry/GitHub plugin installation, plugin upgrades, and the L4 development hot-reload command are not implemented yet.

Contributing and support

Contributions are welcome. Start with CONTRIBUTING.md, follow the Code of Conduct, and review SECURITY.md before reporting a vulnerability.

• Use GitHub Issues for reproducible bugs and approved work.
• Use GitHub Discussions for questions and ideas, if Discussions is enabled for the repository.
• Follow the RFC process in the contribution guide for architecture, security, providers, or public API changes.

License

Apollo Code is licensed under the Apache License 2.0.