Installation

Astromesh can be installed from source for development, pulled as a Docker image for containerized deployments, or installed as a native system service via Astromesh Node on Linux (Debian/Ubuntu, RHEL/Fedora), macOS, and Windows.

Prerequisites

Requirement	Version	Notes
Python	3.12+	Required for source installs
uv	Latest	Python package manager (install guide)
Git	Any recent	To clone the repository
Docker	24+	Optional, for containerized deployment
Rust toolchain	1.75+	Optional, for native extensions (5-50x speedup on CPU-bound paths)

From Source (Development)

This is the recommended method for development, experimentation, and contributing to Astromesh.

1. Clone the repository

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

2. Install dependencies

Install the base package:

uv sync

Or install with specific optional extras depending on your needs:

uv sync --extra all    # Everything — recommended for getting started

The following optional extras are available:

Extra	What It Adds
redis	Redis memory backend (conversational memory, caching)
postgres	PostgreSQL backend (episodic memory, pgvector)
sqlite	SQLite backend (lightweight local memory)
chromadb	ChromaDB vector store for semantic memory
qdrant	Qdrant vector store for semantic memory
faiss	FAISS vector store for local semantic memory
embeddings	Sentence-transformers for local embedding generation
onnx	ONNX Runtime provider for model inference
ml	ML training and fine-tuning utilities
observability	OpenTelemetry SDK, Prometheus exporter
mcp	Model Context Protocol client and server support
all	All of the above

You can combine extras as needed:

uv sync --extra redis --extra postgres --extra mcp

3. Verify the installation

Run the test suite to confirm everything is working:

uv run pytest -v

Expected output:

==================== test session starts ====================
platform linux -- Python 3.12.x, pytest-8.x.x, pluggy-1.x.x
configfile: pyproject.toml
plugins: respx-0.x.x, anyio-4.x.x, asyncio-0.x.x
asyncio: mode=auto
collected XX items

tests/test_api.py::test_health PASSED
tests/test_api.py::test_run_agent PASSED
tests/test_runtime.py::test_bootstrap PASSED
...
==================== XX passed in X.XXs ====================

4. (Optional) Build Rust native extensions

For 5-50x speedup on CPU-bound code paths:

pip install maturin
maturin develop --release

Verify the extensions loaded:

uv run python -c "from astromesh._native import fast_router; print('Native extensions loaded')"

Native extensions loaded

Without the Rust extensions, Astromesh falls back to pure Python automatically. You can also force the Python fallback at runtime by setting ASTROMESH_FORCE_PYTHON=1.

Docker Image

Pull the official Astromesh image:

docker pull monaccode/astromesh:latest

Run with environment-based configuration:

docker run -d \
  --name astromesh \
  -p 8000:8000 \
  -e ASTROMESH_LOG_LEVEL=info \
  -e OLLAMA_ENDPOINT=http://host.docker.internal:11434 \
  -v ./config:/etc/astromesh \
  monaccode/astromesh:latest

Verify the container is running:

curl http://localhost:8000/v1/health

{
  "status": "healthy",
  "version": "0.10.0",
  "agents_loaded": 3,
  "uptime_seconds": 12.4
}

For full Docker deployment guides including Docker Compose with Ollama, PostgreSQL, Redis, and the observability stack, see the Docker Single Node deployment guide.

Debian Package (Linux)

For Debian and Ubuntu systems, Astromesh is available as a .deb package that installs the daemon, CLI, and systemd service.

1. Download package from GitHub Releases

curl -LO https://github.com/monaccode/astromesh/releases/latest/download/astromesh_<VERSION>_amd64.deb

2. Install

sudo apt install ./astromesh_<VERSION>_amd64.deb

3. Verify the installation

astromeshctl status

Expected output:

Astromesh Runtime Status
========================
Daemon:     active (running)
PID:        1842
Uptime:     0h 2m 14s
Config:     /etc/astromesh/
Agents:     3 loaded, 3 healthy
API:        http://127.0.0.1:8000

The package installs:

Component	Location
Daemon binary	/usr/bin/astromeshd
CLI binary	/usr/bin/astromeshctl
Configuration	/etc/astromesh/
State data	/var/lib/astromesh/
Logs	/var/log/astromesh/
systemd unit	/etc/systemd/system/astromeshd.service

For detailed production configuration including systemd (Linux), launchd (macOS), and Windows Service, see the Astromesh Node documentation.

Note: A public APT repository URL is not available yet. Until then, install from GitHub Releases.

Verify Installation

Regardless of your installation method, you can verify that Astromesh is running with a health check:

curl http://localhost:8000/v1/health

Expected response:

{
  "status": "healthy",
  "version": "0.10.0",
  "agents_loaded": 3,
  "uptime_seconds": 42.7
}

A "status": "healthy" response confirms the runtime has started, loaded its configuration, and is ready to serve agent requests.

Next Steps

With Astromesh installed, head to the Quick Start guide to run your first agent in under 5 minutes.