Nexus PDP configuration reference
This reference lists the environment variables that configure Permit Nexus PDP (permitio/pdp-v3), a self-hosted policy decision point (PDP). It is for operators who deploy and tune Nexus PDP. The only required variable is PDP_API_KEY. For deployment requirements such as volumes, probes, and memory, see Deploy Nexus PDP.
As of September 2026, Nexus PDP is in early access. Permit can rename, replace, or remove the variables and defaults on this page before general availability. Pin the Nexus PDP image to a specific tag, and check this page when you upgrade. If you depend on a specific variable, tell Permit support at support@permit.io.
The container PDP (the Edge PDP image permitio/pdp-v2) uses a different set of variables. See the container PDP configuration reference. A variable with the same name can mean something different on each PDP type.
Credentials
| Variable | Default | Description |
|---|---|---|
PDP_API_KEY | Required | The API key of the Permit environment this Nexus PDP serves. |
PDP_API_KEY is the only credential Nexus PDP needs. The PDP_API_KEY value:
- binds the container to exactly one Permit environment,
- authenticates the container to Permit's control plane,
- carries the address of the control plane, so Nexus PDP connects without a separate URL setting,
- is the bearer token that the Nexus PDP authorization API accepts from your services.
Leave PDP_CONTROL_PLANE unset unless Permit support asks you to set it. On the container PDP, PDP_CONTROL_PLANE is the Permit API URL. On Nexus PDP, PDP_CONTROL_PLANE overrides the control-plane address that PDP_API_KEY carries.
Storage and ports
| Variable | Default | Description |
|---|---|---|
EDGE_DB_PATH | /var/lib/edge-pdp/db | Directory of the embedded database. Must be on a persistent volume. |
EDGE_DATA_DIR | /var/lib/edge-pdp | Directory of the event store and generated credentials. Must be on a persistent volume. |
EDGE_PUBLIC_PORT | 7000 | Port of the authorization API, the only port your services call. |
EDGE_HEALTH_PORT | 7001 | Port of the health and readiness endpoints. Point probes at this port, not at the authorization port. |
Both storage paths must be on persistent storage that survives restarts. On ephemeral storage, every restart runs a full cold start. See Nexus PDP deployment requirements.
Nexus PDP also uses ports 7002, 7003, 8181, 4222, and 8222 internally, bound to loopback only. See Ports used by Nexus PDP. Expose only the ports set by EDGE_PUBLIC_PORT and EDGE_HEALTH_PORT.
Behavior and tuning
| Variable | Default | Description |
|---|---|---|
RUST_LOG | info | Log level of Nexus PDP. Set info,edge_pdp=debug to add Nexus PDP debug logs. |
PDP_DEBUG | Unset (off) | Set to true to add debug information to policy evaluation requests. |
OPA_TIMEOUT_MS | 800 | Timeout for each policy evaluation request to Open Policy Agent (OPA), in milliseconds. |
EDGE_PARALLELISM | 4 | Number of change transactions Nexus PDP applies concurrently. |
EDGE_DECISION_LOG_OPT_OUT | false | Set to true to stop sending decision logs to Permit. |
EDGE_DRAIN_TIMEOUT_SECS | 10 | Seconds that in-flight requests have to finish during shutdown before Nexus PDP aborts them. |
EDGE_CHILD_TERMINATION_TIMEOUT_SECS | 30 | Seconds that OPA and the NATS leaf node have to stop after SIGTERM before Nexus PDP sends SIGKILL. |
Set the Kubernetes terminationGracePeriodSeconds to at least EDGE_DRAIN_TIMEOUT_SECS plus EDGE_CHILD_TERMINATION_TIMEOUT_SECS, which is 40 seconds at the defaults. See Nexus PDP deployment requirements.
Child process logging
| Variable | Default | Description |
|---|---|---|
EDGE_NATS_LOG_LEVEL | Follows RUST_LOG | Log level of the NATS leaf node that connects to the control plane: info, debug, or trace. |
EDGE_OPA_LOG_LEVEL | Follows RUST_LOG | Log level of OPA: debug, info, or error. |
EDGE_NATS_LOG_LEVEL=trace logs raw message payloads, which contain your authorization data. EDGE_OPA_LOG_LEVEL=debug logs authorization request and response bodies. Set these levels only for short debugging sessions, and remove them before the container serves production traffic.
Storage engine
The Nexus PDP embedded database (SurrealDB on RocksDB) uses storage-engine defaults sized for large workloads, not for a small container. These variables have the largest effect on memory use:
| Variable | Default | Effect |
|---|---|---|
SURREAL_ROCKSDB_BLOCK_CACHE_SIZE | 536870912 (512 MiB) | Size of the read cache. The largest contributor to resident memory. |
SURREAL_ROCKSDB_WRITE_BUFFER_SIZE | 268435456 (256 MiB) | Size of each in-memory write buffer before RocksDB flushes it to disk. |
SURREAL_ROCKSDB_MAX_WRITE_BUFFER_NUMBER | 32 | Maximum number of write buffers in memory at once. |
SURREAL_ROCKSDB_BACKGROUND_THREADS | 4 | Number of background compaction threads. |
At these defaults, a container with a memory limit of a few hundred MiB is killed for running out of memory (OOM) at startup. Start with 4 GiB of memory, then lower these values while you load test against your own data set. See Nexus PDP resource footprint.
Next steps
- Deploy Nexus PDP: storage, probes, logs, and the security model
- How Nexus PDP syncs data: sync, consistency, cold start, and sizing
- Nexus PDP architecture: the processes and ports inside the container
- Nexus PDP feature parity: supported endpoints and capabilities
- Container PDP configuration reference: environment variables for
permitio/pdp-v2