🥚 EGG — Event Git Graph

The decentralized GitHub, native to Nostr. Your server. Your code. Your identity.

EGG is a self-hosted Git forge that replaces GitHub/GitLab for open-source teams who want true ownership and decentralized collaboration.

Deploy it on your own domain (egg.yourdomain.com) and get:

• Full Git hosting — push, pull, branch, merge with standard git
• Web client — browse repos, diffs, history
• Built-in Nostr relay — all social interactions (issues, PRs, reviews) happen as signed Nostr events
• Decentralized identity — your npub is your username. No accounts, no email, no passwords.
• Cross-instance collaboration — developers on any EGG instance can interact with your repos through Nostr

egg.alice.com ──── nostr events ────► egg.bob.com
      │                                     │
   git repos                            git repos
   web client                           web client  
   nostr relay                          nostr relay

• Architecture
• Requirements
• Installation
• Configuration
• Managing Repositories
• Access Control
• Nostr Integration
• Updating
• Uninstalling
• Contributing
• Protocol Spec
• License

EGG separates two concerns:

┌─────────────────────────────────┐
│        egg.yourdomain.com       │
│                                 │
│  ┌──────────┐  ┌─────────────┐ │
│  │ Git bare │  │  Web Client │ │
│  │  repos   │  │   (EGG UI)  │ │
│  └──────────┘  └─────────────┘ │
│  ┌──────────────────────────┐  │
│  │   Built-in Nostr Relay   │  │
│  └──────────────────────────┘  │
└─────────────────────────────────┘
          │ Nostr events │
          ▼              ▼
   Other EGG        Any Nostr
   instances         clients

Code lives on your server. Conversations live on Nostr.

A domain is required. EGG is designed to run at egg.yourdomain.com. Nostr identity and cross-instance discovery depend on a stable domain.

Add a DNS A record for egg.yourdomain.com pointing to your server's IP. Wait for DNS propagation before proceeding.

ssh user@your-server-ip

# Ubuntu / Debian
sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl nginx certbot python3-certbot-nginx

# Install Node.js 22.x
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

git clone https://github.com/getegg/egg.git /opt/egg
cd /opt/egg

sudo ./scripts/install.sh

The installer will ask you:

• Your domain (egg.yourdomain.com)
• Your Nostr public key (npub1...) — this becomes the instance admin
• Whether the instance is public or invite-only
• Port for the built-in relay (default: 7777)

It will automatically:

• Install Node.js dependencies
• Configure Nginx as reverse proxy
• Issue an SSL certificate via Let's Encrypt
• Create the git user and directories
• Start EGG as a systemd service
• Start the Nostr relay as a systemd service

sudo systemctl status egg
sudo systemctl status egg-relay

Visit https://egg.yourdomain.com — you should see the EGG web client.

Configuration lives in /opt/egg/config/egg.toml:

[server]
domain    = "egg.yourdomain.com"
port      = 3000
admin_npub = "npub1..."          # Your Nostr public key

[git]
repos_path = "/var/egg/repos"    # Where bare repos are stored
ssh_port   = 22

[relay]
enabled  = true
port     = 7777
max_connections = 1000

[access]
# "public"  — anyone can register and push public repos
# "invite"  — only authorized npubs can create repos
mode = "public"

[tls]
enabled = true
cert = "/etc/letsencrypt/live/egg.yourdomain.com/fullchain.pem"
key  = "/etc/letsencrypt/live/egg.yourdomain.com/privkey.pem"

After changing config, restart EGG:

sudo systemctl restart egg

Via the web client at https://egg.yourdomain.com, or via CLI:

egg-cli repo create myproject --visibility public

# In your local project
git init
git add .
git commit -m "first commit"

# Add your EGG instance as remote
git remote add origin git@egg.yourdomain.com:myproject.git

# Push
git push -u origin main

git clone git@egg.bob.com:coolproject.git

git clone https://egg.yourdomain.com/myproject.git

Access is enforced by two layers working together:

• Server layer — controls who can push/pull via SSH keys or npub-auth
• Nostr layer — controls who can interact (issues, PRs, reviews) via signed events

Anyone can clone. Any npub can open issues and submit PRs as Nostr events. You control who can merge via authorized collaborators.

Only authorized npubs can clone and interact.

egg-cli access grant \
  --repo myproject \
  --npub npub1collaborator... \
  --role contributor   # roles: viewer | contributor | maintainer | admin

This publishes a signed Nostr event granting access. The collaborator's EGG client or any Nostr client will see the invitation.

egg-cli access revoke --repo myproject --npub npub1collaborator...

EGG uses Nostr events for all social interactions. The built-in relay listens on port 7777 (configurable).

Point any Nostr client to your relay:

wss://egg.yourdomain.com/relay

Issues and PR notifications will appear in your Nostr feed.

You can configure EGG to broadcast events to external relays in addition to the built-in one:

[relay]
broadcast_to = [
  "wss://relay.damus.io",
  "wss://nos.lol"
]

cd /opt/egg
git pull origin main
npm install --production
sudo systemctl restart egg egg-relay

To check the current version:

egg-cli --version

sudo /opt/egg/scripts/uninstall.sh

This removes EGG services, Nginx config and the git user. Your repos in /var/egg/repos are NOT deleted automatically — back them up or move them manually.

EGG is built in the open. Contributions are welcome.

# Fork the repo on GitHub, then:
git clone https://github.com/YOUR_USERNAME/egg.git
cd egg
npm install
cp config/egg.example.toml config/egg.toml   # edit as needed
npm run dev

Please read CONTRIBUTING.md before submitting a PR.

For protocol discussions, open an issue with the protocol label or join the conversation on Nostr.

The EGG event protocol is documented in docs/PROTOCOL.md.

We follow and extend NIP-34 (Git stuff) from the Nostr protocol.

MIT — Edgar Paula, 2025

Links

• 🌐 Website: egg.edgarpaula.org
• 📦 Organization: github.com/getegg
• 🟣 EGG on Nostr: nosta.me/npub1xux7...
• 👤 Author: edgarpaula.org