Delay is a production-ready connection hub that unifies Zen, GunDB, and IPFS into a single decentralized solution.
- Zen-Native — Deep integration with Zen's cryptographic primitives, DataBase wrapper, and identity resolution
- GunDB Relay — WebSocket relay with SQLite/RADISK persistence and WebRTC support
- IPFS Integration — Upload, pin, manage, and preview IPFS content via REST API
- Admin Dashboard — Modern React-based UI for monitoring and management
- Network Federation — Relay discovery, storage proofs, and reputation system
To connect your application to a Delay hub, use the official SDK:
npm install @delay/sdkSee the SDK Documentation for full usage examples, authentication, and IPFS operations.
git clone <repository-url>
cd delay
./docker-start.sh
curl http://localhost:8765/healthWhen deploying via CapRover, you must configure the Container HTTP Port in the app settings to correctly route NGINX traffic.
- Go to your CapRover Dashboard -> Apps -> delay -> HTTP Settings.
- Set Container HTTP Port to
8765. - Click Save & Update.
(Failure to do this will result in 502 Bad Gateway or 504 Gateway Timeout errors).
cd delay/relay
npm install
npm run start:devAdmin dashboards: http://localhost:8765/
Create a .env file with essential variables:
| Variable | Description | Default |
|---|---|---|
ADMIN_PASSWORD |
Admin token for all routes | (required) |
IPFS_API_URL |
IPFS API endpoint | http://127.0.0.1:5001 |
RELAY_PORT |
HTTP port | 8765 |
STORAGE_TYPE |
sqlite or radisk |
sqlite |
See Environment Variables for complete reference.
| Path | Description |
|---|---|
/dashboard |
New React Dashboard (Recommended) |
/admin |
Legacy entry (redirects) |
/endpoints |
API reference explorer |
| API Reference | Complete REST API documentation | | Environment Variables | All configuration options | | Node Operator Guide | Run your own relay | | Network Federation | Relay discovery & reputation | | Relay Keys | Keypair configuration |
| Endpoint | Description |
|---|---|
GET /gun |
WebSocket for Gun clients |
GET /health |
Health check |
GET /api/v1/system/stats |
System statistics |
| Endpoint | Description |
|---|---|
POST /api/v1/ipfs/upload |
Upload single file |
POST /api/v1/ipfs/upload-directory |
Upload multiple files as directory (maintains structure) |
GET /api/v1/ipfs/cat/:cid |
Stream content |
POST /api/v1/ipfs/pin/add |
Pin content |
GET /api/v1/ipfs/pin/ls |
List pins |
| Endpoint | Description |
|---|---|
GET /api/v1/user-uploads/system-hashes-map |
Get complete file metadata map |
POST /api/v1/user-uploads/save-system-hash |
Save file metadata (admin) |
DELETE /api/v1/user-uploads/remove-system-hash/:cid |
Remove file metadata |
Full API documentation at /endpoints or see API Reference.
This monorepo consists of two primary components:
relay/: The core server application (Zen, GunDB, IPFS connection hub).sdk/: The TypeScript/JavaScript Client SDK (@delay/sdk) for building apps that connect to the relay.
delay/
├── relay/ # Server Application
│ ├── src/ # Express + Gun bootstrap, REST endpoints, Admin UI
│ └── docs/ # API and Node operator documentation
├── sdk/ # TypeScript/JavaScript SDK
│ ├── src/ # SDK source code
│ └── README.md # SDK usage documentation
└── docker/ # Docker deployment utilities
| IPFS UDP buffer warning | Increase host net.core.rmem_max to 7500000 |
| Gun clients fail to connect | wscat -c ws://localhost:8765/gun |
| IPFS API unauthorized | Check IPFS_API_TOKEN |
| Admin UI "token required" | Enter token at /admin first |
- Fork the repository
- Create a feature branch
- Add tests when relevant
- Submit a pull request
MIT License © Shogun contributors. See LICENSE.