A Python and TypeScript implementation of the Aether (AT) protocol, a binary messaging system for autonomous agent communication optimized for AI agent frameworks.
Aether is a transport-agnostic, content-addressed messaging protocol optimized for machine-to-machine communication. Unlike JSON-based protocols, Aether uses FlatBuffers for zero-copy serialization and reduced bandwidth.
Key Features:
- Content-addressed events (Blake3 hashes) for deduplication
- Replaceable events for CRDT-style state synchronization
- Ephemeral events for real-time signals
- Capability-based delegation (macaroon-style)
- Tag-based multi-dimensional routing
- Ed25519 decentralized identity
See PRD.md for the complete product requirements and RFC.txt for the protocol specification.
+--------+ Event (signed) +--------+
| Agent | --------------------------------> | Relay |
|(Client)| <-------------------------------- | |
+--------+ Subscription Filter +--------+
|
v
Other Agents
git clone https://github.com/valinagacevschi/aether
cd aether# Install from PyPI (when available)
pip install aether-protocol
# Or install from source
cd sdk/python
pip install -e .Local import (no install):
export PYTHONPATH="$PWD/sdk/python"# Install from npm (when available)
npm install @aether-protocol/sdk
# Or install from source
cd sdk/typescript
npm install# Install relay server
cd relay/python
python -m venv .venv
source .venv/bin/activate
pip install -e .
# Run relay
python -m aether_relay.server --ws-port 9000 --quic-port 4433 --storage sqlite --storage-path data/relay.dbWebSocket is always enabled. QUIC is enabled when cert files exist.
See /Users/valentin.nagacevschi/dev/aether/relay/README.md for a full QUIC setup example.
git clone https://github.com/valinagacevschi/aether
cd aether
python -m venv .venv
source .venv/bin/activate
python -m pip install -e relay/python -e sdk/python
cd sdk/typescript && npm install && npm run build && cd ../..
cd relay/python
PYTHONPATH=. python -m aether_relay.server \
--ws-host 127.0.0.1 --ws-port 9000 \
--gateway nostr,http \
--nostr-port 7447 \
--http-port 8081 \
--http-ws-port 8082In another terminal:
source .venv/bin/activate
PYTHONPATH="$PWD/sdk/python" python integration-tests/examples/nostr_client_min.py
PYTHONPATH="$PWD/sdk/python" python integration-tests/examples/http_publish_sse.py
# TypeScript example (from repo root; needs SDK node_modules on NODE_PATH)
NODE_PATH=$PWD/sdk/typescript/node_modules npx tsx integration-tests/examples/ws_json_publish_subscribe.tsimport asyncio
import time
from aether import Client, compute_event_id, generate_keypair, sign
async def main():
client = Client()
await client.connect(["ws://127.0.0.1:9000"])
private_key, pubkey = generate_keypair()
content = b'{"name":"agent-1"}'
created_at = time.time_ns()
event_id = compute_event_id(
pubkey=pubkey,
created_at=created_at,
kind=1,
tags=[],
content=content,
)
event = {
"event_id": event_id.hex(),
"pubkey": pubkey.hex(),
"kind": 1,
"created_at": created_at,
"tags": [],
"content": content.decode("utf-8"),
"sig": sign(event_id, private_key).hex(),
}
await client.publish(event)
asyncio.run(main())import { AetherClient, computeEventId, generateKeypair, signEventId } from "@aether-protocol/sdk";
async function main() {
const client = new AetherClient();
await client.connect(["ws://127.0.0.1:9000"]);
const { privateKey, publicKey } = await generateKeypair();
const content = Buffer.from('{"name":"agent-1"}');
const created_at_ns = BigInt(Date.now()) * 1_000_000_000n;
const eventId = computeEventId({
pubkey: publicKey,
createdAt: created_at_ns,
kind: 1,
tags: [],
content,
});
const sig = await signEventId(eventId, privateKey);
await client.publish({
event_id: Buffer.from(eventId).toString("hex"),
pubkey: Buffer.from(publicKey).toString("hex"),
kind: 1,
created_at: created_at_ns.toString(),
tags: [],
content: content.toString("utf-8"),
sig: Buffer.from(sig).toString("hex"),
});
}
main();- 0-999 (IMMUTABLE): Permanent storage
- 10000-19999 (REPLACEABLE): Latest only per (pubkey, kind)
- 20000-29999 (EPHEMERAL): No storage, broadcast only
- 30000-39999 (PARAMETERIZED_REPLACEABLE): Latest per (pubkey, kind, d-tag)
- PyNaCl: Ed25519 signatures
- blake3: Content-addressed hashing
- flatbuffers: Zero-copy serialization
- cryptography: Noise-style upgrade (X25519 + AEAD)
- aioquic: QUIC transport (asyncio-native)
- websockets: WebSocket fallback
- py-libp2p: Gossipsub for relay mesh
- @noble/ed25519: Ed25519 signatures
- @noble/curves / @noble/ciphers / @noble/hashes: Noise-style upgrade (X25519 + AEAD)
- blake3: Content-addressed hashing (WASM)
- flatbuffers: Zero-copy serialization
- ws or node-quic: Transport (WebSocket/QUIC)
- libp2p: Gossipsub (Node.js only)
- Constant-time Ed25519 signature verification
- Replay protection via timestamp validation
- Content sandboxing (no execution of payloads)
- Optional Proof-of-Work for spam prevention
- Noise-style transport upgrade (X25519 + ChaCha20-Poly1305)
Implementation Strategy: "Python for infrastructure, idiomatic SDKs for developers"
- Relay: Python (asyncio-native, handles 100K+ TPS)
- Python SDK: Native Python (shares codebase with relay)
- TypeScript SDK: Native TypeScript with WASM crypto bundle
This approach ensures pip install and npm install work immediately while maintaining debuggability and ecosystem alignment with agent frameworks (LangChain, AutoGen, CrewAI, Vercel AI SDK, LangChain.js).
| Surface | Transport | Protocol | Status |
|---|---|---|---|
| Native Aether | WebSocket/QUIC | Aether messages (JSON/FlatBuffers) | Available |
| NOSTR Gateway | WebSocket | NIP-01 core (EVENT,REQ,CLOSE) |
Available |
| HTTP Gateway | REST + SSE + WebSocket | JSON | Available |
python -m build sdk/pythoncd sdk/typescript && npm install && npm run build && npm packPYTHONPATH=. python -m pytest relay/python/tests- Validate quickstarts in
integration-tests/examples/ - Tag and publish:
- Python:
py-vX.Y.Z - TypeScript:
ts-vX.Y.Z
- Python:
See LICENSE file.
Contributions welcome. Please read the RFC specification before submitting changes.