Skip to content

docs(*): send the README's reference sections to the documentation site #519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ZuyiZhou merged 1 commit into from
Sep 19, 2026
Merged

docs(*): send the README's reference sections to the documentation site #519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -172,7 +172,7 @@ self.logger = logger.bind(channel=self.name)
| `chore` | Other misc |
| `revert` | Revert a prior commit |

**scope** — a top-level subpackage of `raven/`. See the `Repo layout` section of `README.md` for the canonical list. Spanning multiple scopes → omit the scope, or use `(*)`.
**scope** — a top-level subpackage of `raven/`. See the repo-layout page of the documentation site (`docs-site/docs/repo-layout.md`) for the canonical list. Spanning multiple scopes → omit the scope, or use `(*)`.

**subject** — lowercase start; no trailing period; English. The whole header (`<type>(<scope>): <subject>`) must be ≤ 100 chars — the single length rule, enforced by commitlint `header-max-length`.

Expand Down
258 changes: 4 additions & 254 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,89 +202,11 @@ checkout reads the tree in place. Setup asks about each product and registers
the ones you take up, on the model it is tuned for or on this raven's LLM.
See [`agents/README.md`](agents/README.md).

## ❯❯ Self-Hosting
Everything past the first run lives on the documentation site: self-hosting,
Docker deployment, the WebUI, the command reference, the runtime architecture
and the repository layout, in English and Chinese.

Raven can run directly from a checkout or as a single Docker Compose service. The
Compose deployment serves the built page through nginx, keeps the Raven engine
and its child services in one container, and stores durable state in a named
volume.

### 📝 Prerequisites

For a Docker deployment, install Docker Engine and Docker Compose v2. For a
source deployment, install Python 3.12, `uv`, Node.js, and npm. A source
checkout also needs the repository dependencies installed before starting the
engine.

### 🐳 Start with Docker Compose

The repository Compose setup builds the page and Python environment as part of
the image, so no separate host-side build is required:

```bash
cd docker
docker compose up
```

Open <http://127.0.0.1:18793>. The Compose container runs the full `gateway`
engine so providers added from **Settings > Model providers** are available on the next
turn without restarting.

For the detailed container layout, sign-in flow, provider setup, and operational
notes, see [`docker/README.md`](docker/README.md).

### ⚙️ Configuration

Docker reads committed defaults from [`docker/.env`](docker/.env), then loads
the optional, git-ignored `docker/.env.local` over them.
Put credentials and deployment-specific overrides in `.env.local`, not in the
committed file.

Raven stores its configuration, sessions, workspace, logs, and memory under
`RAVEN_HOME`. The Compose image maps this to `/data` through the `raven-data`
volume. Keep that volume for upgrades and restarts; `docker compose down -v`
deletes it and its data.

### 🛠️ Build a Docker image

Build the image using the Makefile target:

```bash
make docker-build
```

The default tag is `raven:local`. To select a different tag or optional
dependency set:

```bash
make docker-build DOCKER_IMAGE=raven:local
docker build -t raven:local --build-arg RAVEN_EXTRAS="channels,tools,sandbox" .
```

Run the locally built image through Compose by exporting
`RAVEN_IMAGE=raven:local` (or prefixing the command with that assignment) and
running `docker compose up` from `docker/`. The Makefile shortcut is
`RAVEN_IMAGE=raven:local make docker-up`. Stop the stack with `make docker-down`.


### 🚀 Start the server from source

From the repository root:

```bash
make install-deps
make build-ui
uv run raven web
```

`raven web` opens the local page and leaves the engine running after the
terminal exits. It defaults to `http://127.0.0.1:18792`. Use
`uv run raven web --foreground` when debugging, or `uv run raven web --stop` to
stop the resident engine. The first run can start without a configured model;
add one from **Settings > Model providers** or run `uv run raven onboard`.

To run only the engine without the browser launcher, use
`uv run raven gateway`.
**[Read the documentation](https://evermind-ai.github.io/Raven/)**

## ❯❯ Core Systems

Expand Down Expand Up @@ -320,178 +242,6 @@ The command opens the WebUI in your browser and keeps Raven running in the backg

> **Screenshot placeholder 3:** Memory and skill management.

## ❯❯ Command Reference

| Command | Purpose |
| --- | --- |
| `raven` or `raven tui` | Launch the terminal UI |
| `raven web` | Open the WebUI and keep Raven running in the background |
| `raven web --stop` | Stop the background WebUI service |
| `raven agent -m "..."` | Run a one-shot task |
| `raven onboard` | Configure providers, sandboxing, channels, memory, web tool keys, sub-agents, and import |
| `raven status` | Show configuration and runtime status |
| `raven doctor` | Diagnose provider and environment problems |
| `raven --version` | Show the installed Raven version |
| `raven upgrade --check` / `raven upgrade` | Check for updates or upgrade a managed installation |
| `raven agents new <name>` | Create a specialized agent from Raven's modular templates |
| `raven acp` | Serve Raven as an ACP agent over stdio |
| `raven sessions` | Create, list, fork, export, or delete sessions; resolve session keys with `resume` |
| `raven playbook` | Create, validate, manage, and run reusable agent workflows |
| `raven provider` | Configure providers and endpoints, authenticate, test connectivity, and select the active model |
| `raven channels` | List, configure, authenticate, enable, or disable messaging channels |
| `raven gateway` | Run messaging gateways |
| `raven gateway status` / `raven gateway reload` / `raven gateway stop` | Inspect, reload configuration, or gracefully stop a running gateway |
| `raven serve` | Run the headless WebSocket RPC service, serving the WebUI when available |
| `raven skill` | Browse SkillForge skills, inspect their contents, block or unblock skills, and remove installed bundles |
| `raven plugins` | List installed plugins and the active memory backend |
| `raven plugin auth <server>` | Authenticate or refresh OAuth access for an MCP server |
| `raven mcp bridge <socket-path>` | Bridge a subagent's MCP connection over stdio to a host-managed server |
| `raven import` | Preview and import data from other AI tools, inspect progress, or stop an import |
| `raven deep-research` | Configure, inspect, or reset the MiroThinker research integration |
| `raven cron` | Create, inspect, run, enable, disable, or delete scheduled jobs |
| `raven sentinel` | Configure proactivity and inspect attention, routines, decisions, and nudges |
| `raven ops connection` | Register local or remote machines, list them, and check connectivity |
| `raven sandbox` | List sandbox VMs, run commands, or open a shell; requires `sandbox.debug=true` |
| `raven tracing` | Open the local trace dashboard |
| `raven tracing compact` | Fold duplicate trace artifacts to reclaim disk space |
| `raven trajectory` | Save, replay, redact, label, and preserve execution trajectories for debugging |

Run `raven --help` or `raven <command> --help` for the complete CLI surface.

## ❯❯ Documentation

**[Raven documentation](https://evermind-ai.github.io/Raven/)** covers the quick
start, self-hosting, Docker deployment, the WebUI, the command reference, the
runtime architecture, and the repository layout, in English and Chinese.

The files below are engineering records kept in the repository beside the code
they describe. Several are dated design notes that describe the tree as of their
date rather than as it stands today.

- [Documentation index](docs/README.md)
- [Developer workflow](docs/dev.md)
- [Tracing Standard API](docs/TRACING_STANDARD_API.md)
- [Sandbox usage](docs/sandbox/usage.md)
- [Memory plugin architecture](docs/memory-plugin-architecture.md)
- [Self-evolution loop mapping](docs/specs/self-evolution-loop-raven-mapping.md)
- [Proactivity implementation](docs/Proactivity-Implementation.md)

<br>
<div align="right">

[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)

</div>

## ❯❯ Repo layout

The shared Python runtime lives in `raven/`. Agent definitions, plugin distributions, frontends, and development tools live alongside it.

Key directories:

```text
raven/ # Shared runtime, feature engines, and CLI/RPC/ACP surfaces
agents/ # Specialized agents assembled from installed Raven and plugins
plugins-dist/ # everos-memory, design-engine, and ppt-engine distributions
ui-web/ # Browser UI, also used by the desktop window
ui-tui/ # React/Ink terminal UI
rpc-schema/ # Shared OpenRPC contract for interactive clients
schemas/ # Generated agent and plugin JSON Schemas
bridge/ # WhatsApp TypeScript bridge
evolver/ # Benchmark-driven harness self-evolution tooling
benchmarks/ # Benchmark adapters and evaluation integrations
docker/ # Container deployment and Compose configuration
tests/ # Unit, integration, and architecture contract tests
scripts/ # Build, packaging, code generation, and repository checks
docs/ # Setup, development, and design documentation
```

The following runtime packages and modules form the canonical commit scopes under `raven/`. Changes outside `raven/` use the relevant tree or distribution scope from [`commitlint.config.cjs`](commitlint.config.cjs); see [`AGENTS.md`](AGENTS.md) for commit rules.

| Package | What it is |
|---|---|
| `acp` | ACP server surface: exposes Raven to external agent hosts |
| `acp_client` | ACP client, capability negotiation, and adapters for third-party agent events |
| `agent` | Agent Loop, Harness Modules, tool execution, and subagent orchestration |
| `auth` | Authentication and authorization primitives |
| `browser` | Browser automation, session management, and navigation checks |
| `channels` | Messaging adapters and their shared channel contract |
| `cli` | Command-line entry points, setup, and service launchers |
| `config` | Configuration schemas, loading, migrations, admission, and controlled updates |
| `contracts` | Papers: declared interfaces and data shapes shared across runtime components |
| `context_engine` | Context assembly, token budgets, and conversation compaction |
| `core` | Assembly Root: runtime generations and the builders that wire their components |
| `eval_engine` | Evaluation hooks for task completion, iteration feedback, and tool auditing |
| `gateway` | Channel lifecycle, runtime generation swaps, event delivery, and process coordination |
| `home` | Shared `RAVEN_HOME` and configuration-path resolution (`home.py`) |
| `i18n` | Language catalogs, translations, and prompt localization |
| `importer` | Cold-start import from other AI tools |
| `knowledge` | Document ingestion, indexing, and retrieval for user knowledge bases |
| `market` | PlugHub catalog, trust checks, installation, and contribution ledgers |
| `mcp` | MCP server connections and tool integration |
| `memory_engine` | Memory recall and consolidation, local skills, and SkillForge retrieval |
| `observability` | Span semantics, attribute extraction, and usage attribution |
| `ops` | Local and remote machine registry and execution transports |
| `permissions` | Tool-call decisions: allow, ask for approval, or refuse |
| `playbook` | Reusable workflow library, validation, generation, and execution |
| `plugins` | Plugin manifests, discovery, contribution registry, and bundled plugins |
| `proactive_engine` | Sentinel event processing, cron scheduling, heartbeat, and proactive decisions |
| `providers` | LLM adapters, provider pool, and model-to-provider binding |
| `routing` | Task classification and model selection by quality and cost |
| `rpc` | Shared typed RPC methods, streaming events, and gateway control surface |
| `sandbox` | Isolated execution, VM lifecycle, and debugging tools |
| `security` | Outbound address policy and prompt-injection fences |
| `session` | Conversation storage, session resolution, titles, and transcript export |
| `skill_hub` | SkillHub search, skill retrieval, bundle installation, and install policy |
| `spine` | Turn scheduling, concurrency lanes, cancellation, and event delivery |
| `templates` | Packaged workspace files, prompt packs, and agent scaffolding templates |
| `token_wise` | Token usage, pricing, prompt caching, and efficiency strategies |
| `tracing` | Span capture, instrumentation, trace storage, and artifact management |
| `trajectory` | Execution bundles, replay, redaction, outcome labels, and regression cassettes |
| `updates` | Release discovery, upgrade planning, installation handoff, and update notices |
| `utils` | Shared utilities, including atomic file writes |

## ❯❯ Architecture

Each runtime entrance assembles Raven through the same **Assembly Root**, `raven/core/runtime.py:build_runtime`. Configuration and plugin contributions determine the components in a runtime generation; the Spine schedules turns and delivers events around the Agent Loop.

```mermaid
flowchart TD
UI["WebUI / TUI"] --> RPC["Shared RPC surface"]
Hosts["External ACP hosts"] --> ACP["ACP server"]
ACP --> RPC
CLI["CLI tasks"] --> Spine["Spine: turn scheduling and events"]
Channels["Messaging channels"] --> Gateway["Gateway"]
Gateway --> Spine
RPC --> Spine
Proactive["Sentinel / Scheduler"] --> Spine
Spine --> Loop["Agent Loop"]
Loop --> Harness["Harness Modules<br/>Memory / Planning / Capability / Action"]
Harness --> Context["Context Engine"]
Harness --> Providers["Providers / model routing"]
Loop --> Tools["Tools / permissions<br/>MCP / sandbox"]
Loop --> Delegation["Subagents / Playbooks"]
Delegation --> Backends["Built-in / ACP / CLI / OpenAI backends"]
Context --> Memory["Memory Engine / SkillForge"]
Memory --> Sources["EverOS plugin / local skills / SkillHub"]
```

The WebUI and React/Ink TUI use the shared contract in [`rpc-schema/openrpc.json`](rpc-schema/openrpc.json). The ACP server adapts external hosts to the RPC stack, while the ACP client drives other agents. CLI tasks, messaging channels, and proactive triggers submit work through the Spine.

- **Modular execution.** The Agent Loop owns turn state, tool execution, persistence, and event ordering. Its four Harness Modules provide replaceable memory, planning, capability selection, and model-response behavior; hooks and tools add domain-specific capabilities.
- **Agent and plugin composition.** Definitions in [`agents/`](agents/README.md) combine the installed runtime with agent-specific configuration and plugins, then serve over ACP. [`plugins-dist/`](plugins-dist/) contains the EverOS memory, visual design, and PowerPoint engines as separate distributions.
- **Kernel boundaries.** `spine/`, `contracts/`, `tracing/`, and `home.py` form the standalone Kernel. Inner runtime packages do not import the CLI, RPC, or ACP surfaces; import contracts enforce these boundaries.
- **Harness self-evolution.** [`evolver/`](evolver/README.md) is a separate tool that diagnoses runs and evaluates candidate harness changes against benchmarks. It consumes Raven as a library; the runtime does not import Evolver or the repo-level agent definitions.

See the [Context Map](CONTEXT-MAP.md) for subsystem boundaries, the [Runtime Context](CONTEXT.md) for canonical terms and layer seats, and [`pyproject.toml`](pyproject.toml) for the enforced import contracts.

<br>
<div align="right">

[![](https://img.shields.io/badge/-Back_to_top-gray?style=flat-square)](#readme-top)

</div>

## ❯❯ EverMind Ecosystem

[EverMind](https://evermind.ai/) connects memory research, production-ready products, and practical
Expand Down
Loading
Loading