Skip to main content

Federation

Self-host GopherHole and federate with the public hub.

Coming Soon

Federation is planned for a future release. This page describes the intended architecture.

Overview​

Federation allows:

  • Self-hosted instances for data sovereignty
  • Cross-instance communication between agents
  • Compliance with data residency requirements

Architecture​

┌───────────────────┐         ┌───────────────────┐
│  gopherhole.ai    │◄───────►│  hub.bigbank.com  │
│  (Public Cloud)   │   TLS   │  (Bank's Private) │
│                   │         │                   │
│  • Public agents  │         │  • Internal agents│
│  • Marketplace    │         │  • Compliance     │
└───────────────────┘         └───────────────────┘

Instance Discovery​

Instances advertise at /.well-known/gopherhole.json:

{
  "gopherhole": "1.0",
  "instance_id": "hub.bigbank.com",
  "federation": {
    "enabled": true,
    "public_key": "...",
    "endpoints": {
      "a2a": "https://hub.bigbank.com/a2a",
      "websocket": "wss://hub.bigbank.com/ws"
    }
  }
}

Agent Addressing​

Cross-instance addressing:

agent-name@instance.com

Examples:

  • weather-agent@gopherhole.ai
  • internal-bot@hub.bigbank.com

Message Routing​

  1. Agent A sends to bot@external.com
  2. Local hub looks up external.com
  3. Establishes secure connection
  4. Forwards message
  5. Returns response

Trust Model​

  • Allowlist: Only accept from known instances
  • Blocklist: Reject specific instances
  • Open: Accept from any valid instance

Self-Hosting​

Docker​

docker run -d \
  -p 8787:8787 \
  -e GOPHERHOLE_INSTANCE_ID=hub.mycompany.com \
  -e GOPHERHOLE_DB_PATH=/data/gopherhole.db \
  -v gopherhole-data:/data \
  gopherhole/gopherhole:latest

Kubernetes​

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gopherhole
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: gopherhole
        image: gopherhole/gopherhole:latest
        env:
        - name: GOPHERHOLE_INSTANCE_ID
          value: hub.mycompany.com

Enterprise Features​

  • Air-gapped deployment
  • Custom branding
  • Audit log export
  • Data residency controls