Self-Hosting Operations Manual

Step-by-step production runbook for deploying, securing, maintaining, and scaling self-hosted AgentSecrets Server clusters.

Deployment Architecture

                    Public Internet / VPC Edge
                                │
                                ▼
                   ┌──────────────────────────┐
                   │    Cloudflare / Caddy    │ (TLS Termination, WAF, Rate Limiting)
                   │      Ports 80 / 443      │
                   └────────────┬─────────────┘
                                │
                                ▼
                   ┌──────────────────────────┐
                   │   AgentSecrets Server    │ (Uvicorn ASGI Workers)
                   │        Port 8000         │
                   └────────────┬─────────────┘
                                │
                  ┌─────────────┴─────────────┐
                  ▼                           ▼
     ┌────────────────────────┐  ┌────────────────────────┐
     │   PostgreSQL Cluster   │  │   Daily Metrics Cron   │
     │      Port 5432         │  │    calculate_metrics   │
     └────────────────────────┘  └────────────────────────┘

1Quick Start: Docker Compose

For rapid evaluation and local team testing:

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

</div>



# Create environment file
cat <<EOF > .env
SETTINGS=core.settings.prod
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
ENCRYPTION_KEY=$(python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
ALLOWED_HOSTS=*
POSTGRES_DB=agentsecrets
POSTGRES_USER=postgres
POSTGRES_PASSWORD=$(python3 -c "import secrets; print(secrets.token_hex(16))")
POSTGRES_HOST=db
POSTGRES_PORT=5432
POSTGRES_SSLMODE=disable
RUN_MIGRATIONS=true
COLLECT_STATIC=true
EOF

# Launch
docker-compose up -d

Verify the server is healthy:

curl http://localhost:8000/api/status/health/

2Zero-Disk Hardening: Ingest & Delete

Once the server stack is active, remove unencrypted plaintext files from disk by ingesting the bootstrap environment directly into AgentSecrets:


</div>



# 1. Point CLI to your self-hosted server
agentsecrets server set http://localhost:8000
agentsecrets init

# 2. Create infrastructure project and push secrets
agentsecrets project create agentsecrets-server
agentsecrets secrets push

# 3. Securely delete plaintext bootstrap file
rm .env

# 4. Run future lifecycle operations with in-memory injection
agentsecrets exec -- docker-compose up -d

2Production Enterprise Deployment

Infrastructure Checklist

Virtual Machine: Ubuntu 22.04 LTS or Debian 12 (minimum 2 vCPU, 4 GB RAM).
Dedicated Database: Managed PostgreSQL 15+ (AWS RDS, Google Cloud SQL, Neon, Supabase) with SSL enabled.
DNS Record: An A or CNAME record pointing to your server IP (e.g. api.agentsecrets.yourcompany.com).
Reverse Proxy: Nginx or Caddy with automated Let's Encrypt TLS certificates.

Step-by-Step Server Setup

1. System User & Environment

sudo useradd -m -s /bin/bash agentsecrets
sudo -u agentsecrets git clone https://github.com/The-17/agentsecrets-server.git /home/agentsecrets/app
cd /home/agentsecrets/app

python3 -m venv env
source env/bin/activate
pip install -r requirements.txt

2. Configure Production Secrets

Create /home/agentsecrets/app/.env with strict 0600 permissions:

SETTINGS=core.settings.prod
SECRET_KEY=<SECURE_DJANGO_SECRET>
ENCRYPTION_KEY=<FERNET_32_BYTE_BASE64_KEY>
ALLOWED_HOSTS=api.agentsecrets.yourcompany.com
POSTGRES_DB=agentsecrets
POSTGRES_USER=agentsecrets_user
POSTGRES_PASSWORD=<STRONG_POSTGRES_PASSWORD>
POSTGRES_HOST=your-postgres-host.rds.amazonaws.com
POSTGRES_PORT=5432
POSTGRES_SSLMODE=require

sudo chmod 600 /home/agentsecrets/app/.env
sudo chown agentsecrets:agentsecrets /home/agentsecrets/app/.env

3. Database Schema Initialization

source env/bin/activate
python manage.py migrate --noinput
python manage.py collectstatic --noinput

4. systemd Service Configuration

Create /etc/systemd/system/agentsecrets.service:

[Unit]
Description=AgentSecrets Server Production ASGI
After=network.target

[Service]
User=agentsecrets
Group=agentsecrets
WorkingDirectory=/home/agentsecrets/app
EnvironmentFile=/home/agentsecrets/app/.env
ExecStart=/home/agentsecrets/app/env/bin/gunicorn -k uvicorn.workers.UvicornWorker core.asgi:application --bind 127.0.0.1:8000 --workers 4 --timeout 60
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now agentsecrets

5. TLS Reverse Proxy (Caddy Example)

Create /etc/caddy/Caddyfile:

api.agentsecrets.yourcompany.com {
    reverse_proxy 127.0.0.1:8000
    encode gzip
}

sudo systemctl reload caddy

3Configuring Clients to Use Your Self-Hosted Server

Global Developer Setup

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

Pinning a Single Project

cd /path/to/my-repo
agentsecrets server set https://api.agentsecrets.yourcompany.com --project

Automated CI/CD Pipelines

export AGENTSECRETS_SERVER_URL="https://api.agentsecrets.yourcompany.com"
agentsecrets env -- npm test

4Key Rotation & Disaster Recovery

Key Rotation

To rotate ENCRYPTION_KEY without data loss, provide both keys separated by comma:

ENCRYPTION_KEY="<NEW_PRIMARY_KEY>,<OLD_DECRYPTION_KEY>"

Then run the migration utility:

python manage.py rotate_encryption_key

Automated Backups

pg_dump -U agentsecrets_user -h your-db-host -d agentsecrets -Fc > "agentsecrets_backup_$(date +%Y%m%d).dump"

For full reference details and API specifications, see the Self-Hosting Architecture Reference.