ngit-grasp serve
Run the GRASP relay server (default when no subcommand is given)
Upcoming operator surface
This page is generated from an unreleased ngit-grasp commit. Its interface may change before the next release.
Parent command: ngit-grasp
Usage
text
Usage: ngit-grasp serve [OPTIONS] --domain <DOMAIN>Running ngit-grasp without a subcommand invokes this command implicitly.
Arguments and options
| Input | Description | Details |
|---|---|---|
--domain <DOMAIN> | Domain where this instance is hosted (required, used in GRASP validation) | required; env NGIT_DOMAIN |
--base-path <BASE_PATH> | Public URL path where this instance is mounted. Use / for a domain-root deployment or an absolute path such as /grasp when sharing a domain with another service. | env NGIT_BASE_PATH; default / |
--relay-name <RELAY_NAME_OVERRIDE> | Relay name for NIP-11 information document (defaults to "${domain} grasp relay") | env NGIT_RELAY_NAME |
--relay-description <RELAY_DESCRIPTION> | Relay description for NIP-11 information document | env NGIT_RELAY_DESCRIPTION; default Git Nostr Relay - a grasp implementation |
--git-data-path <GIT_DATA_PATH> | Path to store Git repositories | env NGIT_GIT_DATA_PATH; default ./data/git |
--relay-data-path <RELAY_DATA_PATH> | Path to store Nostr relay data | env NGIT_RELAY_DATA_PATH; default ./data/relay |
--startup-integrity-identifiers <STARTUP_INTEGRITY_IDENTIFIERS> | Restrict automatic startup integrity passes to these repository identifiers. Empty by default, which checks every installed identifier family. This is intended only for staged validation before a full production sweep. | repeatable; env NGIT_STARTUP_INTEGRITY_IDENTIFIERS |
--bind-address <BIND_ADDRESS> | Server bind address (IP:PORT) | env NGIT_BIND_ADDRESS; default 127.0.0.1:7334 |
--trusted-proxy-cidrs <TRUSTED_PROXY_CIDRS> | Proxy address ranges allowed to supply client IP forwarding headers. Empty by default so forwarded headers from direct clients are ignored. | repeatable; env NGIT_TRUSTED_PROXY_CIDRS |
--database-backend <DATABASE_BACKEND> | Database backend type | env NGIT_DATABASE_BACKEND; default lmdb; values lmdb, memory |
--metrics-enabled | Enable Prometheus metrics endpoint | env NGIT_METRICS_ENABLED |
--metrics-connection-per-ip-abuse-threshold <METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD> | Connections per IP before flagging as potential abuse in metrics (display only, no rate limiting) | env NGIT_METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD; default 10 |
--metrics-top-n-repos <METRICS_TOP_N_REPOS> | Number of top bandwidth repos to track in metrics | env NGIT_METRICS_TOP_N_REPOS; default 10 |
--sync-bootstrap-relay-url <SYNC_BOOTSTRAP_RELAY_URL> | URL of bootstrap relay to sync from on startup (optional) Sync discovers additional relays from repository announcements that list our service If no scheme is provided (wss:// or ws://), wss:// is assumed Examples: "relay.example.com" -> "wss://relay.example.com", "wss://relay.example.com" -> unchanged | env NGIT_SYNC_BOOTSTRAP_RELAY_URL |
--sync-plus-enabled <SYNC_PLUS_ENABLED> | Enable GRASP-03 Sync+ mailbox discovery on top of proactive GRASP-02 sync | env NGIT_SYNC_PLUS_ENABLED; default true; values true, false |
--user-index-relays <USER_INDEX_RELAYS> | Comma-separated relays used to publish the relay-owner identity and to discover eligible accepted repository participants' NIP-65 relay lists | env NGIT_USER_INDEX_RELAYS; default wss://purplepag.es,wss://index.hzrd149.com,wss://indexer.coracle.social |
--sync-plus-fallback-relays <SYNC_PLUS_FALLBACK_RELAYS> | Comma-separated inbox fallbacks for eligible authors whose NIP-65 relay list is absent | env NGIT_SYNC_PLUS_FALLBACK_RELAYS; default wss://relay.ditto.pub,wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net |
--sync-recursive-descendant-limit <SYNC_RECURSIVE_DESCENDANT_LIMIT> | Soft limit on recursive query-frontier members below each event which directly tags a repository root. Direct root-tagging events are not counted | env NGIT_SYNC_RECURSIVE_DESCENDANT_LIMIT; default 500 |
--sync-max-backoff-secs <SYNC_MAX_BACKOFF_SECS> | Maximum backoff time in seconds for sync relay reconnection (default: 3600 = 1 hour) | env NGIT_SYNC_MAX_BACKOFF_SECS; default 3600 |
--sync-disconnect-check-interval-secs <SYNC_DISCONNECT_CHECK_INTERVAL_SECS> | Interval in seconds for checking disconnected relays and attempting reconnection (default: 60) Set to lower value for faster reconnection testing | env NGIT_SYNC_DISCONNECT_CHECK_INTERVAL_SECS; default 60 |
--sync-base-backoff-secs <SYNC_BASE_BACKOFF_SECS> | Base backoff time in seconds for relay reconnection (default: 5) Used for exponential backoff: base * 2^(failures-1) Set to 1 for faster test cycles Note: The connection timeout is capped at this value | env NGIT_SYNC_BASE_BACKOFF_SECS; default 5 |
--sync-disable-negentropy | Disable NIP-77 negentropy sync (default: false) When enabled, sync will use REQ+EOSE instead of negentropy for history sync. Primarily useful for testing that sync works without negentropy support | env NGIT_SYNC_DISABLE_NEGENTROPY |
--sync-allow-non-global-targets | Allow event-directed sync targets that are not globally reachable (default: false) Repository announcements and PR events are untrusted; by default their relay and clone URLs may only point at globally reachable hosts. Loopback, private, link-local and other special-purpose addresses, local hostnames, and hosts resolving to such addresses are rejected before any outbound connection or git fetch (SSRF protection). Setting this to true disables the reachability checks. Intended only for integration tests and closed development networks; production relays must leave it false. The operator-configured bootstrap relay is always allowed regardless of this setting. | env NGIT_SYNC_ALLOW_NON_GLOBAL_TARGETS |
--rejected-hot-cache-duration-secs <REJECTED_HOT_CACHE_DURATION_SECS> | Hot cache duration in seconds for rejected announcements (default: 120 = 2 minutes) Stores full event objects for immediate re-processing when dependencies resolve. Too short (<30s): Miss events from slow relays Too long (>5min): Waste memory | env NGIT_REJECTED_HOT_CACHE_DURATION_SECS; default 120 |
--rejected-cold-index-expiry-secs <REJECTED_COLD_INDEX_EXPIRY_SECS> | Cold index expiry in seconds for rejected announcements (default: 604800 = 7 days) Stores metadata only to prevent repeated downloads of rejected events | env NGIT_REJECTED_COLD_INDEX_EXPIRY_SECS; default 604800 |
--naughty-list-expiration-hours <NAUGHTY_LIST_EXPIRATION_HOURS> | Hours before removing relay from naughty list (default: 12) Relays with persistent infrastructure issues (DNS, TLS, protocol errors) are tracked separately and retried after this expiration period | env NGIT_NAUGHTY_LIST_EXPIRATION_HOURS; default 12 |
--holding-retention-secs <HOLDING_RETENTION_SECS> | Retention window in seconds for deleted events kept in holding DB | env NGIT_HOLDING_RETENTION_SECS; default 7776000 |
--holding-cleanup-interval-secs <HOLDING_CLEANUP_INTERVAL_SECS> | Interval in seconds between background holding cleanup passes | env NGIT_HOLDING_CLEANUP_INTERVAL_SECS; default 86400 |
--deletion-request-retention-unused-served-secs <DELETION_REQUEST_RETENTION_UNUSED_SERVED_SECS> | How long an unused deletion or vanish request remains served after relay-observed first_seen_at | env NGIT_DELETION_REQUEST_RETENTION_UNUSED_SERVED_SECS; default 2592000 |
--deletion-request-retention-unused-unserved-gating-additional-secs <DELETION_REQUEST_RETENTION_UNUSED_UNSERVED_GATING_ADDITIONAL_SECS> | Additional time an unused deletion or vanish request remains unserved but eligible to gate | env NGIT_DELETION_REQUEST_RETENTION_UNUSED_UNSERVED_GATING_ADDITIONAL_SECS; default 15552000 |
--deletion-request-retention-used-served-after-last-used-secs <DELETION_REQUEST_RETENTION_USED_SERVED_AFTER_LAST_USED_SECS> | Normal-mode time a used deletion or vanish request remains served after last_used_at | env NGIT_DELETION_REQUEST_RETENTION_USED_SERVED_AFTER_LAST_USED_SECS; default 23328000 |
--deletion-request-retention-used-unserved-gating-additional-secs <DELETION_REQUEST_RETENTION_USED_UNSERVED_GATING_ADDITIONAL_SECS> | Additional normal-mode time a used request remains unserved but continues gating after serving ends | env NGIT_DELETION_REQUEST_RETENTION_USED_UNSERVED_GATING_ADDITIONAL_SECS; default 7776000 |
--archive-all | Enable GRASP-05 archive mode: accept all announcements regardless of listing (WARNING: storage risk) | env NGIT_ARCHIVE_ALL |
--archive-whitelist <ARCHIVE_WHITELIST> | GRASP-05 archive whitelist: comma-separated list of npub/identifier/npub/identifier entries Formats: "npub1...", "npub1.../identifier", "identifier" | env NGIT_ARCHIVE_WHITELIST; default `` |
--archive-grasp-services <ARCHIVE_GRASP_SERVICES> | GRASP-05 archive GRASP services: comma-separated list of GRASP server domains to archive When set, archives all repositories from the specified GRASP server domains Mutually exclusive with archive_all and archive_whitelist | env NGIT_ARCHIVE_GRASP_SERVICES; default `` |
--archive-read-only <ARCHIVE_READ_ONLY> | Archive read-only mode: relay is a read-only sync of archived repositories Defaults to true if archive_all, archive_whitelist, or archive_grasp_services is set, false otherwise Throws error if set to true without archive_all, archive_whitelist, or archive_grasp_services | env NGIT_ARCHIVE_READ_ONLY; values true, false |
--grasp06-enable | Enable GRASP-06 contributor PR submission endpoint at /prs/<npub>/<identifier>.git When enabled, the relay exposes an unauthenticated PR submission endpoint at /prs/<npub>/<identifier>.git that accepts pushes of refs/nostr/<event-id> from any contributor. Security relies on the signed PR/PR-Update events the refs reference, not on HTTP-level auth. Default: false. This is an opt-in feature that adds an unauthenticated write surface; operators must understand the tradeoffs (see GRASP-06 spec and docs/explanation/grasp-06-contributor-pr-submission.md) before enabling it. | env NGIT_GRASP06_ENABLE |
--private-mode | Enable GRASP-08 private-service authentication. When enabled, every Nostr WebSocket session must authenticate with NIP-42 and every standard Git Smart HTTP request must carry the GRASP-08 repository-scoped NIP-98 credential. | env NGIT_PRIVATE_MODE |
--private-members <PRIVATE_MEMBERS> | Permanently configured GRASP-08 members as comma-separated npubs. The effective whitelist also includes NIP-11 owners of relays referenced by accepted repository announcements. Required and fail-closed when private mode is enabled. | env NGIT_PRIVATE_MEMBERS; default `` |
--private-public-origin <PRIVATE_PUBLIC_ORIGIN> | Canonical externally visible origin used by GRASP-08 NIP-98 u tags. Set this when TLS terminates upstream or a non-loopback deployment uses plain HTTP. When empty, the origin is inferred from NGIT_DOMAIN. | env NGIT_PRIVATE_PUBLIC_ORIGIN; default `` |
--repository-whitelist <REPOSITORY_WHITELIST> | Repository whitelist: comma-separated list of npub/identifier/npub/identifier entries Formats: "npub1...", "npub1.../identifier", "identifier" When set, only announcements matching the whitelist AND listing the service are accepted | env NGIT_REPOSITORY_WHITELIST; default `` |
--repository-blacklist <REPOSITORY_BLACKLIST> | Repository blacklist: comma-separated list of npub/identifier/npub/identifier entries to reject Formats: "npub1...", "npub1.../identifier", "identifier" Blacklist takes precedence over all whitelists (archive and repository) | env NGIT_REPOSITORY_BLACKLIST; default `` |
--blacklist-auto-restore | Automatically restore blacklist-deleted repositories on startup when they are no longer blacklisted and still within holding retention | env NGIT_BLACKLIST_AUTO_RESTORE |
--event-blacklist <EVENT_BLACKLIST> | Event blacklist: comma-separated list of npubs whose events are rejected All events from these authors are blocked from both relay storage and purgatory | env NGIT_EVENT_BLACKLIST; default `` |
--deletion-request-disrespector | Deletion request disrespector: ignore NIP-09 and NIP-62 requests (archival mode) When true, the relay stores incoming NIP-09 (kind 5) deletion requests and NIP-62 request-to-vanish events but does NOT act on them: their targets remain fully accessible. This makes the relay an archival server, preventing "left-pad" scenarios by ensuring at least some relays preserve deleted content. This setting ONLY affects NIP-09 and NIP-62 user-initiated requests. Policy-driven blacklist/whitelist deletion flows still run because they enforce local relay serving policy rather than client requests. When true, NIP-09 ("deletion") and NIP-62 ("request to vanish") are NOT advertised in the NIP-11 supported NIPs list so clients can discover that the relay does not honour either request type. | env NGIT_DELETION_REQUEST_DISRESPECTOR |
--max-connections <MAX_CONNECTIONS> | Maximum total connections to the relay (default: unlimited, defers to OS/infrastructure limits) | env NGIT_MAX_CONNECTIONS |
--relay-max-subscriptions <RELAY_MAX_SUBSCRIPTIONS> | Maximum active REQ subscriptions per WebSocket connection | env NGIT_RELAY_MAX_SUBSCRIPTIONS; default 500 |
--relay-max-event-size-bytes <RELAY_MAX_EVENT_SIZE_BYTES> | Maximum serialized event size in bytes | env NGIT_RELAY_MAX_EVENT_SIZE_BYTES; default 196608 |
--relay-filter-limit <RELAY_FILTER_LIMIT> | Per-filter result cap, including when a filter omits limit | env NGIT_RELAY_FILTER_LIMIT; default 500 |
--log-level <LOG_LEVEL> | Application log level or an explicit tracing filter expression. Bare levels keep dependency logging at warn | env NGIT_LOG_LEVEL; default info |
-h, --help | Print help (see a summary with '-h') | — |
-V, --version | Print version | — |
Related reference
Flags backed by environment variables are also listed in the configuration reference.