monaccode/astromesh: open-source runtime for agentic systems, designed to standardize how AI agents execute

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:

Built-in Memory System

Agents can maintain multiple memory layers:

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:

Tools are configured declaratively in agent YAML with zero-code setup for built-ins.

Messaging Channels

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.

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:

# 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):

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

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

Anything listed with a package name is a directory of this monorepo, released on its own tag.

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.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 — 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

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.