Astromesh

Agent Runtime Platform for building AI agents

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.

---

Why Astromesh

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.

---

Documentation

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

---

Key Features

Multi-Model Runtime

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

---

Multiple Agent Reasoning Patterns

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

---

Built-in Memory System

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

---

Retrieval-Augmented Generation (RAG)

Astromesh includes a complete RAG pipeline:

• document chunking
• embeddings
• vector search
• reranking
• context injection

Supported vector stores:

• pgvector
• ChromaDB
• Qdrant
• FAISS

---

Tool System

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.

---

Messaging Channels

Astromesh supports external messaging integrations.

Current integration:

• WhatsApp (Meta Cloud API)

Future integrations:

• Slack
• Telegram
• Discord
• Web chat
• Voice assistants

---

Observability

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

---

Developer Experience

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?"

---

Architecture

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

---

Quick Start

Requirements

• Python 3.12+
• uv package manager

Install uv

pip install uv

Clone the repository

git clone https://github.com/monaccode/astromesh.git
cd astromesh

Install dependencies

uv sync

Run the runtime

uv run uvicorn astromesh.api.main:app --reload

API will be available at http://localhost:8000

---

Create Your First Agent

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: react

Run the Agent

curl -X POST http://localhost:8000/v1/agents/my-agent/run \
  -H "Content-Type: application/json" \
  -d '{"query":"Hello","session_id":"demo"}'

---

Example Use Cases

AI Copilots

• developer assistants
• support agents
• internal knowledge assistants

Autonomous Workflows

• document processing
• business automation
• API orchestration

Multi-Agent Systems

• distributed reasoning
• hierarchical agents
• collaborative agents

AI APIs

Expose agents as programmable services.

---

Docker Deployment

Astromesh includes a full development stack:

docker compose up

Includes:

• Agent runtime API
• Ollama inference
• vLLM inference
• embeddings service
• PostgreSQL + pgvector
• Redis
• Prometheus
• Grafana

---

Ecosystem

Astromesh is an ecosystem of six components covering the full agent lifecycle:

Component	Description	Package	Status
Core Runtime	Multi-model agent engine with 6 orchestration patterns	astromesh	v0.19.0
ADK	Python-first agent SDK with decorators and CLI	astromesh-adk	v0.1.5
CLI	CLI tool for managing nodes and clusters	astromesh-cli	v0.1.0
Node	Cross-platform system installer and daemon	astromesh-node	v0.1.0
Forge	Visual agent builder with wizard, canvas, and templates	astromesh-forge	v0.1.0
Orbit	Cloud-native IaC deployment with Terraform	astromesh-orbit	v0.1.0

---

Astromesh ADK

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-adk

from 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

---

Astromesh Node

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.0-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 — astromeshctl with 17 commands (status, doctor, agents, mesh, etc.)
• 7 profiles — full, gateway, worker, inference, mesh-gateway, mesh-worker, mesh-inference

Docs: Node Introduction | Installation Guides

---

Astromesh Cloud

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

---

Astromesh Orbit

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 apply

One 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 eject produces 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

---

Project Structure

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)

---

Optional: Rust Native Extensions

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 --release

See docs/NATIVE_ESTENSIONS_RUST.md for details.

---

Roadmap

• 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

---

Contributing

Contributions are welcome.

Ways to contribute:

• new providers
• orchestration patterns
• vector stores
• tools
• bug fixes
• documentation improvements

---

License

Apache-2.0 (see LICENSE)

---

Community

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.