Starting agentd

agentd is the daemon that manages all agents. It must be running before you can use ash or spawn any agents.

Starting the Daemon

# Development (foreground, with logging)
cargo run --bin agentd

# Or, if you built with --release
./target/release/agentd

# With verbose tracing
RUST_LOG=debug cargo run --bin agentd

agentd listens on a Unix domain socket. Default path: /run/agentd/agentd.sock

To use a custom socket path:

agentd --socket /tmp/my-agentd.sock

Then tell ash to use the same socket:

ash --socket /tmp/my-agentd.sock list

Verifying the Daemon is Running

ash ping
# Output: pong

ash status
# Output: daemon status, agent count, uptime

agentd also starts an HTTP API gateway on 127.0.0.1:8080 by default. The gateway exposes all agent management operations over REST, allowing external services and CI pipelines to interact with the daemon without a direct Unix socket connection.

Verify it is running:

curl http://127.0.0.1:8080/health
# {"status":"ok","version":"...","uptime_secs":42}

To change the bind address:

AGENTD_API_ADDR=0.0.0.0:9090 cargo run --bin agentd

See API Gateway for the full HTTP API reference, authentication setup, and CORS configuration.

Stopping the Daemon

Send SIGTERM or SIGINT (Ctrl+C in the foreground). agentd will:

Transition all running agents to Terminate
Flush the audit log
Release all secrets from memory (zeroized)
Exit cleanly

Log Output

agentd uses structured logging via the tracing crate. Control verbosity with RUST_LOG:

RUST_LOG=info   agentd   # default: info-level structured events
RUST_LOG=debug  agentd   # verbose: all tool dispatches, IPC frames
RUST_LOG=trace  agentd   # very verbose: internal state transitions

Running as a System Service

For production use, run agentd as a systemd service. Example unit file:

[Unit]
Description=Scarab-Runtime Agent Daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/agentd
Restart=on-failure
Environment=RUST_LOG=info
Environment=OPENROUTER_API_KEY=sk-or-...

[Install]
WantedBy=multi-user.target

sudo cp etc/systemd/agentd.service /etc/systemd/system/
sudo systemctl enable --now agentd

Scarab-Runtime Documentation