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

loa-core 2.0.1