DEV Community

The Seventeen
The Seventeen

Posted on

Self-Hosting AgentSecrets: Own Your Secrets with Total Privacy

#ai #opensource #tutorial #agents

One of the foundational design principles of AgentSecrets is openness and data sovereignty.

While the managed cloud exists for teams that want hands-off infrastructure, you don't have to send your encrypted data to third-party servers if you don't want to. You can self-host the AgentSecrets server backend on your own VPS, home lab, or local server, keep all encrypted credentials in your own PostgreSQL database, and use the official AgentSecrets CLI binary on your workstation with zero compromises.

In this guide, we will walk through how to spin up your own private AgentSecrets server in under 5 minutes and point your official CLI binary to it.

1. Why Self-Host?

When you self-host the AgentSecrets server:

  • 100% Privacy & Ownership: Your encrypted credential blobs, workspace configurations, and team metadata reside exclusively in your own private PostgreSQL database.
  • Use the Official Binary: You don't need to fork, build from source, or maintain custom code. You install the official agentsecrets binary on macOS, Linux, or Windows (brew, npm, pip, or go), and point it to your private endpoint with a single command.
  • Zero-Knowledge by Default: Even though you control the server, the server still never sees plaintext secrets. All credentials are encrypted client-side via AES-256-GCM using your local hardware keychain before transmission.
  • Air-Gapped & Homelab Friendly: Run it locally in Docker, on a \$5 DigitalOcean / Hetzner droplet, or inside an internal private network.

2. Deploying the Server with Docker Compose

The AgentSecrets server backend (agentsecrets-server) is a lightweight asynchronous Python/Django Ninja service backed by PostgreSQL. The fastest and cleanest way to run it is via Docker Compose.

Step 1: Clone the Server Repository

On your server or local machine:

git clone https://github.com/The-17/agentsecrets-server.git
cd agentsecrets-server
Enter fullscreen mode Exit fullscreen mode

Step 2: Generate Keys and Create .env

Run this one-liner to generate secure cryptographic keys and bootstrap your 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
Enter fullscreen mode Exit fullscreen mode

What These Do:

  • SECRET_KEY: Internal cryptographic signing key for session tokens.
  • ENCRYPTION_KEY: A 32-byte Fernet key used by the server to apply an extra layer of envelope encryption over data before saving it to PostgreSQL.
  • RUN_MIGRATIONS=true: Automatically provisions database tables on startup.

Step 3: Start the Containers 

docker-compose up -d
Enter fullscreen mode Exit fullscreen mode

Step 4: Verify Server Health

Check that the server is online and connected to the database:

curl http://localhost:8000/api/status/health/
Enter fullscreen mode Exit fullscreen mode

Expected output:

{"status": "ok", "database": "connected"}
Enter fullscreen mode Exit fullscreen mode

3. Adding HTTPS with Caddy (Recommended for VPS)

If you are hosting on a public VPS (e.g. secrets.yourdomain.com), put Caddy in front of port 8000. Caddy automatically handles Let's Encrypt SSL certificates with zero manual renewal configuration.

Install Caddy, then add this to /etc/caddy/Caddyfile:

secrets.yourdomain.com {
    reverse_proxy 127.0.0.1:8000
    encode gzip
}
Enter fullscreen mode Exit fullscreen mode

Reload Caddy:

sudo systemctl reload caddy
Enter fullscreen mode Exit fullscreen mode

Verify your SSL endpoint:

curl https://secrets.yourdomain.com/api/status/health/
# {"status": "ok", "database": "connected"}
Enter fullscreen mode Exit fullscreen mode

4. Connecting the Official CLI Binary

Now that your server is running, switch to your developer workstation (Mac, Linux, or Windows).

Step 1: Install the Official Binary

If you haven't already, install the standard CLI:

:::tabs

Homebrew (macOS & Linux) 

brew install The-17/tap/agentsecrets
Enter fullscreen mode Exit fullscreen mode

npm 

npm install -g @the-17/agentsecrets
Enter fullscreen mode Exit fullscreen mode

pip 

pip install agentsecrets-cli
Enter fullscreen mode Exit fullscreen mode

Go 

go install github.com/The-17/agentsecrets/cmd/agentsecrets@latest
Enter fullscreen mode Exit fullscreen mode

:::

For all installation methods, see the Installation Documentation.

Step 2: Point Your CLI to Your Self-Hosted Server

Run agentsecrets server set followed by your server's URL:

agentsecrets server set https://secrets.yourdomain.com
Enter fullscreen mode Exit fullscreen mode

(If testing locally on the same machine, use http://localhost:8000).

Output: 

Configure AgentSecrets Server
  ──────────────────────────────
  Target URL: https://secrets.yourdomain.com
* Server reachable (ping: 32ms)
* Saved server URL globally (~/.agentsecrets/config.json).

Commands will now communicate with this AgentSecrets server.
Enter fullscreen mode Exit fullscreen mode

Verify the connection:

agentsecrets server status
Enter fullscreen mode Exit fullscreen mode

Output: 

Server Connection Status
  ──────────────────────────────
  Server Type:   Self-Hosted Server (Custom URL)
  Endpoint:      https://secrets.yourdomain.com
  Config Source: Global config (~/.agentsecrets/config.json)
  Status:        HEALTHY (HTTP 200)
  Latency:       32ms
Enter fullscreen mode Exit fullscreen mode

[!TIP]
You can switch back to the official cloud at any time by running:

agentsecrets server reset

5. Setting Up Your Account & Storing Secrets

Once pointed to your server, everything works just like the standard AgentSecrets workflow:

1. Initialize Your Identity 

agentsecrets init --storage-mode 1
Enter fullscreen mode Exit fullscreen mode
  • Generates your local cryptographic keypair on your machine.
  • Binds your secrets locally to the native OS Keychain (macOS Keychain, Linux Secret Service, Windows DPAPI).

2. Create a Project & Add Secrets 

# Create a project context
agentsecrets project create my-app

# Set your secrets (saved locally in Keychain & synced to your private server)
agentsecrets secrets set OPENAI_API_KEY=sk-proj-12345...
agentsecrets secrets set STRIPE_KEY=sk_live_67890...
Enter fullscreen mode Exit fullscreen mode

Inspect your stored keys safely:

agentsecrets secrets list
Enter fullscreen mode Exit fullscreen mode

Actual Terminal Output: 

Environment: development

Key             DEV    STAGING    PROD
OPENAI_API_KEY   *        -        -
STRIPE_KEY       *        -        -

Showing cached keys. Use --remote for latest from cloud.
Enter fullscreen mode Exit fullscreen mode

Your secrets are now safely synced to your private server and encrypted client-side. Even you, looking at the PostgreSQL database directly, will only see double-encrypted ciphertext.

6. Project-Scoped Pinning & Team Sharing

Pinning a Project to Your Private Server

If you work on public open-source projects using the default cloud, but have a specific company repository that must use your private self-hosted server, pin the server per-project:

cd /path/to/private-project
agentsecrets server set https://secrets.yourdomain.com --project
Enter fullscreen mode Exit fullscreen mode

This saves the endpoint inside .agentsecrets/project.json. Anyone cloning that repository with the proper permissions will communicate directly with your private server.

Automated Backups

To back up your self-hosted vault, take a standard PostgreSQL snapshot:

docker exec -t $(docker ps -qf "name=db") pg_dump -U postgres agentsecrets > "agentsecrets_backup_$(date +%Y%m%d).sql"
Enter fullscreen mode Exit fullscreen mode

Because all secret values in the database are already encrypted with client-side AES-256-GCM and server-side Fernet, your backup file contains zero plaintext credentials.

Conclusion & Documentation Links

Self-hosting AgentSecrets gives you the best of both worlds: uncompromising privacy and data ownership on the backend, combined with the polished, zero-exposure developer experience of the official CLI binary on your workstation.

Continue Reading in the Official Documentation:

Top comments (0)