Arveil documentation¶
Arveil is a self-hosted, end-to-end encrypted messenger for families and small circles of trust. A Go relay moves encrypted envelopes; a Rust core on each device owns identity, MLS, local storage and recovery; Flutter apps for macOS and Android sit on top of that core. These pages explain how to run it, how it is designed and what has been verified.
Versión en español: es/README.md
Status (October 1, 2026). Beta 6, build 27 is published on GitHub, Homebrew and Google Play internal testing. It includes personal invitations, QR codes, attachment opening and experimental notifications without Google. The compatible relay is deployed in the test environment; the public relay/CLI binaries remain at v0.1.0, with their distributable upgrade tracked in #133.
M3b.5 physical-device and three-external-user acceptance remain open. The beta record separates publication from acceptance. There is no independent security audit; the platform record preserves actual results and limits. Each ADR declares its own status.
Where to start¶
| I want to… | Read |
|---|---|
| Install the app after an invitation | The website's step-by-step guide |
| Try Arveil | Install and try |
| Run a relay for my family | Running a realm · Rootless Podman · Cloudflare Tunnel |
| Build or package the apps | Client packages · Signed Android updates · Flutter client README |
| Understand the security | Threat model · Protocol · Architecture |
| Follow the apps | Phase 3b plan · Implementation record · Client design · Platform record |
| Contribute | Contributing guide · Security policy |
Document map¶
Using and operating¶
| Document | Contents |
|---|---|
| Install and try | Server, macOS and Android routes, current availability and installation acceptance |
| Running a realm | Install, addresses and tunnels, limits, health and metrics, backups, restore and upgrades |
| Rootless Podman | A private-network relay with SSH, Tailscale and persistent rootless Podman |
| Cloudflare Tunnel | Opening that private relay to the Internet through a tunnel and a local proxy that verifies client addresses |
| Client packages | Building, auditing and publishing the macOS ZIP and Android APK |
| Signed Android updates | The opt-in update check in the Android app: signing key, signed feed, publishing and what the app verifies |
| Personal invitations | User journey, owner setup, wire contract, verification and rollout gates |
Design¶
| Document | Contents |
|---|---|
| Architecture | Components, boundaries, deployment, access paths, scope and phases |
| Threat model | Assets, adversaries, what the server knows, conditional guarantees and invariants I-01 to I-13 |
| Protocol | Bootstrap, transport, MLS groups, durable delivery, frame catalog and recovery |
| Domain model | Entities, key lifecycle, server schema, local atomicity and state machines |
Decisions¶
| Record | Decision |
|---|---|
| ADR-001 | Go server and a secure Rust core |
| ADR-002 | MLS for conversations and devices |
| ADR-003 | A server trusted with neither content nor identity |
| ADR-004 | SQLite, the filesystem and a single server binary |
| ADR-005 | Cryptographic identity and authorized devices |
| ADR-006 | Local-first, recovery-first, explicit history |
| ADR-007 | Optional redundancy after V1; independent relays preferred |
| ADR-008 | Noise channel, signed endpoint list, access over LAN, tailnet, tunnel or Internet |
| ADR-009 | Flutter first for the apps (accepted) |
| ADR-010 | Distribution and signed, opt-in updates outside the app stores (accepted for Android; proposed for macOS) |
| ADR-011 | Names people choose for themselves, shared end to end with their conversations (proposed) |
| ADR-012 | QR codes and links to join, link devices and add contacts; verification as a separate, optional step (implemented) |
| ADR-013 | Realm roles and administration from the app, with the host as the last resort (proposed) |
Apps¶
| Document | Contents |
|---|---|
| Phase 3b plan | Milestones M3b.0 to M3b.8 and their acceptance criteria |
| Implementation record | What each change implemented, its evidence and its limits |
| Client design | Visual system, personalization and the redesign plan |
| Invitation onboarding plan | Current priority: one invitation from installation to the first conversation; dependencies, blockers and acceptance |
| Attachments and notifications | File viewing, local Mac alerts and the Android experiment without Google |
| Platform record | Dated acceptance runs: device, system, commit and result |
Plans, reviews and evidence¶
| Document | Contents |
|---|---|
| Phase plans 0 · 1 · 2 · 3 · 4 | Milestones, exit conditions and results of each completed phase |
| Viability review v0.3 | External-style review with verified references and open risks |
| MLS library comparison | The M0.5 spike behind choosing mls-rs |
| Demo transcript · Q3 capture | The Phase 0 demo run, and what a TLS-terminating proxy saw of the Noise channel (Q3) |
| Noise inside a Cloudflare Tunnel · No rooms table | Design notes (drafts) |
The sections below are the historical design record from September 2026. They explain how the design reached its current shape; the documents above describe what is true today.
Historical v0.4 design background¶
The application foundation and Flutter plan describe current status; the candidates and tasks below belong to the original proposal.
The chosen direction is Go + Rust, MLS, identity independent of the realm, delivery through opaque mailboxes, a carrier-independent Noise channel with a signed endpoint list, SQLite + filesystem and client-driven recovery. Flutter is the interface candidate; OpenMLS is the first candidate MLS library and mls-rs the alternative to evaluate. No library choice implies an audit of the application.
The details added in this edition —commit coordinator, direct authorization by the root key, HPKE envelope and initial retention values— are proposals to close ambiguities in the conversation, not previously confirmed decisions or MLS requirements.
Before freezing the protocol, the following must be resolved: transactional MLS persistence, commit authorization, signed serialization, device linking channel, archive and backup profile, revocation under partitions and bindings for the initial platforms. The documents indicate conservative behavior for those cases.
The current revision replaces the earlier proposals of a Rust backend with PostgreSQL by a Go server with SQLite. It does not include global federation, calls, blockchain, home-grown cryptography or a requirement for external data services.
The v0.3 edition incorporates, as a future and optional possibility, redundancy of the same realm across machines or households. ADR-007 collects alternatives, limits and evaluation criteria. Standalone remains the V1 profile; no cluster, load balancer or replication engine is selected or promised.
References and traceability¶
The source of intent is the conversation "Plantear arquitectura de idea", in particular its second proposal. Its figures on competitors, release dates and claims of superiority are not reproduced without verification.
Extension v0.4 — 2026-09-04: ADR-008 is added after finding that the previous design relied on end-to-end TLS for the confidentiality of sessions and capabilities and for the realm pin, which does not hold with Cloudflare Tunnel or other intermediaries that terminate TLS. Changes: Noise IK channel between device and realm inside WebSocket; the API moves from HTTP routes to CBOR frames; DeviceCredential replaces the Ed25519 transport key with an X25519 Noise key; the realm adds a Noise key and a signed RealmEndpointList; TLS remains as an optional layer; the LAN no longer needs certificates; ADR-007 adopts independent relays as the preferred direction. Documents at v0.4: README, ARCHITECTURE, THREAT_MODEL, PROTOCOL, DOMAIN_MODEL, ADR-007 and ADR-008. ADR-001 through ADR-006 do not change. The v0.3 review remains as a dated document; its actions on the coordinator, push on iOS and effort remain open.
Extension v0.3 — 2026-09-04: ADR-007 is added and linked from the architecture, threat model and ADR-004. Its redundancy references were consulted in the conversation before this extension; the technology choice is deferred.
Online review v0.2 — 2026-09-04: the official Go and Rust releases, the MLS/HPKE RFCs, the SQLite documentation and the OpenMLS and mls-rs repositories were consulted. This review replaces the v0.1 notice about lack of access. It confirms the Go + Rust + MLS + SQLite direction, but incorporates concrete requirements on durability, dependency selection and commit handling. It is not a code audit or an interoperability test.
Changes with respect to v0.1:
- Verified candidate toolchain versions: Go 1.27.1 and Rust 1.98.1; details and sources in ADR-001.
- SQLite: mandatory WAL-reset fix and explicit durability configuration; ADR-004.
- Core: distinguish compiled platforms from tested platforms and exclude sensitive debug features; ADR-001 and ADR-002.
- Protocol: separate prepared commit from accepted commit and specify loss/revocation of the coordinator; PROTOCOL.
Still open: pairing, the final coordination policy, the transactional provider, the concrete library versions and the archive/recovery format. The OpenMLS manual pages could not be retrieved; no capabilities are attributed to its API that we have not verified. The links to EdDSA, CBOR and SQLCipher are complementary references pending a specific review.
| Primary reference | Use and scope of review |
|---|---|
| RFC 9420 — MLS | Group protocol, epochs, KeyPackages and security |
| RFC 9750 — MLS Architecture | Responsibilities of the Authentication Service and Delivery Service |
| RFC 9180 — HPKE | Outer encryption per recipient; not person authentication on its own |
| RFC 8032 — EdDSA | Complementary reference: identity signatures |
| RFC 8949 — CBOR | Complementary reference: candidate deterministic serialization |
| OpenMLS / manual | README reviewed; manual not retrieved; candidate subject to integration |
| mls-rs | Alternative for comparing providers, platforms and persistence |
| SQLite WAL / synchronous / Online Backup API | Persistence and backup requirements; reviewed |
| Go releases / Rust 1.98.1 | Verified versions; project compatibility pending |
| SQLCipher | Complementary reference: integration and base version pending |
| Noise Protocol Framework | Device↔realm channel of ADR-008; IK pattern; snow (Rust) and flynn/noise (Go) implementations pending version pinning |
Our product decisions are not attributed to these standards: the identity model, the capabilities, the commit coordinator and the recovery flows are proposals of this application that require their own review.