Documentation

Stare Network provides identity infrastructure and secure networking for AI agents. This guide covers the core concepts, architecture, and APIs.

Quickstart

Get an agent connected to the Stare relay network in under 5 minutes.

pip install stare-sdk

from stare import Agent

# Connect to the relay network
agent = Agent(
    name="my-agent",
    relay="relay.stare.network:9999"
)

# Register and get an identity
identity = agent.register()
print(f"DID: {identity.did}")
print(f"Endpoint: {identity.endpoint}")

Installation

Python SDK

pip install stare-sdk

Rust SDK

[dependencies]
stare = "0.1"

Self-hosted relay

# Install the relay server
cargo install freehold-server

# Generate config
freehold-server example-config > /etc/freehold/server.toml

# Start the relay
freehold-server -c /etc/freehold/server.toml

Agent Identity

Every agent on the Stare network gets a decentralized identifier (DID) derived from its cryptographic key material. Identities are:

• Self-sovereign — agents control their own keys
• Verifiable — any party can verify an agent's identity without contacting a central authority
• Deterministic — the same key material always produces the same DID
• Hardware-backed — optional TEE attestation for high-assurance deployments

Relay Network

The Stare relay network enables agent-to-agent communication regardless of network topology. Agents behind NAT, firewalls, or carrier-grade NAT can communicate through the relay infrastructure.

Key features:

• XDP-accelerated forwarding — packets are forwarded at wire speed in the kernel's network driver, bypassing the entire network stack
• Automatic NAT traversal — port spray + bidirectional relay handles every NAT type
• Dual-path DNS — SVCB records let clients race direct and relay paths simultaneously
• Rate limiting — per-agent token bucket rate limiting in eBPF

Architecture

The Stare infrastructure consists of three layers:

• Data plane — eBPF/XDP programs that handle packet forwarding at wire speed. No userspace involvement for data path traffic.
• Control plane — Rust-based relay server that handles registration, authentication, DNS management, and NAT hole-punching coordination.
• Identity layer — Cryptographic identity primitives, credential issuance, and verification.

XDP Data Plane

The XDP (eXpress Data Path) program runs at the lowest level of the Linux networking stack — directly in the NIC driver. It processes packets before the kernel's network stack sees them, enabling:

• Sub-microsecond forwarding latency
• Millions of packets per second per core
• Zero-copy packet rewriting (SNAT + DNAT)
• Kernel-bypass rate limiting with token buckets

NAT Traversal

Stare handles NAT traversal automatically using a multi-strategy approach:

• Direct connection — if both agents have public IPs or permissive NAT, they connect directly
• Port spray — for predictable NAT port allocation, the relay coordinates a port spray (10,000 ports) to find the mapped port
• Bidirectional relay — for symmetric NAT or when spray fails, all traffic flows through the relay with full SNAT+DNAT at XDP speed

API Reference

Full API reference is available in the SDK documentation. Core endpoints:

POST   /v1/agents          # Register a new agent
GET    /v1/agents/:did     # Get agent info
POST   /v1/credentials     # Issue a credential
POST   /v1/verify          # Verify a credential

Configuration

The relay server is configured via TOML:

# /etc/freehold/server.toml
interface = "eth0"
port = 9999

[anycast]
primary_ip = "142.248.222.1"

[dns]
enabled = true
zone = "stare.network"

[limits]
max_ports_per_ip = 3