Daemon (astromeshd)

astromeshd is the daemon process that turns the Astromesh library into a long-running system service. It bootstraps the runtime, starts the API server, and integrates with process supervisors like systemd.

What It Does

The daemon wraps AgentRuntime with process management concerns:

• Loads configuration from disk
• Bootstraps the full runtime (agents, providers, memory, tools)
• Starts the FastAPI/Uvicorn HTTP server
• Writes a PID file for process management
• Sends readiness notification to systemd
• Handles graceful shutdown on SIGTERM/SIGINT

Startup Sequence

flowchart TB
    start["astromeshd started"]
    s1["`**1. Find config dir**
    --config flag > /etc/astromesh > ./config/`"]
    s2["`**2. Read runtime.yaml**
    Global settings: port, log level, providers`"]
    s3["`**3. Bootstrap runtime**
    Scan agents/, load channels, wire services`"]
    s4["`**4. Start API server**
    Uvicorn on configured host:port`"]
    s5["`**5. Write PID file**
    /var/lib/astromesh/astromeshd.pid`"]
    s6["`**6. Notify systemd**
    sd_notify(READY=1)`"]
    serving["Serving requests"]
    start --> s1
    s1 --> s2
    s2 --> s3
    s3 --> s4
    s4 --> s5
    s5 --> s6
    s6 --> serving

CLI Flags

Flag	Default	Description
--config PATH	(auto-detect)	Explicit path to configuration directory
--port PORT	runtime.yaml, else 8000	Port for the HTTP API server
--host HOST	runtime.yaml, else 0.0.0.0	Bind address for the HTTP server
--log-level LEVEL	info	Logging level: debug, info, warning, error
--pid-file PATH	astromeshd.pid in the platform data dir	Path to write the PID file
--foreground	off	Run in foreground mode, without init-system integration

Examples

# Start with defaults (auto-detect config)
astromeshd

# Explicit config directory and debug logging
astromeshd --config /etc/astromesh --log-level debug

# Custom port and PID file
astromeshd --port 9000 --pid-file /tmp/astromesh.pid

Config Auto-Detection

When --config is not provided, the daemon searches for a configuration directory in this order:

Priority	Path	Typical Use
1	--config flag value	Explicit override
2	$ASTROMESH_CONFIG_DIR	Environment variable override
3	/etc/astromesh/	System-wide installation (Linux packages)
4	./config/	Local development, Docker containers

The first path that exists and contains a runtime.yaml file is used. If none is found, the daemon exits with an error.

PID File

The daemon writes its process ID to a PID file after the API server is ready. This enables process managers and init systems to track and signal the process.

Default location: astromeshd.pid in the platform data directory — /var/lib/astromesh/astromeshd.pid on Linux, /Library/Application Support/Astromesh/data/ on macOS, %ProgramData%\Astromesh\data\ on Windows.

The PID file is removed on graceful shutdown. If the daemon crashes, a stale PID file may remain — astromeshd checks for and cleans up stale PID files on startup.

systemd Integration

The daemon integrates with systemd using the sd_notify protocol.

Example unit file (/etc/systemd/system/astromesh.service):

[Unit]
Description=Astromesh Agent Runtime
After=network.target postgresql.service redis.service
Wants=postgresql.service redis.service

[Service]
Type=notify
ExecStart=/usr/bin/astromeshd --config /etc/astromesh
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
RestartSec=5
User=astromesh
Group=astromesh
RuntimeDirectory=astromesh
PIDFile=/var/lib/astromesh/astromeshd.pid

[Install]
WantedBy=multi-user.target

systemd Feature	Support
Type=notify	Yes — daemon sends READY=1 once agents are loaded, just before the API server starts listening
ExecReload	SIGHUP reloads agents and RAG from disk between RELOADING=1 and READY=1 (node v0.1.5+); runtime.yaml and providers need a restart
Restart=on-failure	Automatic restart on non-zero exit
WatchdogSec	Yes — the daemon pings WATCHDOG=1 every half of WatchdogSec from its event loop (node v0.1.4+); a hung loop stops pinging and systemd restarts it

Filesystem Layout

Path	Description
/usr/bin/astromeshd	Daemon binary (installed via APT/pip)
/usr/bin/astromeshctl	CLI binary
/etc/astromesh/	System configuration directory
/etc/astromesh/runtime.yaml	Global runtime configuration
/etc/astromesh/agents/	Agent YAML definitions
/etc/astromesh/channels.yaml	Channel adapter configuration
/var/lib/astromesh/astromeshd.pid	PID file
/var/log/astromesh/	Log files (when file logging is enabled)
/var/lib/astromesh/	Persistent data (vector stores, episodic logs)

Graceful Shutdown

On receiving SIGTERM or SIGINT:

1. Stop accepting new requests
2. Wait for in-flight requests to complete (30-second timeout)
3. Close MCP server connections
4. Flush pending memory writes
5. Remove PID file
6. Exit with code 0