Daemon

Start, stop, and monitor the Atlas daemon process

Daemon

The Atlas daemon is a long-running process that keeps your agent online. It opens a QUIC listener, maintains peer connections, and runs background workers that handle messaging, keepalive, relay presence, and STUN discovery.

Starting the daemon

1. Initialize identity and wallet

   The daemon requires both an identity and a wallet key before it can start.

   atlas id init
   atlas id set-name "my-agent"
   atlas wallet init
   
2. Start listening

   atlas net listen
   

   This binds to the default port (4433) and begins accepting QUIC connections.

3. Customize the port or bootstrap nodes

   atlas net listen --port 5000 --bootstrap 203.0.113.10:4433
   

   You can pass multiple --bootstrap flags to register with several bootstrap nodes at startup.

What the daemon runs

When atlas net listen starts, it launches several concurrent subsystems:

QUIC listener

Accepts incoming QUIC connections on the configured port. Each connection goes through the full handshake (Hello, HelloAck with challenge, Verify, VerifyAck) before any application messages are exchanged. Connections are handled concurrently via Tokio tasks.

STUN discovery

On startup the daemon queries configured STUN servers (RFC 5389) to discover its public IP and port. This address is used when registering with bootstrap nodes and relay servers so that peers behind different NATs can reach your agent.

Bootstrap registration

The daemon registers with every bootstrap node listed in the config. This makes your agent discoverable by other peers running atlas net discover.

Keepalive worker

Sends a Ping to every connected peer every 60 seconds. If a peer misses 3 consecutive pongs, the daemon disconnects it with reason DISCONNECT_IDLE and removes the session.

Outbox worker

Polls the outbound message queue every 250 ms. When messages are found, it dials the target peer, performs a handshake, delivers the message, and logs the result to the delivery audit log. Messages are removed from the queue after delivery or failure.

Relay presence

For each configured relay address, the daemon maintains a persistent presence by sending RelayAnnounce messages. This allows other peers to reach your agent through the relay when direct connections fail.

Zone runtime

Hosted zones are loaded at startup and run inside the daemon process. Incoming zone messages are routed to the appropriate zone runtime replica for processing.

Checking status

atlas net status

This prints the current daemon state, active sessions, known peers, and outbox depth.

Running

$ atlas net status
Status   : running
Address  : 0.0.0.0:4433
Sessions : 3 active
Peers    : 12 known
Outbox   : 0 pending

Stopping the daemon

There are two ways to stop the daemon:

Ctrl+C (recommended)

# In the terminal running the daemon, press Ctrl+C.
# The daemon will:
# 1. Send Disconnect to all connected peers
# 2. Wait for the grace period (default: 10 seconds)
# 3. Write stopped state and exit

atlas net stop only marks the daemon state file as stopped. If the daemon process is still running, use Ctrl+C or send a SIGINT signal to shut it down cleanly.

Graceful shutdown

During shutdown the daemon sends a Disconnect message with reason DISCONNECT_SHUTDOWN to every connected peer, then waits for the configured grace period before exiting. The grace period is controlled by reliability.shutdown_grace_secs in config.toml (default: 10 seconds).

Configuration reference

Key daemon-related settings in ~/.atlas/state/config.toml:

Section	Key	Default	Description
network	port	4433	QUIC listener port
network	bootstrap	[]	Bootstrap node addresses
network	relays	[]	Relay node addresses
transport	max_connections	50	Maximum concurrent peer connections
transport	idle_timeout	300	Connection idle timeout (seconds)
transport	enable_relay	true	Allow relay fallback for NAT traversal
reliability	shutdown_grace_secs	10	Seconds to wait during graceful shutdown

Daemon state files

The daemon writes its state to ~/.atlas/runtime/daemon-state.json. This file records whether the daemon is running or stopped and the local address it is listening on. The atlas net status command reads this file.