Skip to main content
agtOS is designed for self-hosted deployment where you control your own data. This page consolidates all security features and configuration.

​
API Authentication

REST API authentication is opt-in. When the AGTOS_API_KEY environment variable is set, all /api/* endpoints require a Bearer token. 
# Enable authentication
AGTOS_API_KEY=your-secret-key-here

# Authenticated request
curl -H "Authorization: Bearer your-secret-key-here" \
  http://localhost:4102/api/health
Exempt paths (never require auth):
  • /health and sub-paths — for monitoring and health checks
  • /metrics — for Prometheus scraping
  • /api/credentials — localhost-only, needed during onboarding
The API key is compared using SHA-256 hashing with crypto.timingSafeEqual to prevent timing attacks.
In production, always set AGTOS_API_KEY. Without it, all API endpoints are unauthenticated — anyone on the network can access them.

​
Rate Limiting

All API endpoints are rate-limited using a token bucket algorithm per client IP:
ScopeDefaultConfig Variable
General API (/api/*)100 req/minAPI_RATE_LIMIT
Chat, Tasks, Credentials20 req/minCHAT_RATE_LIMIT
Rate limit headers are included on every response (X-RateLimit-Remaining). Exceeded requests receive 429 Too Many Requests.

​
Credential Encryption

API keys for cloud providers (Claude, OpenAI, OpenRouter) are encrypted at rest using AES-256-GCM:
  • Algorithm: AES-256-GCM (authenticated encryption)
  • Key derivation: PBKDF2 with 100,000 iterations
  • Salt: Configurable via AGTOS_CREDENTIAL_SALT (hex-encoded 16 bytes)
  • IV: Random 16 bytes per encryption
# Generate a production salt
node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"

# Set in production
AGTOS_CREDENTIAL_SECRET=your-secret-here
AGTOS_CREDENTIAL_SALT=a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6
In development, a default secret is used and the salt is randomized per restart. In production, set both AGTOS_CREDENTIAL_SECRET and AGTOS_CREDENTIAL_SALT for persistent encrypted credential storage.

​
Device Authentication

Hardware devices (ESP32, browsers) authenticate using per-device shared secrets. The secret is hashed with SHA-256 before storage — the plaintext is never persisted. Devices progress through a trust lifecycle:
Trust LevelValueMeaning
Anonymous0No authentication
Basic1API key authenticated
Verified2Device-specific secret provided
Trusted3Verified + established history

​
Input Validation

All POST endpoints validate input with Zod schemas:
  • Text limits: Chat messages max 10,000 characters, memory questions max 2,000 characters
  • Body size: Request bodies capped at 1 MB
  • ID format: Path parameter IDs must match ^[a-zA-Z0-9\-_]+$ (1-128 characters)
  • Type safety: All fields are type-checked with constraints (min/max, enums, patterns)
Invalid input returns 400 Bad Request with field-level error details.

​
Network Security

​
CORS

Cross-Origin Resource Sharing is configured via CORS_ORIGIN: 
# Default: localhost only
CORS_ORIGIN=http://localhost:5173

# Allow all origins (not recommended for production)
CORS_ORIGIN=*

# Multiple origins
CORS_ORIGIN=https://app.example.com,https://admin.example.com
Tauri desktop app origins (tauri://localhost, https://tauri.localhost) are always included automatically.

​
Credential Storage Endpoint

POST /api/credentials is localhost-only — requests from non-loopback addresses receive 403 Forbidden. This ensures API keys can only be stored from the same machine during onboarding.

​
mDNS

mDNS device discovery is opt-in (AGTOS_MDNS_ENABLED=false by default). When enabled, agtOS broadcasts its presence on the local network for zero-config ESP32 discovery. Disable in untrusted network environments.

​
Data Privacy

  • BYOK (Bring Your Own Key) — agtOS never stores or transmits your API keys to any third party. Keys are encrypted locally and used only for direct API calls to the providers you configure.
  • Local-first — all processing (voice, memory, scheduling) runs on your machine. Cloud providers receive only the messages you send to them.
  • Memory controls — configurable retention period (default 30 days), per-user privacy settings, and explicit delete APIs.
  • No telemetry — agtOS does not collect usage data, analytics, or crash reports.

​
Production Checklist

1

Set AGTOS_API_KEY

Protect all API endpoints with Bearer token authentication.
2

Set credential encryption secrets

Set AGTOS_CREDENTIAL_SECRET and AGTOS_CREDENTIAL_SALT for persistent credential storage across restarts.
3

Configure CORS

Restrict CORS_ORIGIN to your specific frontend domains.
4

Set NODE_ENV=production

Enables structured JSON logging and enforces credential salt requirements.
5

Review rate limits

Adjust API_RATE_LIMIT and CHAT_RATE_LIMIT based on expected traffic.
6

Disable mDNS

Keep AGTOS_MDNS_ENABLED=false unless you need ESP32 zero-config discovery.