Top Related Projects
A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols
Peer-to-Peer Databases for the Decentralized Web
The current, performant & industrial strength version of Holochain on Rust.
Peer-to-peer hypermedia protocol
:kangaroo: - PouchDB is a pocket-sized database.
A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.
Quick Overview
GUN is a decentralized, real-time, graph database engine that runs in JavaScript. It's designed to be lightweight, fast, and scalable, allowing developers to build distributed and offline-first applications. GUN supports peer-to-peer synchronization and can work both in the browser and on servers.
Pros
- Decentralized architecture, enhancing data resilience and privacy
- Real-time synchronization across multiple peers
- Supports offline-first development
- Lightweight and easy to integrate into existing projects
Cons
- Learning curve for developers unfamiliar with graph databases
- Limited support for complex queries compared to traditional databases
- Potential scalability issues with large datasets
- Relatively small community compared to mainstream databases
Code Examples
- Basic data storage and retrieval:
const gun = Gun();
// Store data
gun.get('user').put({ name: 'Alice', age: 30 });
// Retrieve data
gun.get('user').on((data) => {
console.log(data);
});
- Real-time updates:
const gun = Gun();
// Subscribe to changes
gun.get('counter').on((data) => {
console.log('Counter value:', data);
});
// Update data
setInterval(() => {
gun.get('counter').put(Math.floor(Math.random() * 100));
}, 1000);
- Working with graph relationships:
const gun = Gun();
// Create nodes and relationships
gun.get('alice').put({ name: 'Alice' });
gun.get('bob').put({ name: 'Bob' });
gun.get('alice').get('friends').set(gun.get('bob'));
// Traverse the graph
gun.get('alice').get('friends').map().on((friend) => {
console.log('Alice\'s friend:', friend.name);
});
Getting Started
To start using GUN in your project, follow these steps:
-
Install GUN via npm:
npm install gun
-
Import and initialize GUN in your JavaScript file:
import Gun from 'gun'; const gun = Gun();
-
Start using GUN to store and retrieve data:
gun.get('myData').put({ hello: 'world' }); gun.get('myData').on((data) => console.log(data));
For more advanced usage and configuration options, refer to the official GUN documentation.
Competitor Comparisons
A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols
Pros of ssb-db
- Designed specifically for decentralized social networking applications
- Robust append-only log structure ensures data integrity and immutability
- Built-in support for cryptographic signatures and verification
Cons of ssb-db
- More complex setup and configuration compared to Gun
- Limited real-time synchronization capabilities
- Steeper learning curve for developers new to the Secure Scuttlebutt ecosystem
Code Comparison
ssb-db example:
const ssbClient = require('ssb-client')
ssbClient((err, sbot) => {
sbot.publish({ type: 'post', text: 'Hello, SSB!' }, (err, msg) => {
console.log(msg)
})
})
Gun example:
const Gun = require('gun')
const gun = Gun()
gun.get('messages').set({ text: 'Hello, Gun!' })
gun.get('messages').on((data, key) => {
console.log(data)
})
Both Gun and ssb-db are decentralized database solutions, but they have different focuses and architectures. Gun is designed for real-time, multi-master synchronization with a graph-based data model, while ssb-db is tailored for secure, append-only logs in social networking contexts. Gun offers easier setup and more flexible data structures, whereas ssb-db provides stronger guarantees for data integrity and cryptographic verification.
Peer-to-Peer Databases for the Decentralized Web
Pros of OrbitDB
- Built on IPFS, providing robust decentralized storage and content addressing
- Supports multiple database types (key-value, docs, counters, etc.)
- More flexible and extensible architecture
Cons of OrbitDB
- Steeper learning curve due to IPFS integration
- Less active development and smaller community compared to Gun
- Potentially slower performance for real-time applications
Code Comparison
OrbitDB:
const orbitdb = await OrbitDB.createInstance(ipfs)
const db = await orbitdb.keyvalue('my-database')
await db.put('key', 'value')
const value = await db.get('key')
Gun:
const gun = Gun()
const db = gun.get('my-database')
db.put({ key: 'value' })
db.get('key').once((value) => console.log(value))
Both projects aim to provide decentralized database solutions, but they differ in their approach and underlying technologies. OrbitDB leverages IPFS for data storage and distribution, offering a more comprehensive decentralized architecture. Gun, on the other hand, focuses on simplicity and real-time synchronization, making it easier to get started but potentially less scalable for complex use cases.
While OrbitDB provides more database types and flexibility, Gun excels in ease of use and real-time capabilities. Developers should consider their specific requirements and the trade-offs between these two options when choosing a decentralized database solution for their projects.
The current, performant & industrial strength version of Holochain on Rust.
Pros of Holochain
- More scalable architecture for distributed applications
- Built-in support for data validation and integrity
- Stronger focus on privacy and user control
Cons of Holochain
- Steeper learning curve due to complex architecture
- Smaller community and ecosystem compared to Gun
- Less mature, still in active development
Code Comparison
Holochain (Rust):
#[hdk_extern]
pub fn create_entry(entry: Entry) -> ExternResult<HeaderHash> {
create_entry(&entry)
}
Gun (JavaScript):
gun.get('key').put({
data: 'value'
}, (ack) => {
console.log('Data saved:', ack);
});
Key Differences
- Holochain uses Rust for core development, while Gun is primarily JavaScript-based
- Holochain employs a agent-centric model, whereas Gun focuses on a graph-based data structure
- Holochain offers more built-in security features and data validation mechanisms
- Gun provides easier integration with web applications and real-time synchronization
Both projects aim to create decentralized, peer-to-peer networks, but they differ in their approach to data storage, validation, and application architecture. Holochain offers a more comprehensive framework for building distributed applications, while Gun provides a simpler, more flexible solution for real-time data synchronization.
Peer-to-peer hypermedia protocol
Pros of IPFS
- More mature and widely adopted project with a larger community and ecosystem
- Content-addressed storage provides better data integrity and deduplication
- Supports a wider range of use cases beyond just real-time data synchronization
Cons of IPFS
- Higher complexity and steeper learning curve for developers
- Requires more resources and infrastructure to run effectively
- Less focus on real-time updates and conflict resolution
Code Comparison
IPFS (JavaScript HTTP client):
import { create } from 'ipfs-http-client'
const ipfs = create('http://localhost:5001')
const { cid } = await ipfs.add('Hello world')
console.log(cid.toString())
Gun:
import Gun from 'gun'
const gun = Gun()
gun.get('greetings').put({ message: 'Hello world' })
gun.get('greetings').on((data) => console.log(data.message))
Key Differences
- IPFS focuses on content-addressed storage and distribution, while Gun emphasizes real-time data synchronization
- IPFS uses a distributed hash table (DHT) for content discovery, whereas Gun relies on a peer-to-peer mesh network
- Gun provides built-in conflict resolution and eventual consistency, which IPFS leaves to higher-level applications
- IPFS has a more modular architecture with separate components for storage, networking, and naming, while Gun integrates these features more tightly
:kangaroo: - PouchDB is a pocket-sized database.
Pros of PouchDB
- Better documentation and more extensive API
- Stronger focus on data synchronization with CouchDB
- Larger community and more widespread adoption
Cons of PouchDB
- Heavier and more complex than Gun
- Primarily designed for document-based data, less flexible for graph-like structures
Code Comparison
PouchDB:
var db = new PouchDB('mydb');
db.put({
_id: 'dave@gmail.com',
name: 'David',
age: 69
});
db.changes().on('change', function() {
console.log('Ch-ch-changes');
});
Gun:
var gun = Gun();
gun.get('user').put({
name: 'David',
age: 69
});
gun.get('user').on(function(data, key) {
console.log('Update:', data);
});
Both PouchDB and Gun are JavaScript databases for web and mobile applications. PouchDB excels in CouchDB synchronization and has more extensive documentation, while Gun offers a lighter-weight solution with real-time synchronization capabilities. PouchDB is better suited for document-based data structures, whereas Gun provides more flexibility for graph-like data. The code examples demonstrate basic data storage and change detection in both libraries, highlighting their different approaches to handling data and updates.
A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.
Pros of Automerge
- Designed specifically for collaborative editing, with built-in conflict resolution
- Supports a wider range of data types, including text, lists, and nested objects
- More actively maintained with regular updates and improvements
Cons of Automerge
- Generally slower performance compared to Gun, especially for large datasets
- Requires more setup and configuration for complex use cases
- Less flexible for real-time applications outside of collaborative editing
Code Comparison
Automerge example:
import * as Automerge from 'automerge'
let doc1 = Automerge.init()
doc1 = Automerge.change(doc1, doc => {
doc.list = ['item1']
})
Gun example:
import Gun from 'gun'
const gun = Gun()
gun.get('list').put(['item1'])
Both Gun and Automerge are open-source JavaScript libraries for building distributed/decentralized applications, but they have different focuses and strengths. Gun is more general-purpose and optimized for real-time applications, while Automerge specializes in collaborative editing with strong consistency guarantees. The choice between them depends on the specific requirements of your project, such as data types, performance needs, and the level of conflict resolution required.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
GUN is an ecosystem of tools that let you build community run and encrypted applications - like an Open Source Firebase or a Decentralized Dropbox.
The Internet Archive and 100s of other apps run GUN in-production.
- Multiplayer by default with realtime p2p state synchronization!
- Graph data lets you use key/value, tables, documents, videos, & more!
- Local-first, offline, and decentralized with end-to-end encryption.
Decentralized alternatives to Zoom, Reddit, Instagram, Slack, YouTube, Stripe, Wikipedia, Facebook Horizon and more have already pushed terabytes of daily P2P traffic on GUN. We are a friendly community creating a free fun future for freedom:









Quickstart
GUN is super easy to get started with:
- Try the interactive tutorial in the browser (5min ~ average developer).
- Or
npm install gun
and run the examples withcd node_modules/gun && npm start
(5min ~ average developer).
Note: If you don't have node or npm, read this first. If the
npm
command line didn't work, you may need tomkdir node_modules
first or usesudo
.
- An online demo of the examples are available here: http://try.axe.eco/
- Or write a quick app: (try now in a playground)
<script src="https://cdn.jsdelivr.net/npm/gun/gun.js"></script>
<script>
// import GUN from 'gun'; // in ESM
// GUN = require('gun'); // in NodeJS
// GUN = require('gun/gun'); // in React
gun = GUN();
gun.get('mark').put({
name: "Mark",
email: "mark@gun.eco",
});
gun.get('mark').on((data, key) => {
console.log("realtime updates:", data);
});
setInterval(() => { gun.get('mark').get('live').put(Math.random()) }, 9);
</script>
- Or try something mind blowing, like saving circular references to a table of documents! (play)
cat = {name: "Fluffy", species: "kitty"};
mark = {boss: cat};
cat.slave = mark;
// partial updates merge with existing data!
gun.get('mark').put(mark);
// access the data as if it is a document.
gun.get('mark').get('boss').get('name').once(function(data, key){
// `once` grabs the data once, no subscriptions.
console.log("Mark's boss is", data);
});
// traverse a graph of circular references!
gun.get('mark').get('boss').get('slave').once(function(data, key){
console.log("Mark is the cat's slave!", data);
});
// add both of them to a table!
gun.get('list').set(gun.get('mark').get('boss'));
gun.get('list').set(gun.get('mark'));
// grab each item once from the table, continuously:
gun.get('list').map().once(function(data, key){
console.log("Item:", data);
});
// live update the table!
gun.get('list').set({type: "cucumber", goal: "jumping cat"});
Want to keep building more? Jump to THE DOCUMENTATION!
About
First & foremost, GUN is a community of the nicest and most helpful people out there. So I want to invite you to come tell us about what you are working on & wanting to build (new or old school alike! Just be nice as well.) and ask us your questions directly. :)
The GUN ecosystem stack is a collection of independent and modular tools covering everything from CRDT conflict resolution, cryptographic security & encryption, radix storage serialization, mesh networking & routing algorithms, to distributed systems correctness & load testing, CPU scheduled JSON parser to prevent UI lag, and more!


On that note, let's get some official shout outs covered first:
Support
Thanks to:
![]() |
![]() |
|
![]() |
![]() |
![]() |
Robert Heessels, Lorenzo Mangani, NLnet Foundation, Sam Liu, Daniel Dombrowsky, Vincent Woo, AJ ONeal, Bill Ottman, Mike Lange, Sean Matheson, Alan Mimms, Dário Freire, John Williamson, Robin Bron, Elie Makhoul, Mike Staub, Bradley Matusiak, Jeff Cook, Nico, Aaron Artille, Tim Robinson, Fabian Stamm, Mike Staub, Hunter Owens, Jacob Millner, Gerrit Balindt, Gabriel Lemon, Murage Martin, Jason Stallings
- Join others in sponsoring code: https://www.patreon.com/gunDB !
- Ask questions: http://stackoverflow.com/questions/tagged/gun ?
- Found a bug? Report at: https://github.com/amark/gun/issues ;
- Need help? Chat with us: http://chat.gun.eco .
History
GUN was created by Mark Nadal in 2014 after he had spent 4 years trying to get his collaborative web app to scale up with traditional databases.
After he realized Master-Slave database architecture causes one big bottleneck, he (as a complete newbie outsider) naively decided to question the status quo and shake things up with controversial, heretical, and contrarian experiments:
The NoDB - no master, no servers, no "single source of truth", not built with a real programming language or real hardware, no DevOps, no locking, not just SQL or NoSQL but both (all - graphs, documents, tables, key/value).
The goal was to build a P2P database that could survive living inside any browser, and could correctly sync data between any device after assuming any offline-first activity.

Technically, GUN is a graph synchronization protocol with a lightweight embedded engine, capable of doing 20M+ API ops/sec in just ~9KB gzipped size.
Documentation
API reference |
Tutorials |
Examples |
GraphQL |
Electron |
React & Native |
Vue |
Svelte |
Webcomponents |
CAP Theorem Tradeoffs |
How Data Sync Works |
How GUN is Built |
Crypto Auth |
Modules |
Roadmap |
This would not be possible without community contributors, big shout out to:
ajmeyghani (Learn GUN Basics with Diagrams); anywhichway (Block Storage); beebase (Quasar); BrockAtkinson (brunch config); Brysgo (GraphQL); d3x0r (SQLite); forrestjt (file.js); hillct (Docker); JosePedroDias (graph visualizer); JuniperChicago (cycle.js bindings); jveres (todoMVC); kristianmandrup (edge); Lightnet (Awesome Vue User Examples & User Kitchen Sink Playground); lmangani (Cytoscape Visualizer, Cassandra, Fastify, LetsEncrypt); mhelander (SEA); omarzion (Sticky Note App); PsychoLlama (LevelDB); RangerMauve (schema); robertheessels (gun-p2p-auth); rogowski (AXE); sbeleidy; sbiaudet (C# Port); Sean Matheson (Observable/RxJS/Most.js bindings); Shadyzpop (React Native example); sjones6 (Flint); RIP Stefdv (Polymer/web components); zrrrzzt (JWT Auth); xmonader (Python Port);
I am missing many others, apologies, will be adding them soon! This list is infinitely old & way out of date, if you want to be listed in it please make a PR! :)
Testing
You will need to npm install -g mocha
first. Then in the gun root folder run npm test
. Tests will trigger persistent writes to the DB, so subsequent runs of the test will fail. You must clear the DB before running the tests again. This can be done by running rm -rf *data*
command in the project directory.
Shims
These are only needed for NodeJS & React Native, they shim the native Browser WebCrypto API.
If you want to use SEA for User
auth and security, you will need to install:
npm install @peculiar/webcrypto --save
Please see our React Native docs for installation instructions!
Then you can require SEA without an error:
GUN = require('gun/gun');
SEA = require('gun/sea');
Deploy
Note: The default examples that get auto-deployed on
npm start
CDN-ify all GUN files, modules, & storage.
Note: Moving forward, AXE will start to automatically cluster your peer into a shared DHT. You may want to disable this to run an isolated network.
Note: When deploying a web application using GUN on a cloud provider, you may have to set
CI=false
in your.env
. This prevents GUN-specific warnings from being treated as errors when deploying your app. You may also resolve this by modifying your webpack config to not try to build the GUN dependencies.
To quickly spin up a GUN relay peer for your development team, utilize Heroku, Docker, or any others listed below. Or some variant thereof Dokku, K8s, etc. ! Or use all of them so your relays are decentralized too!
Linux
SSH
into the home directory of a clean OS install with sudo
ability. Set any environment variables you need (see below), then do:
curl -o- https://raw.githubusercontent.com/amark/gun/master/examples/install.sh | bash
Read install.sh first! If
curl
is not found, copy&paste the contents of install.sh into your ssh.
You can now safely CTRL+A+D
to escape without stopping the peer. To stop everything killall screen
or killall node
.
Environment variables may need to be set like export HTTPS_CERT=~/cert.pem HTTPS_KEY=~/key.pem PORT=443
. You can also look at a sample nginx config. For production deployments, you probably will want to use something like pm2
or better to keep the peer alive after machine reboots.
Dome
Deploy GUN in one-click with Dome and receive a free trial:
Heroku
Heroku deletes your data every 15 minutes, one way to fix this is by adding cheap storage.
Or:
git clone https://github.com/amark/gun.git
cd gun
heroku create
git push -f heroku HEAD:master
Then visit the URL in the output of the 'heroku create' step, in a browser. Make sure to set any environment config vars in the settings tab.
Zeet.co
Then visit the URL in the output of the 'now --npm' step, in your browser.
Docker
Warning: Docker image is community contributed and may be old with missing security updates, please check version numbers to compare.
Pull from the Docker Hub . Or:
docker run -p 8765:8765 gundb/gun
Or build the Docker image locally:
git clone https://github.com/amark/gun.git
cd gun
docker build -t myrepo/gundb:v1 .
docker run -p 8765:8765 myrepo/gundb:v1
Or, if you prefer your Docker image with metadata labels (Linux/Mac only):
npm run docker
docker run -p 8765:8765 username/gun:git
Then visit http://localhost:8765 in your browser.
License
Designed with ⥠by Mark Nadal, the GUN team, and many amazing contributors.
Openly licensed under Zlib / MIT / Apache 2.0.
Top Related Projects
A database of unforgeable append-only feeds, optimized for efficient replication for peer to peer protocols
Peer-to-Peer Databases for the Decentralized Web
The current, performant & industrial strength version of Holochain on Rust.
Peer-to-peer hypermedia protocol
:kangaroo: - PouchDB is a pocket-sized database.
A JSON-like data structure (a CRDT) that can be modified concurrently by different users, and merged again automatically.
Convert
designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot