Self-Hosting Guide

This guide covers deploying and operating agentsecrets-server on private infrastructure using Docker Compose or standalone Linux servers.

Architecture Overview

                      Internet / Private Network
                                  │
                                  ▼
                     ┌──────────────────────────┐
                     │   Reverse Proxy / TLS    │ (Caddy / Nginx / Traefik)
                     │     Port 80 / 443        │
                     └────────────┬─────────────┘
                                  │
                                  ▼
                     ┌──────────────────────────┐
                     │   agentsecrets-server    │ (Gunicorn + Uvicorn ASGI)
                     │        Port 8000         │
                     └────────────┬─────────────┘
                                  │
                    ┌─────────────┴─────────────┐
                    ▼                           ▼
       ┌────────────────────────┐  ┌────────────────────────┐
       │   PostgreSQL 14+       │  │   Daily Metrics Cron   │
       │      Port 5432         │  │    calculate_metrics   │
       └────────────────────────┘  └────────────────────────┘

Configuration Reference

The server reads configuration from environment variables injected at runtime:

Required Keys

Variable	Description	Example / Generator
`SECRET_KEY`	Django cryptographic signing key	`python3 -c "import secrets; print(secrets.token_urlsafe(50))"`
`ENCRYPTION_KEY`	Fernet 32-byte urlsafe base64 encryption key	`python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
`SETTINGS`	Django settings module path	`core.settings.prod` (production) or `core.settings.dev`
`ALLOWED_HOSTS`	Comma-separated list of valid Host header domains	`api.agentsecrets.yourcompany.com,localhost`
`POSTGRES_DB`	Database name	`agentsecrets`
`POSTGRES_USER`	Database user	`postgres`
`POSTGRES_PASSWORD`	Database password	Strong generated password
`POSTGRES_HOST`	Database hostname	`db` (Docker) or `localhost`
`POSTGRES_PORT`	Database port	`5432`

Optional Keys

Variable	Description	Default
`POSTGRES_SSLMODE`	PostgreSQL SSL connection mode (`require`, `prefer`, `disable`)	`prefer` (cloud) / `disable` (docker)
`CRON_SECRET`	Bearer token for triggering metrics computation via HTTP	None
`LOG_LEVEL`	Application logging verbosity (`INFO`, `WARNING`, `ERROR`)	`INFO`

Deployment with Docker Compose

1Project Setup

git clone https://github.com/The-17/agentsecrets-server.git
cd agentsecrets-server

2Configure Credentials via AgentSecrets

Use the CLI to manage and inject the server's own configuration without writing plaintext .env files to disk:

agentsecrets init
agentsecrets project create agentsecrets-server

agentsecrets secrets set SECRET_KEY="$(python3 -c 'import secrets; print(secrets.token_urlsafe(50))')"
agentsecrets secrets set ENCRYPTION_KEY="$(python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')"
agentsecrets secrets set SETTINGS="core.settings.prod"
agentsecrets secrets set ALLOWED_HOSTS="api.agentsecrets.yourcompany.com,localhost"
agentsecrets secrets set POSTGRES_DB="agentsecrets"
agentsecrets secrets set POSTGRES_USER="postgres"
agentsecrets secrets set POSTGRES_PASSWORD="your-strong-db-password"
agentsecrets secrets set POSTGRES_HOST="db"
agentsecrets secrets set POSTGRES_PORT="5432"

3Launch Containers

docker-compose up -d

The compose stack bootstraps PostgreSQL 16 Alpine, performs database health probes, applies pending database migrations via entrypoint.sh, and starts the ASGI server on port 8000.

Connecting the CLI and SDKs

You can point the AgentSecrets CLI to your self-hosted server globally, per-project, via command-line flags, or using environment variables.

Option A: Using the `server` Command (Recommended)

Set the target server globally across your machine:

agentsecrets server set https://api.agentsecrets.yourcompany.com

Or set it exclusively for a specific repository / project:

agentsecrets server set http://localhost:8000 --project

Check connectivity and latency to your server:

agentsecrets server status

View the active server endpoint and configuration source:

agentsecrets server get

To revert back to the default AgentSecrets Server:

agentsecrets server reset

Option B: Initializing with `--server`

When onboarding or setting up a new project against your self-hosted instance:

agentsecrets init --server https://api.agentsecrets.yourcompany.com
agentsecrets login --server https://api.agentsecrets.yourcompany.com

During interactive agentsecrets init, you can also choose "2. Self-Hosted Server (Custom URL)" when prompted.

Option C: Environment Variables

For automated CI/CD runners or containerized workloads, set the server endpoint via environment variable:

export AGENTSECRETS_SERVER_URL="https://api.agentsecrets.yourcompany.com"
# (AGENTSECRETS_API_URL is also supported for backwards compatibility)

Verify Status

Verify that your CLI is communicating with the intended server:

agentsecrets status

The output displays the active server URL and whether it is the default server or a self-hosted instance.

Health Checks & Monitoring

The server exposes non-destructive diagnostic endpoints:

Probe URL: GET /api/status/health/ (or GET /api/status/)
Behavior: Returns 200 OK when database, cache, and encryption pipelines pass; returns 503 Service Unavailable on degraded subsystems.

Automated Telemetry Rollups

To compute historical DAU/WAU/MAU and platform analytics, trigger calculate_metrics daily:

Option A: System Cron

5 0 * * * cd /path/to/agentsecrets-server && agentsecrets env -- python manage.py calculate_metrics --days 7 >> /var/log/metrics.log 2>&1

Option B: Authenticated HTTP Trigger

curl -X POST https://api.agentsecrets.yourcompany.com/telemetry/internal/compute-metrics/ \
  -H "Authorization: Bearer your-cron-secret"