Skip to main content

​
Overview

FOKS is a client-server system where multiple independent servers can federate — much like email or the Web. Users on one server can join teams on another server, and encrypted data can flow across server boundaries. The system has two main sides: a client running on your machine, and a server you connect to (either foks.app or your own).

​
Client Architecture

The client consists of a persistent agent and a one-shot CLI. This mirrors the design of ssh-agent. 
  foks (CLI)  ──────┐
                    │ Unix socket / named pipe
  git-remote-foks ──┤
                    │
              [ foks agent ]
                    │
              network (TLS)
                    │
              [ FOKS server ]

​
The agent

foks agent (started via foks ctl start) runs in the background and:
  • Holds device private keys in memory
  • Maintains an authenticated session with the server
  • Performs background rekeying after revocations — when a device or user is removed from a team, all team keys must rotate; the agent handles this automatically
  • Responds to requests from the CLI over a local Unix socket (or Windows named pipe)

​
The CLI

The foks binary is a one-shot command that connects to the agent for most operations. It is also a Git remote helper when invoked as git-remote-foks (typically a symlink).

​
Server Architecture

A FOKS server is a suite of independently-running Go services backed by a single PostgreSQL database.
ServiceDescription
regPublic registration and login; no mTLS required
userAuthenticated user and team operations; requires mTLS
probeDiscovery service — returns the hostchain and service endpoints for this server
beaconMaps a raw host ID (hash of the host’s public key) to a DNS name
merkle_queryPublic Merkle tree queries
merkle_batcherBatches pending operations into a deterministic set for the next Merkle epoch
merkle_builderApplies a batch to update the Merkle tree
merkle_signerSigns the new Merkle tree root
kv_storeServer-side key-value store backend; requires mTLS
queueInternal message queue for key-exchange (KEX) between devices
internal_caIssues mTLS certificates to the backend services

​
Key Hierarchy

  Device key (EdDSA, in agent memory)
       │
       ▼
  Per-User Key (PUK)
       │
       ▼
  Per-Team Key (PTK)  ──── role: owner / admin / member(n) / reader
       │
       ▼
  Encrypted data (KV store, Git repos)
When a device key is revoked, its user key must rotate, which causes all team keys where that user is a member to rotate in turn. The agent handles this cascade automatically.

​
Merkle Trees

Every write to the server is eventually included in a Merkle tree. Clients can query this tree to verify that:
  • The server has not tampered with data
  • The server has not rolled back to an earlier state
The Merkle tree root is signed by the server’s Merkle signer key, which is part of the publicly-verifiable host chain.

​
Signature Chains

Each entity (host, user, team) has a signature chain — an append-only log of key operations. These chains establish the full history of key additions, rotations, and revocations for that entity. Clients verify chains on connect.

​
Federation

Like email, FOKS uses DNS to discover servers. A team can include members from multiple FOKS servers. When servers need to probe each other (e.g., to verify a foreign team member’s keys), they use the probe service of the foreign host.

​
Protocols

FOKS protocols are defined in the proto-src/ directory using a custom IDL. Generated Go files live in proto/. Protocol groups:
GroupUsed for
lclClient CLI → local agent (Unix socket)
remClient agent → server (TLS)
infraServer → server communication
libShared types