Cryptographic host identity
Public identity material identifies a peer; verified fingerprints and pinned keys establish local trust.
man/technology
A node on your machine.
Raven separates identity, encrypted envelopes, and transport. The terminal controls the node; a supported carrier connects it to a peer.
RVN1: identity, envelope, carrier.
RVN1 specifies a signed envelope and identity model that supported Raven hosts can use across multiple carriers.
One envelope across supported paths
The host seals the payload before transmission. Optional relays can forward the envelope without receiving the endpoint’s decryption keys.
Protocol and implementation
A public specification is not a promise that every carrier or profile is implemented in every build. Use the current conformance and implementation notes.
system/components
One protocol. Clear responsibilities.
The terminal build lives in the Rust workspace. These components keep the host, the command interface, and the wire format distinct.
raven-core
Local identity, addresses, envelope processing, ATSAM primitives, routing policy, and queue components.
raven-node
The receiving service and authenticated peer path, local control interfaces, and explicit bridge-pull support. A node runs on a host that its peers can reach.
raven terminal
The CLI for identity, contacts, messaging, inbox, and status. The Rust package is ash; raven and ash are executables built from the same CLI code.
RDAP companion
Agent task delegation through A2A, with separate identity and carrier configuration. Integration with the production node’s protected identity and encrypted session path is incomplete.
transport/architecture
Multiple carriers. One envelope.
Raven hosts can use multiple transports. A transport hierarchy describes the architecture; availability follows the build and the host.
[ your machine ]
│
RAVEN NODE
│ RVN1 signed envelope
│
├── Internet P2P
│ libp2p · experimental
│
├── Local network
│ LAN / direct peer
│
└── Optional local transport
Bluetooth · adapter required
Internet P2P · libp2p
The architecture includes peer discovery and encrypted peer-to-peer streams over libp2p. Full DHT, relay coordination, and hole punching across real NATs remain experimental in the terminal path.
Local network · direct peer
The current CLI dials a verified contact’s secure LAN endpoint. Reachable hosts communicate directly without a Raven-operated central messaging service.
Optional local transport · Bluetooth
Bluetooth can carry RVN1 envelopes where a compatible adapter is available. Real headless GATT support is not complete in raven-node; the CI BLE adapter is a mock. Servers can run Raven without Bluetooth.
transport/forwarding
A Raven node can act as a blind relay when enabled.
RVN1 forwarding is designed to move the same sealed payload between carriers. A relay is a host participating in the configured path.
Store and forward
Queues, bounded replication, hop limits, expiration, and duplicate handling support delayed forwarding. These controls do not guarantee that a reachable route exists.
Explicit bridge support
Authenticated bridge-pull clients are available. Automatic production A→B→C discovery is not connected to the CLI send path; a bridge harness is evidence for that harness.
Optional Bluetooth
Bluetooth requires suitable hardware and a compatible carrier. The headless node’s mock adapter is useful for software tests but is not evidence of physical GATT operation.
security/session
Authenticate before sending.
The normal terminal node refuses to originate a message without the supported authenticated session setup. Unsafe lab profiles are not a production substitute.
Verify the public identity
Compare the peer’s fingerprint through a trusted channel and pin the public key. An @tag is a local convenience, not an independent trust authority.
Seal locally on the host
Payload protection happens at the endpoints before the envelope enters a carrier. Relay code is not entrusted with endpoint decryption keys.
Match the supported profile
ATSAM specifications cover more than the current terminal implementation. Full ML-KEM pairing and post-quantum ratchet interoperability have separate conformance and release gates.
interface/commands
Run Raven from your shell.
These commands use the existing raven executable. Install prerequisites and follow the node setup guide for your operating system.
git clone https://github.com/Ahmadreza-Arezehgar/RAVEN.git cd RAVEN/node cargo build --locked --release -p ash --bin raven cargo run --release -p ash --bin raven -- --help
The executable is created in the workspace target/release directory. Add that directory to your PATH, or invoke the executable by its path. Windows uses raven.exe.
Identity and contacts
raven init · raven whoami · raven contact add --help · raven contact list
Listen, chat, inspect
raven listen · raven send --contact @alice --chat · raven inbox · raven status
Before a conversation
Both hosts need compatible identities, pinned peer public details, and a reachable listener. Use raven contact add --help to supply the public address, key, fingerprint, local tag, and LAN dial address.
communication/agents
Signed tasks are a separate security boundary.
RDAP verifies trusted requests and signed task envelopes. Its current keys, state, and carriers remain separate from Raven Node.
HTTP, HTTPS, and Git
Direct A2A requests are signed. HTTP needs HTTPS or another protected layer for confidentiality. A Git carrier depends on a configured shared repository and its access controls.
Experimental mailbox
The optional Raven swarm mailbox adapter carries signed plaintext and is disabled by default. It does not provide the production node’s end-to-end confidentiality.
Configured model providers
The operator selects a local or hosted model. Task text and permitted project context may be sent to that provider; a peer signature does not change the provider’s data handling.
linux / windows / macos
Terminal native. By design.
Raven is terminal-native and targets Linux, Windows, and macOS. The CLI is the intended product interface. Backend initialization and service readiness differ by platform; see the installation FAQ.
Linux
Source-build the CLI for a shell or plain TTY. Fresh protected identity creation on GNU/Linux remains gated. A headless host needs a supported secure-store configuration; Bluetooth is optional.
Windows
Clone the repository, build the Rust workspace, and run Raven directly from PowerShell or Windows Terminal.
macOS
Run the same Raven CLI from Terminal.app, iTerm2, or any compatible shell. The protocol and identity model remain the same across macOS, Linux, and Windows.
Communication between operating-system hosts.
Raven is designed to let humans, machines, and software agents establish authenticated, encrypted communication without a mandatory central messaging service.
Host identity and explicit peers
Generate identity locally and verify the peer that will receive a message or task.
Multiple transports and optional relays
Support direct peers, encrypted forwarding, and degraded-network operation through implemented carriers.
Human and machine communication
Make the CLI a stable interface for people and hosts. RDAP agent exchange is part of the direction; its shared identity and encrypted node integration are not yet complete.
An open protocol and reviewable implementation
Publish specifications, source, and test evidence. Name the implementation and validation limits of every supported path.
engineering/evidence
Read the implementation boundary.
Software checks establish only the behavior they exercise. Real network traversal, physical Bluetooth, cryptographic interoperability, and independent security review need their own evidence.