docs/design/federation.md
Status: Partially implemented -- Infrastructure (Dolt remotes) exists. Core federation features (URI scheme, cross-workspace queries, delegation) are not yet implemented.
Multi-workspace coordination for Gas Town and Beads.
Federation enables multiple Gas Town instances to reference each other's work, coordinate across organizations, and track distributed projects.
Level 1: Entity - Person or organization (flat namespace)
Level 2: Chain - Workspace/town per entity
Level 3: Work Unit - Issues, tasks, molecules on chains
Full work unit reference (HOP protocol):
hop://entity/chain/rig/issue-id
hop://[email protected]/main-town/greenplace/gp-xyz
Cross-repo reference (same platform):
beads://platform/org/repo/issue-id
beads://github/acme/backend/ac-123
Within a workspace, short forms are preferred:
gp-xyz # Local (prefix routes via routes.jsonl)
greenplace/gp-xyz # Different rig, same chain
./gp-xyz # Explicit current-rig ref
See ~/gt/docs/hop/GRAPH-ARCHITECTURE.md for full URI specification.
Planned relationship primitives: employment (entity-to-org membership),
cross-reference (inter-workspace depends_on links), and delegation
(work distribution across workspaces with terms and deadlines).
Every agent operation is attributed. See identity.md for the complete BD_ACTOR format convention.
# Set per agent session
GIT_AUTHOR_NAME="greenplace/crew/joe"
GIT_AUTHOR_EMAIL="[email protected]" # Workspace owner
Result: abc123 Fix bug (greenplace/crew/joe <[email protected]>)
BD_ACTOR="greenplace/crew/joe" # Set in agent environment
bd create --title="Task" # Actor auto-populated
All events include actor:
{
"ts": "2025-01-15T10:30:00Z",
"type": "sling",
"actor": "greenplace/crew/joe",
"payload": { "bead": "gp-xyz", "target": "greenplace/polecats/Toast" }
}
Workspace metadata lives in ~/gt/.town.json (owner, name, public_name).
Planned commands: gt remote add/list for remote registration,
bd show hop://... and bd list --remote=... for cross-workspace queries.
dolt login)Town-level Dolt databases have remotes configured pointing to DoltHub:
# Check configured remotes for town database
cd ~/gt/.dolt-data/town && dolt remote -v
# origin https://doltremoteapi.dolthub.com/steveyegge/gastown-town {}
# local http://localhost:8000/town {}
| Database | Remote Name | URL | Purpose |
|---|---|---|---|
| town | origin | steveyegge/gastown-town | DoltHub public federation |
| town | local | http://localhost:8000/town | Local development/testing |
| gastown | origin | steveyegge/gastown-rig | DoltHub public federation |
| beads | origin | steveyegge/gastown-beads | DoltHub public federation |
1. DoltHub (Recommended for Public Federation)
Like GitHub for Dolt - public, hosted, zero infrastructure:
# Login to DoltHub (one-time setup)
dolt login
# Push to remote
cd ~/gt/.dolt-data/town
dolt push origin main
2. Local Remotesapi (Development/Testing)
Already enabled in ~/gt/.dolt-data/config.yaml:
read_only: false for full federation)# Test local remote
dolt push local main
3. Self-Hosted DoltLab (Enterprise)
For private federation within an organization:
dolt remote add corp https://doltlab.corp.example.com/org/repo4. Direct Town-to-Town (Advanced)
Two Gas Town instances federating directly:
dolt remote add town-a http://town-a.example.com:8000/townTo push/pull from configured remotes:
DoltHub Authentication:
dolt login
# Opens browser for OAuth
# Creates credentials in ~/.dolt/creds/
Create DoltHub Repository:
steveyegge/gastown-town)Initial Push:
cd ~/gt/.dolt-data/town
dolt push -u origin main
Enable Write for Local Remotesapi:
Edit ~/gt/.dolt-data/config.yaml:
remotesapi:
port: 8000
read_only: false # Enable writes
Restart daemon: gt down && gt up
bd list --org=...)