Security

Nova is designed to run locally on your own hardware. This page covers the security mechanisms that protect your instance, your data, and your infrastructure from unintended agent actions.

Authentication

Admin secret

The admin secret (ADMIN_SECRET in .env) protects privileged operations like key management, pod configuration, service restarts, and factory resets. It is passed as a header:

X-Admin-Secret: your-admin-secret

The Dashboard stores the admin secret in localStorage and sends it with every request.

API keys

API keys authenticate external consumers (IDE plugins, scripts, CI/CD pipelines). Keys use the format sk-nova-<random> and are hashed with SHA-256 before storage — the raw key is shown exactly once at creation and can never be retrieved again.

# Create a key (admin only)
curl -X POST http://localhost:8000/api/v1/keys \
  -H "X-Admin-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "rate_limit_rpm": 60}'

Keys can be passed via either header:

Authorization: Bearer sk-nova-...
X-API-Key: sk-nova-...

Development bypass

When REQUIRE_AUTH=false (the default), API key authentication is bypassed. The admin secret is always required for admin endpoints regardless of this setting.

Rate limiting

Nova enforces rate limits using a Redis sliding window counter. Limits are applied at two levels:

Level	Mechanism	Configuration
Per API key	Requests per minute (RPM)	Set at key creation via rate_limit_rpm
Per provider	Daily request quota	Built into the LLM Gateway per provider

When a rate limit is exceeded, the API returns HTTP 429 with a descriptive error message.

Sandbox tiers

Sandbox tiers control what agents can access when executing tools. Each pod is configured with a sandbox tier that restricts filesystem access and shell execution scope.

Tier	Filesystem access	Shell execution	Use case
Isolated	None — ephemeral only	Ephemeral container per invocation	Pure computation, API calls, text tasks
Nova	Nova installation directory at /nova	Path-constrained to /nova	Self-configuration — updating settings, prompts
Workspace (default)	Scoped to NOVA_WORKSPACE at /workspace	Path-constrained to /workspace	Coding projects, file generation
Host	Full host filesystem	Unrestricted subprocess	DevOps, system administration (explicit opt-in)

The sandbox tier is enforced by the Orchestrator’s tool execution layer. The workspace tier is the default and recommended for most use cases.

Path traversal protection

All file operations validate paths against the configured workspace root. Attempts to access files outside the allowed directory (e.g., ../../etc/passwd) are rejected before any filesystem operation occurs.

Shell command denylist

The run_shell tool maintains a denylist of dangerous command prefixes that are blocked before execution. This provides a defense-in-depth layer on top of sandbox tiers.

Data privacy

Nova is designed to run entirely on your own infrastructure:

• No telemetry — Nova sends no usage data, analytics, or crash reports to any external service
• No cloud dependency — all services run locally in Docker containers; cloud LLM providers are optional
• Local storage — all data (memories, tasks, keys, configurations) is stored in your PostgreSQL instance
• Secret masking — the Recovery Service masks sensitive values (API keys, secrets) when reading environment variables via the API
• Whitelist enforcement — the Recovery Service restricts .env access to a whitelist of known Nova configuration keys

Best practices

1. Change the default admin secret — the first thing to do after installation
2. Enable REQUIRE_AUTH=true in production to enforce API key authentication
3. Use the workspace sandbox tier unless you have a specific need for broader access
4. Keep backups — use the Recovery Service or make backup regularly
5. Review API keys — revoke unused keys from the Keys page in the Dashboard
6. Use Cloudflare Tunnel or Tailscale for remote access instead of exposing ports directly