Security

This page is for operators securing a Dakera v0.12.3 deployment. It covers authentication and permissions, encryption at rest and key rotation, cluster and gRPC authentication, CORS, rate limits, input validation, audit logging, and a production checklist.

Every request passes through rate limiting, authentication and input validation before it reaches the engine. Memory content can be encrypted at rest with AES-256-GCM, and every request is written to an audit log.

Security layers

Input validation

Validation is always on. A value that matches one of these patterns is refused with 400, and the message names the rule it broke:

Filters accept only the documented operators. Outbound URLs that a caller can choose (such as extractor_override.base_url) are checked against private and reserved address ranges; see Limits and hardening.

Field limits

Security headers

Dakera sets these response headers by default (enabled unless noted):

Dakera does not terminate TLS; set HSTS at the reverse proxy as well if it terminates TLS for you. There are no preset names to select: the headers above are what the environment variables configure.

export DAKERA_HSTS_MAX_AGE=63072000
  export DAKERA_FRAME_OPTIONS=SAMEORIGIN

CORS and cross-origin protection

Clients that send no Origin header (SDKs, curl, servers) and GET, HEAD and OPTIONS requests are never refused by the cross-origin check.

TLS and HTTPS

Dakera does not terminate TLS. Terminate it at a reverse proxy or load balancer (Nginx, Caddy, Traefik or a cloud load balancer) in front of the REST and gRPC ports.

See Deployment → Reverse proxy & TLS termination for complete Nginx and Caddy configurations. For gRPC, configure mTLS at the proxy level when client certificate authentication is required.

Encryption at rest

With DAKERA_ENCRYPTION_KEY set, memory content, text documents (_text) and the persisted full-text (BM25) indexes are sealed with AES-256-GCM before they reach storage. The write-ahead log, snapshots, RocksDB files, the disk cache, Redis, S3 objects, backups and cluster replication therefore only carry ciphertext. Nothing else needs configuring and nothing changes for clients: the memory API returns plaintext.

Keyring

The key in DAKERA_ENCRYPTION_KEY is the first data key. Every rotation adds a data key to the keyring, which is stored in the reserved namespace _dakera_keyring, wrapped under a master key derived from DAKERA_ENCRYPTION_KEY (never in the clear), and replicated to every node. Old keys are kept, so values sealed under them keep opening while they are re-sealed and backups taken before a rotation still restore. A key that nothing references any more is marked retired but is still kept for old backups, WAL segments and snapshots. Key material never appears in responses, errors, logs or debug output; only key ids do.

Rotating keys

POST /admin/encryption/rotate-key (global admin scope; /v1/admin/encryption/rotate-key works too).

# One namespace; every other namespace keeps its key
  curl -X POST localhost:3000/admin/encryption/rotate-key \
    -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" \
    -d '{"namespace": "_dakera_agent_alice"}'
  
  # Everything
  curl -X POST localhost:3000/admin/encryption/rotate-key \
    -H "Authorization: Bearer $ADMIN_KEY" -H "Content-Type: application/json" -d '{}'

The response reports key_id, previous_key_id, scope (global or namespace), namespace, reseal (completed, running, or partial: work the background pass retries, such as records written meanwhile or a namespace that could not be read), rotated (values re-sealed by the time of the answer), skipped, namespaces, fulltext_indices_rotated, failed_namespaces, action_required and status_url. Reads keep working throughout. DAKERA_ENCRYPTION_KEY itself does not change after a rotation, and every node re-seals its own copy of the data after receiving the new key through replication.

Status, re-seal and master revocation

Metrics: dakera_encryption_values_resealed_total{kind}, dakera_encryption_values_unreadable, dakera_encryption_reseal_running, dakera_encryption_reseal_namespaces_remaining, dakera_encryption_deferred_writes_total and dakera_encryption_keys{state}. A shipped alert rule fires on unreadable encrypted values (see Operations).

Changing DAKERA_ENCRYPTION_KEY itself

1. Rotate with new_key set to the new value. The keyring is then also wrapped under it.
2. Set DAKERA_ENCRYPTION_KEY to the new value on every node and restart them.
3. Once the key that came from the old passphrase is retired, optionally revoke its master with revoke-master.

Setting a new value without step 1 leaves the keyring, and everything sealed under its keys, unreadable. If encryption at rest is off, a global rotation with new_key turns it on for the running process and the response carries action_required: set DAKERA_ENCRYPTION_KEY to that value before the next restart.

What still holds old ciphertext after a rotation

Until rewritten or expired: WAL segments and snapshots written before the re-seal, RocksDB SST files until compaction, S3 object versions when bucket versioning is on, the disk and Redis caches until the entry is replaced, and backups. All of it stays decryptable with the keyring and none of it is plaintext.

Encrypted backups

POST /admin/backups accepts "encrypt": true (every file of the backup sealed with AES-256-GCM under a key derived from the operator key) and "compression": "zstd"; compression is applied first, then encryption, and both are recorded in the manifest. encrypt without DAKERA_ENCRYPTION_KEY, and "compression": "lz4", are refused with 400. Backups also carry _text sealed (v0.11 backups held it in plaintext). Details: Operations.

Going back to v0.11

dakera downgrade opens every value with the persisted keyring (generated keys, passphrase keys and namespace keys included) and re-seals memory content as $enc$v1$ under DAKERA_ENCRYPTION_KEY, with _text and the BM25 indexes in plaintext, which is what v0.11.108 reads. The keyring is kept, so backups taken under v0.12 still restore with v0.12. Values it cannot open (a key this DAKERA_ENCRYPTION_KEY cannot unwrap) are counted in values_unreadable and make the command exit 1. See Rolling back to v0.11.

Verify

curl -s localhost:3000/admin/encryption/status -H "Authorization: Bearer $ADMIN_KEY" | jq '{enabled, default_key_id, reseal}'
  curl -s localhost:3000/metrics | grep dakera_encryption_values_unreadable   # expect 0

API key authentication

Send the key as Authorization: Bearer <key> or X-API-Key: <key>. DAKERA_ROOT_API_KEY bootstraps a super_admin key; with authentication on (the default) and no key configured, the server exits at startup.

Scope hierarchy

Key grants (v0.12.2)

A key's namespaces is its grant list: null or ["*"] reach every namespace, [] reaches none, and each entry is an exact namespace name or a prefix pattern p* with one trailing star. Patterns are strict: team-* reaches team-a but not team or team-, and a pattern never reaches a server-internal namespace. ["_dakera_agent_mlx-*"] lets a developer key create and use its own agents (POST /v1/agents).

• Validated. Junk entries ("a**b?", blank, "*" mixed with names), internal namespaces and patterns that could cover them (_dakera_*, _*) are refused with 400 on create, edit and extra_namespaces.
• Existing keys never widen. On a key created before v0.12.2, a foo* entry stays a literal name that grants nothing, across restarts, renames and rotations, until its namespaces are saved again with PATCH. Such entries, and a _dakera_sessions entry, are listed in inert_namespaces.
• Edit in place. PATCH /admin/keys/{key_id} (super_admin) renames a key or replaces its namespaces; PATCH /v1/namespaces/{ns}/keys/{key_id} lets a namespace admin do the same within its own grants (a team-* admin can grant team-a*, never t*, * or null). scope cannot be changed.
• Sessions are authorized by their agent's namespace alone; keys no longer need a _dakera_sessions grant.
• Open event streams re-check the key's scope and namespaces every 15 s and close when it no longer qualifies. Deactivation is permanent: no concurrent edit or late replicated add revives a deactivated key.
• Check a key with GET /v1/auth/whoami: it answers the key as the server reads it (scope, namespaces, unrestricted, expires_at, grants_version, inert_namespaces), never the key itself.

API key lifecycle

The complete workflow from bootstrap to rotation:

# 1. Bootstrap root key (set at server start)
export DAKERA_ROOT_API_KEY=$(openssl rand -hex 32)

# 2. Create a scoped application key
curl -X POST http://localhost:3000/admin/keys \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"query-service","scope":"read","expires_in_days":90}'
# {"key_id":"dk_key_1a2b3c4d","key":"dk_...","name":"query-service","scope":"read","namespaces":null,
#  "created_at":1790000000,"expires_at":1797776000,"warning":"..."}   (the key is shown only once)

# 3. Restrict key to a namespace (multi-tenant isolation)
curl -X POST http://localhost:3000/admin/keys \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a","scope":"write","namespaces":["tenant-a"],"expires_in_days":90}'

# 4. List all keys
curl http://localhost:3000/admin/keys \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"

# 5. Monitor key usage (by key_id)
curl http://localhost:3000/admin/keys/dk_key_1a2b3c4d/usage \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"

# 6. Rotate a key, keeping the old one valid for an hour while clients move (v0.12.2)
curl -X POST http://localhost:3000/admin/keys/dk_key_1a2b3c4d/rotate \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"grace_secs":3600}'
# {"new_key":"dk_...","key_id":"dk_key_...","old_key_id":"dk_key_1a2b3c4d","old_key_expires_at":1791395803,...}

# 7. Or revoke a compromised key at once
curl -X DELETE http://localhost:3000/admin/keys/dk_key_1a2b3c4d \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY"

Namespace isolation

Namespaces are the isolation boundary in multi-tenant deployments. A key restricted to namespace tenant-a can read and write only that namespace, and namespace listings show it only the namespaces it can reach.

# Create an isolated namespace for a tenant
curl -X POST http://localhost:3000/v1/namespaces \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a","dimension":1024}'

# Create a key scoped to that namespace
curl -X POST http://localhost:3000/admin/keys \
  -H "Authorization: Bearer $DAKERA_ROOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"tenant-a-app","scope":"write","namespaces":["tenant-a"]}'

Permissions

Keys have one of four scopes (read, write, admin, super_admin, each including the one before) and may be restricted to namespaces. In v0.12.0 a key restricted to namespaces no longer passes checks that only asked for a scope. With authentication off every request is super_admin and none of this applies.

Check namespace-pinned keys and backup tooling before upgrading (Upgrading to v0.12).

gRPC

With authentication on (the default), every RPC except Health needs an API key in the call metadata (x-api-key: <key> or authorization: Bearer <key>), authorized per scope and namespace like its REST twin (UNAUTHENTICATED, PERMISSION_DENIED). Calls draw on the server-wide rate limit (RESOURCE_EXHAUSTED), are bounded by DAKERA_REQUEST_TIMEOUT and, for Query, query_timeout_ms (DEADLINE_EXCEEDED), fail UNAVAILABLE while maintenance mode rejects requests, and are audited.

Cluster authentication

Cluster mode requires DAKERA_CLUSTER_SECRET (at least 16 characters, identical on every node) and a stable DAKERA_CLUSTER_NODE_ID. Generate the secret with openssl rand -hex 32 and store it like any other credential. It authenticates; it does not encrypt — keep node-to-node traffic on a private network or behind TLS.

• Every node-to-node request under /internal/* must carry the secret. On a node that is not in cluster mode these routes answer 404.
• Gossip packets carry an HMAC-SHA256 tag over a send time and a random nonce. An untagged or forged packet is dropped, as is one more than 5 minutes away from the receiver's clock or whose nonce was already seen.
• From v0.12.1 a cluster node without the secret refuses to start, fresh install or upgraded: it exits with code 78 before it serves anything, and dakera --check-config reports a missing or short secret. On v0.12.0 a node upgraded from v0.11 could start without it, with the node-to-node routes open as in v0.11: POST /internal/sync/key/add then let anyone who reached the API port mint a super_admin key. Set the secret on every node and upgrade them in one window (High availability); rotating it needs the same window.
• A node upgraded from v0.11 without a node id generates one once, keeps it in {data root}/cluster-node-id, and is degraded in /health (cluster_auth) until it is set.
• Cluster nodes must not share one S3 bucket (shared_store; see High availability).

Limits and hardening

Telemetry

Telemetry is on by default. It sends lifecycle events and a 6-hourly heartbeat, including the machine's hostname; PostHog also records the connecting IP address and derives a coarse location (GeoIP). It never sends memory content, queries, ids, keys or paths. Turn it off with DAKERA_TELEMETRY=0 or DO_NOT_TRACK=1. Full list: Telemetry.

Rate limiting

Dakera enforces two kinds of limit. The server-wide limit is a token bucket per node; with DAKERA_REDIS_URL set, the nodes share one counter in Redis (falling back to the per-node bucket if Redis does not answer). Per-namespace limits are optional and per minute: set rate_limit_enabled, rate_limit_stores_per_minute and rate_limit_recalls_per_minute in the namespace's memory policy (PUT /v1/namespaces/{ns}/memory_policy).

# Global rate limit
DAKERA_RATE_LIMIT_RPS=100       # requests per second (default; RATE_LIMIT_RPS still works, deprecated)
DAKERA_RATE_LIMIT_BURST=50      # burst capacity

gRPC calls take a token from the same limit.

When rate limited, clients receive a 429 Too Many Requests response with Retry-After header indicating when to retry.

# Example rate-limited response (also sends X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset)
HTTP/1.1 429 Too Many Requests
Retry-After: 1
Content-Type: application/json

{"error":"Rate limit exceeded: 100 requests per second for this server. Resets at Unix time 1790000000.","code":"RATE_LIMIT_EXCEEDED","status":429,"details":"remaining: 0"}

Audit logging

Dakera writes one audit entry per request to the log (target audit), at a level that follows the status code. The entry records the key id, never the key.

Configuration

Body capture runs after authentication, so a rejected request is never read. Bodies are capped, secrets are redacted, and the bodies of key-management and cluster routes (/admin/keys, /admin/cluster, /v1/namespaces/{ns}/keys, and routes that carry keys) are always recorded as [REDACTED]. Secret query parameters such as ?api_key= are logged as [REDACTED]. Enabling capture grows the audit log.

Audit entry

{
    "request_id": "7f3c9a1e-00000042",
    "timestamp": "2026-10-01T10:30:45.123Z",
    "method": "POST",
    "path": "/v1/memory/store",
    "client_ip": "10.0.1.50",
    "user_agent": "curl/8.5.0",
    "api_key_id": "dk_key_1a2b3c4d",
    "status_code": 200,
    "duration_ms": 45,
    "request_size": 412,
    "response_size": 96
  }

request_id is the client's X-Request-ID when it sends one. Optional fields (query, client_ip, user_agent, api_key_id, request_size, response_size, request_body, response_body, error, context) appear only when they have a value. gRPC calls are audited as well.

Security monitoring

Monitor audit logs for:

• Failed authentication attempts (401). The server logs a request without a valid key at DEBUG with at most one WARN per minute counting them; dakera_errors_total{type="auth"} counts every one
• Forbidden access attempts (403)
• Rate limit hits (429)
• Admin operations outside maintenance windows
• Access from unexpected IP ranges

Container security

# Kubernetes security context
securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop: ["ALL"]

Verifying release images (v0.12.3)

Every release tag (:<version>, :cpu, :latest, :gpu, :cuda) is signed by the release workflow, and the signature is recorded in the public Rekor transparency log. Verify an image with cosign v3 or later before you run it (cosign 2.x does not find these signatures), and read its provenance and SBOM:

cosign verify ghcr.io/dakera-ai/dakera:0.12.3 \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  --certificate-identity-regexp '^https://github\.com/(?i:dakera-ai)/dakera/\.github/workflows/release\.yml@refs/tags/v'

docker buildx imagetools inspect ghcr.io/dakera-ai/dakera:0.12.3 --format '{{ json .Provenance }}'
docker buildx imagetools inspect ghcr.io/dakera-ai/dakera:0.12.3 --format '{{ json .SBOM }}'

Images published before v0.12.3 are unsigned.

Network security

# UFW firewall rules for a Dakera node
sudo ufw allow from any to any port 443 proto tcp       # HTTPS via reverse proxy
sudo ufw allow from 10.0.0.0/8 to any port 3000         # REST API from internal network
sudo ufw allow from 10.0.0.0/8 to any port 50051        # gRPC from internal network
sudo ufw allow from 10.0.0.0/8 to any port 7946 proto udp # Gossip between cluster nodes
sudo ufw deny 3000                                       # Block external REST access
sudo ufw deny 50051                                      # Block external gRPC access
sudo ufw deny 7946                                       # Block external gossip access

Production security checklist

Related: Deployment guide (reverse proxy, TLS, firewall setup) · Architecture (trust boundaries, storage layers) · Self-hosted deployment walkthrough