ngit docs

ngit-grasp configuration ​

This reference lists all 51 public runtime configuration options exported by ngit-grasp.

Upcoming operator surface

This page is generated from an unreleased ngit-grasp commit. Its interface may change before the next release.

Loading behaviour ​

ngit-grasp automatically reads a .env file from its working directory. Variables already present in the process environment take precedence over .env values.

Configuration changes require a process restart. See constraint rules for relationships that cannot be expressed as one option, and secret precedence for relay-owner key discovery.

Options ​

  • NGIT_ARCHIVE_ALL — Enable GRASP-05 archive mode: accept all announcements regardless of listing (WARNING: storage risk)
  • NGIT_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
  • NGIT_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
  • NGIT_ARCHIVE_WHITELIST — GRASP-05 archive whitelist: comma-separated list of npub/identifier/npub/identifier entries Formats: "npub1...", "npub1.../identifier", "identifier"
  • NGIT_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.
    • CLI: --base-path <BASE_PATH>
    • Runtime: scope serve; default /; values —; reload restart required
    • Rules: base-path-normalized
  • NGIT_BIND_ADDRESS — Server bind address (IP:PORT)
    • CLI: --bind-address <BIND_ADDRESS>
    • Runtime: scope serve; default 127.0.0.1:7334; values —; reload restart required
    • Rules: bind-address-format
  • NGIT_BLACKLIST_AUTO_RESTORE — Automatically restore blacklist-deleted repositories on startup when they are no longer blacklisted and still within holding retention
    • CLI: --blacklist-auto-restore
    • Runtime: scope serve; default false; values —; reload restart required
    • Rules: —
  • NGIT_DATABASE_BACKEND — Database backend type
    • CLI: --database-backend <DATABASE_BACKEND>
    • Runtime: scope serve; default lmdb; values lmdb, memory; reload restart required
    • Rules: —
  • NGIT_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.
    • CLI: --deletion-request-disrespector
    • Runtime: scope serve; default false; values —; reload restart required
    • Rules: —
  • NGIT_DELETION_REQUEST_RETENTION_UNUSED_SERVED_SECS — How long an unused deletion or vanish request remains served after relay-observed first_seen_at
  • NGIT_DELETION_REQUEST_RETENTION_UNUSED_UNSERVED_GATING_ADDITIONAL_SECS — Additional time an unused deletion or vanish request remains unserved but eligible to gate
  • NGIT_DELETION_REQUEST_RETENTION_USED_SERVED_AFTER_LAST_USED_SECS — Normal-mode time a used deletion or vanish request remains served after last_used_at
  • NGIT_DELETION_REQUEST_RETENTION_USED_UNSERVED_GATING_ADDITIONAL_SECS — Additional normal-mode time a used request remains unserved but continues gating after serving ends
  • NGIT_DOMAIN — Domain where this instance is hosted (required, used in GRASP validation)
    • CLI: --domain <DOMAIN>
    • Runtime: scope serve; default —; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --event-blacklist <EVENT_BLACKLIST>
    • Runtime: scope serve; default empty string; values —; reload restart required
    • Rules: —
  • NGIT_GIT_DATA_PATH — Path to store Git repositories Path to the git data directory (contains bare repositories). Defaults to ./data/git (same default as the relay itself). Git data path containing the .archive subtree Git data path containing the .grasp family storage directory
    • CLI: --git-data-path <GIT_DATA_PATH>
    • Runtime: scope shared; default ./data/git; values —; reload restart required
    • Rules: —
  • NGIT_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.
    • CLI: --grasp06-enable
    • Runtime: scope serve; default false; values —; reload restart required
    • Rules: private-mode-with-grasp06
  • NGIT_HOLDING_CLEANUP_INTERVAL_SECS — Interval in seconds between background holding cleanup passes
    • CLI: --holding-cleanup-interval-secs <HOLDING_CLEANUP_INTERVAL_SECS>
    • Runtime: scope serve; default 86400; values —; reload restart required
    • Rules: holding-cleanup-interval-positive
  • NGIT_HOLDING_RETENTION_SECS — Retention window in seconds for deleted events kept in holding DB
    • CLI: --holding-retention-secs <HOLDING_RETENTION_SECS>
    • Runtime: scope serve; default 7776000; values —; reload restart required
    • Rules: holding-retention-positive
  • NGIT_LOG_LEVEL — Application log level or an explicit tracing filter expression. Bare levels keep dependency logging at warn
    • CLI: --log-level <LOG_LEVEL>
    • Runtime: scope serve; default info; values —; reload restart required
    • Rules: —
  • NGIT_MAX_CONNECTIONS — Maximum total connections to the relay (default: unlimited, defers to OS/infrastructure limits)
    • CLI: --max-connections <MAX_CONNECTIONS>
    • Runtime: scope serve; default —; values —; reload restart required
    • Rules: —
  • NGIT_METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD — Connections per IP before flagging as potential abuse in metrics (display only, no rate limiting)
    • CLI: --metrics-connection-per-ip-abuse-threshold <METRICS_CONNECTION_PER_IP_ABUSE_THRESHOLD>
    • Runtime: scope serve; default 10; values —; reload restart required
    • Rules: —
  • NGIT_METRICS_ENABLED — Enable Prometheus metrics endpoint
    • CLI: --metrics-enabled
    • Runtime: scope serve; default true; values —; reload restart required
    • Rules: —
  • NGIT_METRICS_TOP_N_REPOS — Number of top bandwidth repos to track in metrics
    • CLI: --metrics-top-n-repos <METRICS_TOP_N_REPOS>
    • Runtime: scope serve; default 10; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --naughty-list-expiration-hours <NAUGHTY_LIST_EXPIRATION_HOURS>
    • Runtime: scope serve; default 12; values —; reload restart required
    • Rules: —
  • NGIT_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.
  • NGIT_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.
  • NGIT_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.
    • CLI: --private-public-origin <PRIVATE_PUBLIC_ORIGIN>
    • Runtime: scope serve; default empty string; values —; reload restart required
    • Rules: private-public-origin-format
  • NGIT_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
    • CLI: --rejected-cold-index-expiry-secs <REJECTED_COLD_INDEX_EXPIRY_SECS>
    • Runtime: scope serve; default 604800; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --rejected-hot-cache-duration-secs <REJECTED_HOT_CACHE_DURATION_SECS>
    • Runtime: scope serve; default 120; values —; reload restart required
    • Rules: —
  • NGIT_RELAY_DATA_PATH — Path to store Nostr relay data Path to the LMDB relay data directory (contains the nostr event database). Defaults to ./data/relay (same default as the relay itself). Relay data path containing the holding LMDB directory
    • CLI: --relay-data-path <RELAY_DATA_PATH>
    • Runtime: scope shared; default ./data/relay; values —; reload restart required
    • Rules: —
  • NGIT_RELAY_DESCRIPTION — Relay description for NIP-11 information document
    • CLI: --relay-description <RELAY_DESCRIPTION>
    • Runtime: scope serve; default Git Nostr Relay - a grasp implementation; values —; reload restart required
    • Rules: —
  • NGIT_RELAY_FILTER_LIMIT — Per-filter result cap, including when a filter omits limit
    • CLI: --relay-filter-limit <RELAY_FILTER_LIMIT>
    • Runtime: scope serve; default 500; values —; reload restart required
    • Rules: relay-limits-positive
  • NGIT_RELAY_MAX_EVENT_SIZE_BYTES — Maximum serialized event size in bytes
  • NGIT_RELAY_MAX_SUBSCRIPTIONS — Maximum active REQ subscriptions per WebSocket connection
    • CLI: --relay-max-subscriptions <RELAY_MAX_SUBSCRIPTIONS>
    • Runtime: scope serve; default 500; values —; reload restart required
    • Rules: relay-limits-positive
  • NGIT_RELAY_NAME — Relay name for NIP-11 information document (defaults to "${domain} grasp relay")
    • CLI: --relay-name <RELAY_NAME_OVERRIDE>
    • Runtime: scope serve; default —; values —; reload restart required
    • Rules: —
  • NGIT_RELAY_OWNER_NSEC (secret) — Read the relay_owner_nsec systemd credential when it exists. Read the process environment, including an automatically loaded .env file; an existing process variable wins over .env. Read .relay-owner.nsec from the working directory, or generate it with owner-only permissions when absent.
  • NGIT_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)
    • CLI: --repository-blacklist <REPOSITORY_BLACKLIST>
    • Runtime: scope serve; default empty string; values —; reload restart required
    • Rules: —
  • NGIT_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
  • NGIT_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.
  • NGIT_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.
    • CLI: --sync-allow-non-global-targets
    • Runtime: scope serve; default false; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --sync-base-backoff-secs <SYNC_BASE_BACKOFF_SECS>
    • Runtime: scope serve; default 5; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --sync-bootstrap-relay-url <SYNC_BOOTSTRAP_RELAY_URL>
    • Runtime: scope serve; default —; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --sync-disable-negentropy
    • Runtime: scope serve; default false; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --sync-disconnect-check-interval-secs <SYNC_DISCONNECT_CHECK_INTERVAL_SECS>
    • Runtime: scope serve; default 60; values —; reload restart required
    • Rules: —
  • NGIT_SYNC_MAX_BACKOFF_SECS — Maximum backoff time in seconds for sync relay reconnection (default: 3600 = 1 hour)
    • CLI: --sync-max-backoff-secs <SYNC_MAX_BACKOFF_SECS>
    • Runtime: scope serve; default 3600; values —; reload restart required
    • Rules: —
  • NGIT_SYNC_PLUS_ENABLED — Enable GRASP-03 Sync+ mailbox discovery on top of proactive GRASP-02 sync
    • CLI: --sync-plus-enabled <SYNC_PLUS_ENABLED>
    • Runtime: scope serve; default true; values true, false; reload restart required
    • Rules: —
  • NGIT_SYNC_PLUS_FALLBACK_RELAYS — Comma-separated inbox fallbacks for eligible authors whose NIP-65 relay list is absent
    • CLI: --sync-plus-fallback-relays <SYNC_PLUS_FALLBACK_RELAYS>
    • Runtime: scope serve; default wss://relay.ditto.pub,wss://relay.damus.io,wss://nos.lol,wss://relay.primal.net; values —; reload restart required
    • Rules: —
  • NGIT_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
    • CLI: --sync-recursive-descendant-limit <SYNC_RECURSIVE_DESCENDANT_LIMIT>
    • Runtime: scope serve; default 500; values —; reload restart required
    • Rules: sync-descendant-limit-positive
  • NGIT_TRUSTED_PROXY_CIDRS — Proxy address ranges allowed to supply client IP forwarding headers. Empty by default so forwarded headers from direct clients are ignored.
    • CLI: --trusted-proxy-cidrs <TRUSTED_PROXY_CIDRS>
    • Runtime: scope serve; default —; values —; reload restart required
    • Rules: —
  • NGIT_USER_INDEX_RELAYS — Comma-separated relays used to publish the relay-owner identity and to discover eligible accepted repository participants' NIP-65 relay lists
    • CLI: --user-index-relays <USER_INDEX_RELAYS>
    • Runtime: scope serve; default wss://purplepag.es,wss://index.hzrd149.com,wss://indexer.coracle.social; values —; reload restart required
    • Rules: —

Git collaboration, without the platform.

MIT licensed · guides reviewed against ngit 3.0.0-rc.7