Documentation · Quick Start · Releases
Build, orchestrate and run AI agents with multi-model routing, tools, memory, and RAG — all configured declaratively.
Astromesh is an open-source runtime for agentic systems, designed to standardize how AI agents execute, reason, and interact with external systems.
Think of it as Kubernetes for AI Agents.
⭐ If you find this project useful, consider starring the repository.
Most AI applications repeatedly rebuild the same infrastructure:
- model orchestration
- tool execution
- memory systems
- RAG pipelines
- agent reasoning loops
- observability
- cost control
Astromesh centralizes these capabilities into a single runtime platform.
Instead of writing orchestration logic yourself, you define agents declaratively and let the runtime manage execution.
Full documentation site: monaccode.github.io/astromesh
Includes getting started guides, architecture deep-dives, 7 deployment modes, configuration reference, and API docs.
Additional references in this repo:
- Tech overview:
docs/TECH_OVERVIEW.md - General architecture:
docs/GENERAL_ARCHITECTURE.md - Kubernetes-style architecture diagrams:
docs/K8S_ARCHITECTURE.md - Configuration guide:
docs/CONFIGURATION_GUIDE.md - WhatsApp integration:
docs/WHATSAPP_INTEGRATION.md - Maia mesh guide:
docs/MAIA_GUIDE.md - Developer quick start:
docs/DEV_QUICKSTART.md - ADK quick start:
docs/ADK_QUICKSTART.md - ADK implementation status and pending work:
docs/ADK_PENDING.md - Cloud overview:
docs/CLOUD_OVERVIEW.md - Cloud quick start:
docs/CLOUD_QUICKSTART.md - Cloud API reference:
docs/CLOUD_API_REFERENCE.md - Installation (APT):
docs/INSTALLATION.md - Developer tools:
docs/DEVELOPER_TOOLS.md - Orbit overview:
docs/ORBIT_OVERVIEW.md - Orbit quick start:
docs/ORBIT_QUICKSTART.md - Orbit configuration:
docs/ORBIT_CONFIGURATION.md
Run agents across multiple LLM providers:
- Ollama
- OpenAI-compatible APIs
- vLLM
- llama.cpp
- HuggingFace TGI
- ONNX Runtime
The built-in Model Router automatically selects the best model using strategies such as:
- cost optimized
- latency optimized
- quality first
- round robin
- capability match
Astromesh includes several orchestration strategies:
| Pattern | Description |
|---|---|
| ReAct | reasoning + tool usage loop |
| Plan & Execute | generate plan then execute |
| Pipeline | sequential processing |
| Parallel Fan-Out | multi-model collaboration |
| Supervisor | hierarchical agents |
| Swarm | distributed agent collaboration |
| Glyph | the model writes one program; its dependency graph is executed in waves |
Agents can maintain multiple memory layers:
| Memory Type | Purpose |
|---|---|
| Conversational | chat history |
| Semantic | vector embeddings |
| Episodic | event logs |
Supported backends:
- Redis
- PostgreSQL
- SQLite
- pgvector
- ChromaDB
- Qdrant
- FAISS
Astromesh includes a complete RAG pipeline:
- document chunking
- embeddings
- vector search
- reranking
- context injection
Supported vector stores:
- pgvector
- ChromaDB
- Qdrant
- FAISS
Agents interact with external systems using tools:
| Type | Description |
|---|---|
| Built-in (18 tools) | web_search, http_request, sql_query, send_email, read_file, and more |
| MCP Servers (3) | code_interpreter, shell_exec, generate_image |
| Agent tools | Invoke other agents as tools for multi-agent composition |
| Webhooks | Call external HTTP endpoints |
| RAG | Query and ingest documents |
Tools are configured declaratively in agent YAML with zero-code setup for built-ins.
Astromesh supports external messaging integrations.
In the runtime:
- WhatsApp (Meta Cloud API), through the built-in channel adapter
send_message, a built-in tool that lets an agent reach a person mid-run instead of only answering whoever wrote first
Through Herald, the communications gateway of the suite: two-way routing decided by an entry agent, a Postgres outbox with a retry budget, and an operator console. WhatsApp is live there; Telegram, Web Chat and SMTP have contract stubs in place.
Full observability stack with zero configuration:
- Structured tracing — span trees for every agent execution
- Metrics — counters and histograms (runs, tokens, cost, latency)
- Built-in dashboard — web UI at
/v1/dashboard/ - CLI access —
astromeshctl traces,astromeshctl metrics,astromeshctl cost - OpenTelemetry export — compatible with Jaeger, Grafana Tempo, etc.
- VS Code integration — traces panel and metrics dashboard in your editor
Astromesh provides a complete developer toolkit:
| Tool | Description |
|---|---|
CLI (astromeshctl) | Scaffold agents, run workflows, inspect traces, view metrics, validate configs |
| Copilot | Built-in AI assistant that helps build and debug agents |
| VS Code Extension | YAML IntelliSense, workflow visualizer, traces panel, metrics dashboard, copilot chat |
| Built-in Dashboard | Web UI at /v1/dashboard/ with real-time observability |
# Scaffold a new agent
astromeshctl new agent customer-support
# Run it
astromeshctl run customer-support "How do I reset my password?"# See what happened
astromeshctl traces customer-support --last 5
# Check costs
astromeshctl cost --window 24h
# Ask the copilot for help
astromeshctl ask "Why is my agent slow?"Astromesh follows a layered architecture (see also docs/GENERAL_ARCHITECTURE.md for the full reference):
flowchart TB
api["`**API Layer**
REST / WebSocket`"]
runtime["`**Runtime Engine**
Agent lifecycle and execution`"]
core["`**Core Services**
Model Router · Memory Manager · Tool Registry · Guardrails`"]
infra["`**Infrastructure**
LLM Providers · Vector Databases · Observability · Storage Backends`"]
api --> runtime --> core --> infra
- Python 3.12+
- uv package manager
pip install uvgit clone https://github.com/monaccode/astromesh.git
cd astromeshuv syncuv run uvicorn astromesh.api.main:app --reloadAPI will be available at http://localhost:8000
Create the file: config/agents/my-agent.agent.yaml
apiVersion: astromesh/v1kind: Agentmetadata:
name: my-agentspec:
identity:
display_name: "My Agent"model:
primary:
provider: ollamamodel: "llama3.1:8b"prompts:
system: | You are a helpful assistant.orchestration:
pattern: reactcurl -X POST http://localhost:8000/v1/agents/my-agent/run \
-H "Content-Type: application/json" \
-d '{"query":"Hello","session_id":"demo"}'- developer assistants
- support agents
- internal knowledge assistants
- document processing
- business automation
- API orchestration
- distributed reasoning
- hierarchical agents
- collaborative agents
Expose agents as programmable services.
Astromesh includes a full development stack:
docker compose upIncludes:
- Agent runtime API
- Ollama inference
- vLLM inference
- embeddings service
- PostgreSQL + pgvector
- Redis
- Prometheus
- Grafana
Astromesh is an ecosystem covering the full agent lifecycle. Every component moves on its own clock, so the current versions live in one place — the ecosystem map and its release ledger — rather than in a table that goes stale the day after a release.
| Component | What it does | Where it lives | |
|---|---|---|---|
| Author | ADK | Python-first agent SDK with decorators, hot reload and a project CLI | astromesh-adk |
| Forge | Visual agent builder, served by the node itself at /forge | astromesh-forge | |
| Cortex | Desktop IDE that reaches every runtime you own (Electron + React) | own repo | |
| Leia | Agent operations in plain English, from inside Claude Code | own repo | |
| Execute | Core Runtime | Multi-model agent engine with 7 orchestration patterns | astromesh |
| Glyph | Action language: the model writes one program instead of one tool call per turn | astromesh-glyph | |
| Reach | Herald | Communications gateway — a person reaches an agent, and an agent reaches back | own repo |
| Ship | Node | Cross-platform system installer and daemon | astromesh-node |
| OS | Immutable, API-only Linux appliance with A/B slots | own repo | |
| Orbit | Cloud-native IaC deployment with Terraform (GCP first) | astromesh-orbit | |
| Operate | Nexus | Multi-tenant control plane: publishes, dispatches, meters, bills | own repo |
| CLI | astromeshctl — the terminal interface to a node | astromesh-cli | |
| Models | Nebula | The open-model foundry that trains and publishes what the runtime routes to | own repo |
Anything listed with a package name is a directory of this monorepo, released on its own tag.
The Agent Development Kit is a Python SDK for building, testing, and deploying agents on Astromesh. It provides a high-level API that wraps the runtime, so you can define agents in Python code instead of YAML.
pip install astromesh-adkfromastromesh_adkimportAgent, Toolagent=Agent(
name="my-agent",
model="ollama/llama3.1:8b",
system_prompt="You are a helpful assistant.",
tools=[Tool.web_search(), Tool.http_request()],
)
response=agent.run("What's the weather in Buenos Aires?")- Python-first — Define agents, tools, memory, and guardrails in code
- CLI included —
astromesh-adk init,astromesh-adk run,astromesh-adk test - Hot reload — Edit your agent code and see changes immediately
- Compatible — Generates standard Astromesh agent YAML under the hood
Docs: docs/ADK_QUICKSTART.md | docs/ADK_PENDING.md
Cross-platform system installer and daemon — deploy Astromesh as a native system service on Linux, macOS, and Windows.
# Debian/Ubuntu
sudo dpkg -i astromesh-node-0.1.2-amd64.deb
sudo astromeshctl init --profile full
sudo systemctl start astromeshd- Cross-platform —
.deb(Debian/Ubuntu),.rpm(RHEL/Fedora),.tar.gz(macOS),.zip(Windows) - System service — systemd, launchd, or Windows Service with auto-restart
- CLI management —
astromeshctlwith 17 commands (status, doctor, agents, mesh, etc.) - 7 profiles — full, gateway, worker, inference, mesh-gateway, mesh-worker, mesh-inference
Docs: Node Introduction | Installation Guides
A managed multi-tenant platform for deploying and operating Astromesh agents as a service. Includes a REST API, a web-based Studio for no-code agent design, and usage tracking.
# Cloud API (FastAPI + PostgreSQL)cd astromesh-cloud/api && uvicorn astromesh_cloud.main:app --port 8001
# Cloud Studio (Next.js)cd astromesh-cloud/web && npm run dev- Multi-tenant — Organizations, members, API keys, rate limiting
- Agent lifecycle — draft → deployed → paused with quota enforcement
- BYOK — Bring your own provider keys (OpenAI, Anthropic, etc.) with Fernet encryption
- Studio — 5-step agent wizard, deploy preview, test chat, usage dashboard
- Runtime proxy — Proxies execution to Astromesh core with namespace isolation
Docs: docs/CLOUD_OVERVIEW.md | docs/CLOUD_QUICKSTART.md | docs/CLOUD_API_REFERENCE.md
Orbit is a standalone deployment tool that provisions the full Astromesh stack on cloud infrastructure with a single command. It generates Terraform from Jinja2 templates using a provider plugin architecture.
pip install astromesh-orbit[gcp]
astromeshctl orbit init --provider gcp --preset starter
astromeshctl orbit plan
astromeshctl orbit applyOne command deploys Cloud Run (runtime + Cloud API + Studio), Cloud SQL, Memorystore, Secret Manager, VPC networking, and IAM — all configured from a single orbit.yaml file.
- GCP first — Cloud-native managed services. AWS and Azure providers on the roadmap.
- Escape hatch —
orbit ejectproduces standalone Terraform files with no Orbit dependency. - Two presets — Starter (
$30/mo) and Pro ($150/mo), or configure every field manually.
Docs: docs/ORBIT_OVERVIEW.md | docs/ORBIT_QUICKSTART.md | docs/ORBIT_CONFIGURATION.md
astromesh/ # Core runtime
├── api/ # REST + WebSocket API
├── runtime/ # Agent lifecycle engine
├── core/ # Model router, memory, tools, guardrails
├── providers/ # LLM provider adapters
├── orchestration/ # ReAct, Plan&Execute, Pipeline, etc.
├── rag/ # RAG pipeline
├── channels/ # WhatsApp, Slack, etc.
└── mesh/ # Distributed agent networking
astromesh-adk/ # Agent Development Kit (pip install astromesh-adk)
├── astromesh_adk/
└── tests/
astromesh-cloud/ # Managed platform (SaaS)
├── api/ # Cloud API (FastAPI + PostgreSQL)
└── web/ # Cloud Studio (Next.js)
astromesh-orbit/ # Cloud deployment tool (pip install astromesh-orbit)
├── astromesh_orbit/
│ ├── core/ # Provider Protocol + data types
│ ├── terraform/ # Terraform runner + state backend
│ ├── wizard/ # Interactive setup + presets
│ └── providers/gcp/ # GCP templates
└── tests/
astromesh-cli/ # Astromesh CLI — standalone CLI tool for managing nodes and clusters
├── astromesh_cli/
└── tests/
astromesh-node/ # Astromesh Node — daemon, CLI, and packaging (pip install astromesh-node)
├── daemon/ # astromeshd process (systemd / launchd / Windows Service)
├── cli/ # astromeshctl command-line tool
├── packaging/ # APT/RPM/Homebrew packaging configs
└── tests/
Configuration:
config/
├── agents/
├── rag/
├── providers.yaml
└── runtime.yaml
orbit.yaml # Orbit deployment config (project root)
Astromesh includes optional Rust-powered native extensions for CPU-bound hot paths (chunking, PII redaction, token counting, routing). When compiled, they provide 5-50x speedup. Without them, the system falls back to pure Python automatically.
pip install maturin
maturin develop --releaseSee docs/NATIVE_ESTENSIONS_RUST.md for details.
- Multi-model runtime with 6 providers
- 6 orchestration patterns (ReAct, Plan&Execute, Pipeline, Fan-Out, Supervisor, Swarm)
- Memory system (conversational, semantic, episodic)
- RAG pipeline with 4 vector stores
- 18 built-in tools + 3 MCP servers
- Full observability (tracing, metrics, dashboard)
- CLI with copilot
- Multi-agent composition (agent-as-tool)
- Workflow YAML engine
- VS Code extension
- Agent Development Kit (ADK) — Python SDK
- Astromesh Cloud — managed multi-tenant platform
- Astromesh Orbit — cloud-native deployment (GCP)
- Distributed agent execution
- GPU-aware model scheduling
- Event-driven agents
- Multi-tenant runtime
- Agent marketplace
Contributions are welcome.
Ways to contribute:
- new providers
- orchestration patterns
- vector stores
- tools
- bug fixes
- documentation improvements
Apache-2.0 (see LICENSE)
Community resources coming soon:
- Discord
- Roadmap discussions
- Contributor guide
⭐ If you like Astromesh, give the repo a star. It helps the project reach more developers.