loa-core

Lightweight Observability Agent Core - A Rust library for building observability agents with proper supervision and actor-based architecture.

Features

• Actor-based architecture using ractor
• Supervised agent lifecycle management
• Ed25519 identity and X25519 key exchange for secure communication
• Built-in metrics collection and downsampling
• HTTP client with middleware support
• Configurable heartbeat and alerting

Installation

Add to your Cargo.toml:

[dependencies]
loa-core = "1.2"

Usage

Starting the Agent

use loa_core::Agent;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let agent = Agent::builder()
        .storage_path("/var/lib/loa")
        .build()
        .await?;

    agent.run().await?;
    Ok(())
}

Reading Agent Info (Lightweight)

Read agent metadata without starting the full runtime - useful for CLI tools and status checks:

use loa_core::AgentInfo;
use std::path::Path;

fn main() -> anyhow::Result<()> {
    let info = AgentInfo::read(Path::new("/var/lib/loa"))?;

    println!("Peer ID: {}", info.peer_id);
    println!("Dashboard: {}", info.dashboard_url);

    if let Some(name) = &info.name {
        println!("Name: {}", name);
    }

    Ok(())
}

AgentInfo provides:

• peer_id - Unique agent identifier
• name - Human-readable 3-word name (e.g., conscious-jade-mongoose), None if not registered
• storage_path - Path to agent data directory
• dashboard_url - Direct link to agent dashboard
• ed25519_public_key_hex / x25519_public_key_hex - Public keys
• claim_token - Workspace claim token (if claimed)

Storage Format

Agent data is stored in a single agent.toml file:

[identity]
ed25519_secret = "base64-encoded-64-bytes"
x25519_secret = "base64-encoded-32-bytes"

[registration]
name = "conscious-jade-mongoose"
claim_token = "jd7f331ecpb7xhgmrdzch6m13n7yppkf"

The library automatically migrates from the legacy format (separate agent_id.key, claim_token, and agent_name files) on first load.

License

MIT