Choose Your Starting Point

Quick Start

Agent Runtime

You need Python 3.11+ and an API key for at least one model service. Run in your terminal:

pip install "echo-agent[all]"
echo-agent setup
echo-agent run

setup configures a model; run starts the full Runtime. In mainland China, append -i https://mirrors.aliyun.com/pypi/simple/ to the installation command if needed. The same commands work in Windows PowerShell; see the installation guide for dependencies and platform limitations.

Gateway and Dashboard

For web management, API access, or CLI/TUI clients, exit the run process above, then start Gateway:

echo-agent gateway

Open http://127.0.0.1:58123/ for Dashboard. Connect to the same Runtime from another terminal:

echo-agent cli --tui

Messaging channels, Webhooks, and scheduled jobs follow configuration. Normally run one full Runtime per workspace; cli connects to an existing Gateway without starting another engine. See runtime modes and the Dashboard guide.

echo-agent gateway install
echo-agent gateway status
echo-agent gateway logs --follow

bash scripts/install.sh --source .

EchoAgent Desktop

See the Desktop quick start for installers, supported platforms, and source prerequisites. With this repository already checked out, macOS users can start from its root:

cd client
pnpm setup:mac
pnpm install --frozen-lockfile
pnpm tauri dev

The first launch prepares the embedded Runtime, Theia IDE, and Office Worker. Desktop starts independently and can use the project's built-in remote model service or your own connections. See the Desktop documentation for Windows instructions.

Long-Term Memory and Skill Evolution

Cognitive memory carries context across sessions; skill evolution makes execution experience reusable. These are the two paths in the Runtime:

Cognitive Memory

Remember user preferences and project facts across sessions, reducing repeated background explanations. Memory uses Working, Episodic, Semantic, and Archival tiers. BM25 and optional vector retrieval combine through RRF. Scope, provenance, and lifecycle eligibility determine what enters the current context; archived, superseded, and unresolved entries are excluded from normal recall.

Background consolidation after replies can extract summaries and facts, resolve contradictions, and apply decay and archival policies. See the memory system for implementation and configuration.

Self-Evolving Skills

Generate reusable skill candidates from execution trajectories and reflection, then route them to review or isolated evaluation according to risk and configuration. Only candidates that meet the promotion policy reach the live skill library. Rejections retain their reasons; promoted changes support manual rollback.

The evolution engine is disabled by default and must be enabled in configuration. Once enabled, it supports manual, trajectory-threshold, and scheduled triggers. It updates skill content and enabled state; see evolution and evaluation for the full process.

Architecture and Runtime Modes

Desktop and standalone Runtime follow the same Agent method but currently use different execution engines. Python Runtime provides terminal, Gateway, channels, memory, and skill evolution. Desktop embeds a Rust engine for workspaces, IDE, and automation. Each manages its own models, sessions, and memory and works independently.

Main Operating Modes

Runtime Capabilities

EchoAgent Desktop

Put your Agent to work in your workspace. Desktop uses React, Tauri, and an in-process Rust Agent engine to show plans, tool activity, file changes, and deliverables in one application.

Browser side effects and desktop tasks use different confirmation flows. Computer Use executes continuously within an authorized task; platform permissions still apply. See the Desktop README, architecture and data flow, and automation platform support for implementation details and real-device validation scope.

Extensions and Integration

Bring Agent capabilities into your application through a service connection or source-level embedding:

• Connect to Gateway: Submit tasks and receive events through the HTTP / WebSocket API. The Runtime service owns models, memory, and execution state.
• Embed the Runtime from source: Compose components with bootstrap / AppRuntime and let the host manage startup, shutdown, and workspace ownership. Interfaces follow the chosen source version; pin it and validate lifecycle behavior.
• Study the Desktop host integration: agent_runtime.rs shows the embedded Echo Agent Runtime and typed ACP channels; dependencies are declared in Cargo.toml.

Data and Security

Sessions, memory, configuration, and other state stay in the deployment environment. Remote models, external MCP servers, and third-party messaging channels receive data needed for their operations. When browser or computer automation is enabled in Desktop, model input may include page content and screenshots.

Runtime tool calls follow permissions and approval policies. Desktop also controls workspace authorization, permission modes, and task scope. See the security model, hardening guide, and Desktop data and permission boundaries for storage, authentication, and operational boundaries.

Documentation

Full documentation: English · 中文文档

Development and Contributing

echo-agent/
├── echo-agent-runtime/   # Standalone Runtime, including Dashboard and skills
├── client/               # Desktop workspace, embedded Runtime, and Theia
├── docs/                 # Documentation site and visual assets
├── scripts/              # Repository maintenance, docs checks, and diagram generation
└── .github/              # CI, releases, and repository automation

git clone https://github.com/fuyuxiang/echo-agent.git
cd echo-agent/echo-agent-runtime
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
ruff check .
pytest

Contributions to the Runtime, bug fixes, tools, Skills, Plugins, channels, and documentation are welcome. See CONTRIBUTING.en.md and the repository map. The bilingual README architecture diagrams are generated by scripts/generate-readme-diagrams.py; review and update diagrams and text when their implementations change.

Community and Support

• Usage questions and design discussions: GitHub Discussions
• Bug reports and feature requests: GitHub Issues
• Chinese-language chat: QQ group 47572014
• Security vulnerabilities: GitHub private security reports; see SECURITY.md for the disclosure process

Project Founders

Echo Agent was co-founded by Yuxiang Fu and Yanrong Gao.

License

Original project code is available under the PolyForm Noncommercial License 1.0.0 for the purposes permitted by that license. Commercial uses outside those purposes require separate permission from the maintainers.

Third-party components retain their respective licenses. This update does not revoke rights already granted under earlier licenses.

Earlier MIT notice: LICENSES/MIT.txt. See the third-party notices for licenses of components included in the desktop app.

The FastEmbed compatibility copy bundled with the Runtime is licensed under Apache-2.0. See its maintenance notes for the source and Pillow 13 compatibility changes.