geth

geth is a personal, local-first mesh runtime for scripts, devices, databases, documents, blobs, pipes, and future multi-user collaboration.

This project is not the Ethereum geth client. The project and executable are still named geth.

One Binary

There is one executable: geth.

It has daemon mode and control mode:

geth init
geth daemon run
geth daemon service install
geth status
geth node id
geth resource list
geth cas add ./file

The daemon owns local identity, the Iroh endpoint, trust state, resource registry, module router, local metadata store, and synchronized data structures. Most non-daemon commands talk to the daemon through a local Unix socket at $GETH_HOME/run/geth.sock.

The daemon can also install itself as a user service:

geth daemon service install
geth daemon service status
geth daemon service uninstall

The bootstrap service managers are systemd user units on Linux, launchd user agents on macOS, and per-user scheduled tasks on Windows. These are user-level services, not system services.

Transport And SSH

All remote node-to-node geth communication is designed to happen over Iroh only. SSH is not a geth transport backend, and there is no SSH fallback transport. The default node config uses Iroh's default relay policy for practical connectivity; set [iroh].relay_mode = "disabled" for local-only/offline development. Named custom relay maps can be selected with relay_mode = "custom" and relay_map = "<name>". Iroh local-network discovery is enabled by default with [iroh].local_discovery = true.

SSH keys are used as admin trust anchors and ecosystem integration points. OpenSSH, FIDO, and YubiKey-backed keys can sign geth trust objects through canonical geth envelopes with explicit namespaces such as geth.keychain.v1@geth.local. Future SSH proxying may carry SSH protocol bytes over authorized Iroh streams, but the geth transport remains Iroh.

SSH certificate request and renewal flows are managed as geth metadata. A node can create a certificate request, another machine can approve it and receive an explicit ssh-keygen -s ... command suitable for a CA key or YubiKey-backed CA, and the resulting -cert.pub can be imported for distribution. Certificate and key revocation entries are tracked locally and can be exported as JSONL for distribution. Future Iroh replication will distribute these records between authorized nodes.

MVP Features

The bootstrap implementation provides:

• geth init
• geth daemon run
• geth daemon service install|uninstall|start|stop|status|print
• geth status
• geth node id
• geth resource list
• geth resource create <kind> <name>
• geth keychain init [--admin-key <path>]
• geth keychain status
• geth auth explain <subject> <resource> <capability>
• geth auth grant <subject> <resource> <capability> [--grant-id <id>]
• geth auth revoke <resource> <grant-id>
• local filesystem CAS commands: add, get, hash, has, pin, unpin, cleanup, list
• local DB resource registration: geth db add <name> <path> and geth db status <name>
• SSH certificate flow metadata:
  • geth ssh cert request --public-key <path> --principal <name>
  • geth ssh cert requests
  • geth ssh cert approve <request-id> --ca-key <path>
  • geth ssh cert import <request-id> --cert <path>
  • geth ssh cert list
  • geth ssh revocation add <kind> <target>
  • geth ssh revocation list
  • geth ssh revocation export --out <path>

Other command groups exist as explicit stubs: kv, pipe, document, pubsub, secret, and ssh.

Resource Modules

Everything meaningful is modeled as a resource. Planned resource kinds are:

• db: SQLite/cr-sqlite synchronization
• kv: Iroh Documents backed key-value stores
• pipe: dumbpipe-like byte streams over Iroh
• document: Automerge documents over Iroh streams
• pubsub: lossy notifications, not authoritative storage
• cas: content-addressed blob storage and distribution
• ssh-proxy: authorized SSH proxy/admin access over Iroh

Authorization is resource-scoped and capability-based. Bearer secrets may grant specific resource capabilities but do not create trusted node identity.

Local State

If GETH_HOME is set, geth uses it. Otherwise it uses an OS-specific data directory. The bootstrap layout is:

$GETH_HOME/
  geth.sqlite
  config.toml
  identity/agent.ed25519
  identity/iroh.ed25519
  cas/blobs/
  run/geth.sock

Quick Start

In one shell:

export GETH_HOME="$(mktemp -d)"
cargo run -p geth -- init
cargo run -p geth -- daemon run

In another shell:

export GETH_HOME="<same dir>"
cargo run -p geth -- status
cargo run -p geth -- node id
echo "hello geth" > /tmp/hello-geth.txt
cargo run -p geth -- cas add /tmp/hello-geth.txt
cargo run -p geth -- cas list

Authorization Direction

The MVP defines the split between:

• keychain: SSH-rooted users, devices, nodes, agents, and endpoint bindings
• auth: resource-local signed authorization operations and capability grants
• secrets: resource master secrets, epochs, envelopes, and bearer access

The current code does not implement Keyhive, BeeKEM, strong forward secrecy, or post-compromise security. It leaves room for future local-first, replicated auth logs and BeeKEM/CGKA-style group key evolution.