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 |
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.
Current integration:
- WhatsApp (Meta Cloud API)
Future integrations:
- Slack
- Telegram
- Discord
- Web chat
- Voice assistants
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):
API Layer
REST / WebSocket
↓
Runtime Engine
Agent lifecycle and execution
↓
Core Services
Model Router · Memory Manager · Tool Registry · Guardrails
↓
Infrastructure
LLM Providers · Vector Databases · Observability · Storage Backends
- 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/v1
kind: Agent
metadata:
name: my-agent
spec:
identity:
display_name: "My Agent"
model:
primary:
provider: ollama
model: "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
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-adkfrom astromesh_adk import Agent, Tool
agent = 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
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/
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.