Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agtos.ai/llms.txt

Use this file to discover all available pages before exploring further.

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/validate — read-only key validation
  • /api/setup-token — localhost-only, onboarding token retrieval
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 in ~/.agtos/credentials.json using AES-256-GCM:
  • Algorithm: AES-256-GCM (authenticated encryption with AAD binding per provider)
  • Key derivation: scrypt (N=16384, r=8, p=1) — auto-migrates legacy PBKDF2 files
  • Salt: 32 bytes, persisted at ~/.agtos/.salt (auto-generated on first use)
  • Machine secret: 32 bytes, persisted at ~/.agtos/.secret (auto-generated on first use)
  • IV: Random 12 bytes per encryption (per NIST SP 800-38D)
  • File permissions: 0o600 (owner read/write only)
# For Docker/CI — set these env vars so credentials persist across restarts
AGTOS_CREDENTIAL_SECRET=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
AGTOS_CREDENTIAL_SALT=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
On desktop/local installs, the machine secret and salt are auto-generated and persisted to ~/.agtos/. No manual configuration is needed. For Docker deployments, set AGTOS_CREDENTIAL_SECRET and AGTOS_CREDENTIAL_SALT as environment variables.

​
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 and requires authentication (API key or setup token) — 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

For Docker/CI, set AGTOS_CREDENTIAL_SECRET and AGTOS_CREDENTIAL_SALT env vars for persistent encrypted credential storage across container restarts. Desktop installs auto-generate these at ~/.agtos/.secret and ~/.agtos/.salt.
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.