Skip to main content

Daemon Control Commands

The Lattice daemon is the heart of the system—a long-running background process that orchestrates everything else. It manages your conversation sessions, coordinates agent execution, maintains connections to LLM providers, and ensures your data persists across restarts. Understanding how to control this daemon process is fundamental to working with Lattice effectively.

Understanding the Daemon

Think of the daemon as a persistent service that runs quietly in the background, waiting for commands from client tools like the CLI or your applications. When you start it, the daemon creates a Unix socket for fast local communication, loads your configuration to understand which LLM providers to use, and initializes its internal state to track sessions and agents. Once running, it stays active until explicitly told to stop or until the system shuts down.

The daemon handles all the complex work of maintaining provider connections, queueing tasks, persisting data to disk, and coordinating concurrent operations. From your perspective as a user, you interact with the daemon through simple commands, and it handles all the intricate details behind the scenes.

Controlling the Daemon

Starting the Daemon

When you want to begin working with Lattice, the first step is getting the daemon running. The lattice-ctl daemon start command launches the daemon process in the background, allowing it to run independently while you continue using your terminal for other work.

bash
lattice-ctl daemon start

The daemon checks for existing processes to prevent duplicates, creates the ~/.lovelace/lattice/ directory structure, loads your configuration and saved state, and establishes a Unix socket for client connections.

Running in Foreground Mode

If you need to see what the daemon is doing during startup—perhaps for debugging or to understand initialization errors—you can run it in foreground mode instead. The --foreground flag keeps the daemon attached to your terminal, printing log output directly where you can see it:

bash
lattice-ctl daemon start --foreground

This mode is invaluable when troubleshooting configuration problems or understanding why the daemon might be failing to start. You'll see detailed logs about which config file is being loaded, which providers are being initialized, and any errors that occur during the startup sequence.

Using Custom Configuration

Sometimes you need to use a custom configuration file instead of the default location. Maybe you're testing different provider setups, or you maintain separate configurations for development and production. The --config flag lets you point the daemon to a specific configuration file:

bash
lattice-ctl daemon start --config /path/to/custom-config.toml

When the daemon starts with a custom config, it uses that file exclusively, ignoring the default location at ~/.lovelace/lattice/config.toml. This makes it easy to maintain multiple configurations side by side without interference.

Common Startup Issues

Common startup problems usually fall into a few categories. If you see "Daemon already running" errors, another instance is still active—you'll need to stop it before starting a new one. Permission errors typically mean the daemon can't write to ~/.lovelace/lattice/, which you can fix by ensuring the directory is writable by your user. If the daemon binary itself can't be found, the PATH isn't configured correctly—reinstalling usually resolves this.

Stopping the Daemon

When you're finished working or need to restart the daemon to apply configuration changes, you'll want to stop it cleanly. The lattice-ctl daemon stop command tells the running daemon to shut down gracefully:

bash
lattice-ctl daemon stop

Graceful shutdown prevents data loss by completing a careful sequence: the daemon stops accepting new connections, waits for in-flight requests to finish, persists all session and agent state to the SQLite database, and cleans up resources like sockets and PID files. When you restart, the daemon restores all sessions exactly as they were, letting you resume work seamlessly.

Monitoring the Daemon

Checking Daemon Status

Before running any other commands, you often want to verify whether the daemon is actually running. The lattice-ctl daemon status command provides this basic information:

bash
lattice-ctl daemon status

When the daemon is running, you'll see its status displayed along with the process ID and socket location. When it's not running, the command reports that fact clearly. This simple check is particularly useful in scripts where you need to verify the daemon's state before proceeding with other operations.

Getting Detailed Status

Beyond just checking if the daemon is alive, you often want to know how it's performing and what it's doing. The lattice-ctl status command provides a comprehensive view of daemon activity:

bash
lattice-ctl status

This shows you the daemon version, how long it's been running, and current activity metrics like the number of active agents, tasks, and sessions. These metrics help you understand the daemon's workload and can guide decisions about when to restart or how to scale your usage.

Quick Health Checks

For quick health verification, the lattice-ctl ping command provides the fastest possible check:

bash
lattice-ctl ping

This sends a simple "are you there?" message to the daemon and waits for a response. If you see "pong" come back, the daemon is alive and responsive. This minimal health check is perfect for monitoring scripts that need to verify the daemon is working without retrieving detailed status information.

Understanding Health Checks

Sometimes status metrics alone don't tell you what's wrong. The lattice-ctl health command provides component-level health information that breaks down the daemon's status into individual subsystems:

bash
lattice-ctl health

The health response shows the overall daemon status along with the health of specific components like the IPC server, agent registry, task queue, and database connection. When something goes wrong, this granular view helps you pinpoint exactly which part of the system is failing, making troubleshooting much more targeted and effective.

Graceful Shutdown via IPC

While lattice-ctl daemon stop sends a signal to the process externally, you can also request shutdown through the daemon's normal communication channel. The lattice-ctl shutdown command sends a shutdown request via the IPC socket:

bash
lattice-ctl shutdown

Both approaches—signal-based and IPC-based shutdown—result in the same graceful shutdown sequence. The daemon finishes current work, saves state, and exits cleanly. The main difference is in how the shutdown is initiated: signals come from the operating system level, while IPC shutdown requests come through the daemon's normal request handling path. Either method is safe to use, so choose whichever fits your workflow better.

Running the Daemon as a System Service

For regular use, you'll want the daemon to start automatically when your system boots rather than manually starting it each time. Lattice integrates with your operating system's service manager to make this seamless. On macOS, this means launchd. On Linux, it typically means systemd. The service installation commands handle all the platform-specific details for you.

To install the daemon as a system service, use:

bash
lattice-ctl service install
lattice-ctl service start

Once installed as a service, the daemon starts automatically on boot and runs continuously in the background. You can still control it using the normal daemon commands, but now it's integrated into your system's service management infrastructure. This means you can view logs through standard system tools, monitor it alongside other services, and rely on it to be available whenever you need it.

Practical Workflows

Understanding individual commands is useful, but seeing how they work together in real scenarios helps build intuition. Let's walk through some common situations.

Restarting the Daemon

When you need to restart the daemon to apply configuration changes, first stop the running instance with lattice-ctl daemon stop. Wait a moment for the shutdown to complete, then start a fresh instance with lattice-ctl daemon start. The new daemon process will load the updated configuration and resume with all your saved sessions and agent state intact.

Debugging Issues

For debugging issues, running the daemon in foreground mode gives you immediate visibility into what's happening. Stop any background daemon with lattice-ctl daemon stop, then start in foreground mode with lattice-ctl daemon start --foreground. You'll see detailed logs stream to your terminal, showing exactly what the daemon is doing. This real-time feedback makes it much easier to diagnose configuration problems, provider connection issues, or unexpected behavior. When you're done debugging, just press Ctrl+C to stop the foreground daemon and return to background operation.

Monitoring Daemon Health

Monitoring daemon health can be automated with simple scripts. A monitoring loop can periodically ping the daemon and restart it if it's not responding. This kind of defensive monitoring ensures the daemon stays available even if something unexpected causes it to crash or hang.

Configuration and Environment

The daemon's behavior is controlled by its configuration file, typically located at ~/.lovelace/lattice/config.toml. This file specifies which LLM providers to use, sets resource limits, configures logging, and controls various operational parameters. When starting the daemon, it automatically loads this configuration and uses it to initialize all subsystems.

Environment variables provide another way to influence daemon behavior without modifying configuration files. Setting LATTICE_CONFIG_PATH tells the daemon to load configuration from a different location. The LATTICE_SOCKET variable changes where the daemon creates its Unix socket, which can be useful for running multiple isolated instances. For logging, LATTICE_LOG_LEVEL controls how verbose the daemon's output is—setting it to "debug" produces detailed diagnostic information, while "warn" keeps output minimal.

Troubleshooting Daemon Issues

When the daemon won't start, the problem usually falls into one of a few categories. If you see errors about the daemon already running, check whether a previous instance is still alive. Sometimes a crash leaves behind a stale PID file even though no process is running—removing the PID file at ~/.lovelace/lattice/daemon.pid often resolves this.

Permission errors indicate the daemon can't access necessary files or directories. Ensure ~/.lovelace/lattice/ exists and is writable by your user. On some systems, security policies or filesystem restrictions can prevent Unix socket creation—check your system logs for hints about what's being blocked.

If the daemon starts but immediately crashes, run it in foreground mode to see error messages. Often this reveals configuration problems like invalid TOML syntax, missing provider credentials, or unreachable LLM endpoints. The error messages will guide you toward the specific configuration that needs fixing.

Related Documentation

This guide covers daemon lifecycle management, but several related topics provide additional context. The session management guide explains how the daemon stores conversation state. The agent management guide describes how autonomous agents run within the daemon process. The provider configuration guide covers setting up the LLM providers the daemon connects to. For general configuration questions, consult the configuration overview, which explains all available settings and how they interact.