Self-Hosting AgentRQ
Run AgentRQ entirely on your own infrastructure. Your task data never leaves your servers. Apache-2.0 licensed — free to deploy, modify, and redistribute.
Why Self-Host?
Your task data, file attachments, and agent conversations never leave your infrastructure. Run on-prem, in your VPC, or on a local developer machine.
Apache-2.0 licensed. Audit the code, fork it, customize it, or contribute back. The same codebase that powers app.agentrq.com.
Configure your own auth, database, storage, and domain. Run it airgapped if needed. No external service dependencies beyond Google OAuth2.
Run it for your entire team at zero incremental cost. You only pay for the infrastructure you choose to run it on.
Prerequisites
-
Docker — the only runtime dependency. Install from docs.docker.com/get-docker.
-
Google OAuth2 credentials — AgentRQ uses Google Sign-In for authentication. You'll need a Client ID and Client Secret from Google Cloud Console.
-
A domain or localhost — any hostname works. For local use,
http://localhostis fine. For production, point a domain at your server — AgentRQ can handle TLS automatically via Let's Encrypt.
Pull the Docker Image
The official image is published on Docker Hub at hasmcp/agentrq:latest. No build step required — pull and run.
$ docker pull hasmcp/agentrq:latestCreate Your .env File
Create a .env file in your working directory. All configuration is done via environment variables:
# ── App ──────────────────────────────────────────────────
PORT=80
AGENTRQ_BASE_URL=https://your-domain.com
AGENTRQ_DOMAIN=your-domain.com
# ── TLS (built-in Let's Encrypt) ─────────────────────────
# Leave disabled for local use or if running behind a proxy
AGENTRQ_SSL_ENABLED=false
AGENTRQ_SSL_LETSENCRYPT_EMAIL=[email protected]
AGENTRQ_SSL_CACHE_DIR=/_certs
# Optional: Cloudflare DNS challenge for wildcard certs
AGENTRQ_SSL_CLOUDFLARE_API_TOKEN=
# ── Database: SQLite (default) ────────────────────────────
AGENTRQ_SQLITE_ENABLED=true
AGENTRQ_SQLITE_DSN=./_storage/agentrq.db
# ── Database: PostgreSQL (optional, disable SQLite above) ─
AGENTRQ_POSTGRES_ENABLED=false
AGENTRQ_POSTGRES_HOST=localhost
AGENTRQ_POSTGRES_PORT=5432
AGENTRQ_POSTGRES_USER=postgres
AGENTRQ_POSTGRES_PASSWORD=yourpassword
AGENTRQ_POSTGRES_DBNAME=agentrq
# ── Authentication ───────────────────────────────────────
AGENTRQ_AUTH_JWT_SECRET=change-me-to-a-long-random-secret
# Root login for initial setup (disable after first use)
AGENTRQ_AUTH_ROOT_LOGIN_ENABLED=false
AGENTRQ_AUTH_ROOT_ACCESS_TOKEN=change-me
# ── Google OAuth2 ────────────────────────────────────────
AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_SECRET=your-client-secret
# ── SMTP (optional — for email notifications) ────────────
AGENTRQ_SMTP_ENABLED=false
AGENTRQ_SMTP_HOST=smtp.example.com
AGENTRQ_SMTP_PORT=587
AGENTRQ_SMTP_USERNAME=[email protected]
AGENTRQ_SMTP_PASSWORD=yourpassword
AGENTRQ_SMTP_FROM=AgentRQ <[email protected]>true to enable built-in TLS via Let's Encrypt. Requires a public domain and port 80/443 reachable from the internet.ROOT_ACCESS_TOKEN. Useful for initial setup. Disable in production..env to your .gitignore. The file contains secrets — never commit it to version control.Google OAuth2 Setup
AgentRQ uses Google OAuth2 for user authentication. You need to create OAuth2 credentials in Google Cloud Console.
- 1.
-
2.
Click + Create Credentials → OAuth 2.0 Client ID
-
3.
Application type: Web application
-
4.
Add the following Authorized Redirect URI:Redirect URI
https://your-domain.com/api/v1/auth/google/callback -
5.
Click Create — copy the Client ID and Client Secret into your
.envasAGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_IDandAGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_SECRET
http://localhost/api/v1/auth/google/callback as an authorized redirect URI. Google allows multiple redirect URIs per OAuth2 credential.Run with Docker
Run the container, mounting a local directory for persistent storage and passing your .env file:
$ docker run -d \
--name agentrq \
--restart unless-stopped \
-p 80:80 \
--env-file .env \
-v ./data:/_storage \
hasmcp/agentrq:latest
✓ AgentRQ running at http://localhost./data directory into the container. Your SQLite database and file attachments are stored here — it persists across container restarts.-p 443:443 -v ./certs:/_certs$ docker run -d \
--name agentrq \
--restart unless-stopped \
-p 80:80 -p 443:443 \
--env-file .env \
-v ./data:/_storage \
-v ./certs:/_certs \
hasmcp/agentrq:latest
Set AGENTRQ_SSL_ENABLED=true and AGENTRQ_SSL_LETSENCRYPT_EMAIL in your .env to have AgentRQ provision and renew TLS certificates automatically. No reverse proxy needed.
Connect Claude Code to Your Instance
Update .mcp.json in your project to point at your self-hosted server instead of app.agentrq.com. The URL format is identical — only the host changes.
{
"mcpServers": {
"agentrq": {
"type": "http",
"url": "https://WORKSPACE_ID.mcp.your-domain.com/mcp?token=YOUR_TOKEN"
}
}
}
Your Workspace ID and MCP token are generated in your self-hosted dashboard, exactly as with the cloud version. Sign in to your instance at https://your-domain.com, create a workspace, and copy the token.
Database & Storage Notes
Single file at ./_storage/agentrq.db. Zero setup. Great for personal use and small teams.
Back up this file regularly — it contains all your tasks, messages, and workspace config.
Switch to PostgreSQL for multi-user teams, higher concurrency, and managed backups. Set postgres.dsn in config and disable SQLite.
The schema is auto-migrated on startup in both modes.
./_storage/ alongside the SQLite database. Include this directory in your backup strategy. For cloud deployments, consider mounting a persistent volume at this path.
workspaceTokenKey stable. This key encrypts MCP tokens in the database using AES-256-GCM. If you change it, all existing workspace MCP tokens become unreadable and must be regenerated. Back it up along with your database.