Astromesh Node

Astromesh Node is the native system-level deployment of Astromesh. It installs the astromeshd daemon and astromeshctl CLI as a first-class service on your operating system — integrating with systemd on Linux, launchd on macOS, and Windows Service Manager on Windows.

Node is a way to run the runtime — not a container

Astromesh Node is one of several parallel ways to bring up the same Astromesh runtime, and it runs it as a native operating-system service — not inside Docker. Docker, Helm / Kubernetes, the OS appliance, and Orbit are sibling deployment methods that all run the same astromeshd daemon and expose the same REST API. Reach for Node when you want the runtime supervised by systemd / launchd / Windows Service directly on a host — bare metal, VM, or edge — with no containers.

What is Astromesh Node?

Astromesh Node packages the Astromesh runtime into platform-native installation artifacts:

• Linux (Debian/Ubuntu) — .deb package with APT integration and systemd unit
• Linux (RHEL/Fedora/CentOS) — .rpm package with systemd unit
• macOS — .tar.gz with install script and launchd plist
• Windows — .zip with PowerShell installer and Windows Service registration

Each platform installs the same two binaries — astromeshd (the daemon) and astromeshctl (the CLI) — along with a platform-appropriate service manager integration.

Key Features

System Service Integration

Astromesh Node runs as a supervised OS-level service:

• Linux: systemd Type=notify, Restart=on-failure, watchdog health checks, journald logging
• macOS: launchd KeepAlive=true, stdout/stderr to /Library/Logs/Astromesh/
• Windows: Windows Service (astromeshd), registered with the bundled astromeshd-service.py wrapper

CLI Management

astromeshctl provides a unified CLI across all platforms:

astromeshctl status          # Daemon status table
astromeshctl init            # Interactive configuration wizard
astromeshctl doctor          # Health diagnostics
astromeshctl agents list     # List loaded agents
astromeshctl providers list  # List configured providers
astromeshctl config validate # Validate config files

Starting, stopping and tailing logs go through the platform service manager (systemctl, launchctl, Start-Service) — see Service control.

4 Node Roles

The astromeshctl init wizard offers 4 roles, each backed by a profile that controls which services activate on the node:

Role	Services	Use Case
full	All services	Single-node, everything on one machine
gateway	api, channels, observability	Public entry point, routes to workers
worker	api, agents, tools, memory, rag, observability	Agent execution node
inference	api, inference, observability	Dedicated LLM inference

Cross-Platform

The same runtime.yaml configuration works identically on all platforms. Filesystem paths are normalized per OS (see Configuration).

Comparison with Other Deployment Methods

Method	Best For	OS Integration	Orchestration
Astromesh Node	Single-server production, edge, on-prem	Native service	Platform service manager
From Source	Development, contributing	None	Manual
Docker Single Node	Containerized, CI/CD	Docker daemon	Docker Compose
Helm / Kubernetes	Multi-node, cloud-native	None	Kubernetes
Astromesh Orbit	Managed cloud	None	GCP Cloud Run

Choose Astromesh Node when:

• You want a production-ready deployment without containers or Kubernetes
• You need the daemon to start automatically on boot and restart on failure
• You are deploying to a bare-metal server, VM, or edge device
• You prefer CLI-based management over container tooling

Architecture

Astromesh Node installs the following components:

astromeshd          — Agent runtime daemon (HTTP API, agent execution, model routing)
astromeshctl        — CLI for service management and configuration
runtime.yaml        — Platform-aware config (services, api, providers, memory)
*.agent.yaml        — Agent definitions (YAML, same schema as Docker/K8s deployments)

The daemon exposes the same REST API (/v1/agents/{name}/run, /v1/ws/agent/{name}, etc.) regardless of platform. Existing integrations and SDKs work without modification.

Next Steps

• Quick Start — Install and run in under 5 minutes
• Linux (Debian/Ubuntu) — Full Debian/Ubuntu install guide
• Linux (RHEL/Fedora) — RPM-based Linux guide
• macOS — macOS install guide
• Windows — Windows install guide
• Configuration — runtime.yaml reference and profiles
• CLI Reference — Full astromeshctl command reference