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 agentrq/agentrq:latest. No build step required — pull
and run.
$ docker pull agentrq/agentrq:latestCreate Your .env File
Create a .env file in your working directory. All
configuration is done via environment variables:
# ── App ──────────────────────────────────────────────────
ENV=production
PORT=80
AGENTRQ_BASE_URL=https://your-domain.com
AGENTRQ_DOMAIN=your-domain.com
# ── Reverse proxy (optional) ─────────────────────────────
# Sub-path the proxy serves AgentRQ under (e.g. /agentrq); the proxy strips it
AGENTRQ_BASE_PATH=
# Public domain of the proxy; requests with this Host skip subdomain checks
AGENTRQ_PROXY_DOMAIN=
# Force the cookie Secure flag when the proxy terminates TLS (default: follows SSL_ENABLED)
AGENTRQ_COOKIE_SECURE=
# ── 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
# Encrypts integrated OAuth access tokens (such as Slack tokens) using AES-256-GCM (must be 32 bytes).
AGENTRQ_AUTH_WORKSPACE_TOKEN_KEY=change-me-exactly-32-bytes-long!
# 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
# ── GitHub OAuth2 (optional — adds “Sign in with GitHub”) ─
AGENTRQ_ACCOUNTS_OAUTH2_CLI_GITHUB_CLIENT_ID=
AGENTRQ_ACCOUNTS_OAUTH2_CLI_GITHUB_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]>
# ── Slack (optional — for Slack integration) ─────────────
AGENTRQ_SLACK_ENABLED=false
AGENTRQ_SLACK_CLIENT_ID=your-slack-client-id
AGENTRQ_SLACK_CLIENT_SECRET=your-slack-client-secret
AGENTRQ_SLACK_SIGNING_SECRET=your-slack-signing-secret
AGENTRQ_SLACK_APP_ID=your-slack-app-id
# ── Web Push (optional — PWA notifications) ──────────────
# Generate with: npx web-push generate-vapid-keys
AGENTRQ_WEBPUSH_VAPID_PUBLIC_KEY=
AGENTRQ_WEBPUSH_VAPID_PRIVATE_KEY=
AGENTRQ_WEBPUSH_SUBSCRIBER=mailto:[email protected]
# ── Storage ──────────────────────────────────────────────
# Writable directory for attachments and local skill files
AGENTRQ_STORAGE_DIR=./_storage
# Attachments older than this are deleted daily at midnight UTC
AGENTRQ_APP_ATTACHMENT_RETENTION=7d
# Where skill files and attachments live: local or s3
AGENTRQ_SKILLS_STORAGE=local
AGENTRQ_ARTIFACTS_STORAGE=local
# ── S3-compatible storage (only when one of the above is s3) ─
AGENTRQ_S3_ENDPOINT=https://s3.us-east-1.amazonaws.com
AGENTRQ_S3_ACCESS_KEY=
AGENTRQ_S3_SECRET_ACCESS_KEY=
AGENTRQ_S3_REGION=us-east-1
AGENTRQ_S3_BUCKET=
# Base of public links, e.g. a CDN (default: <endpoint>/<bucket>)
AGENTRQ_S3_PUBLIC_URL=
# ── DDoS Protection (optional) ───────────────────────────
AGENTRQ_DDOS_ENABLED=true
AGENTRQ_DDOS_MAX_REQ_PER_SEC=20
AGENTRQ_DDOS_BLOCK_DURATION=5m
# ── Rate Limiting (optional) ─────────────────────────────
AGENTRQ_RATELIMIT_ENABLED=true
AGENTRQ_RATELIMIT_MAX_PER_IP=60
AGENTRQ_RATELIMIT_MAX_PER_USER=100
AGENTRQ_RATELIMIT_WINDOW=60s
# ── Multiple instances (optional) ────────────────────────
# ID generator node, 0-1023 — must be unique per running instance
MONOFLAKE_NODE=1
# Instance identity for daemon pairing (default: node-<MONOFLAKE_NODE>)
AGENTRQ_INSTANCE_ID=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.
BASE_PATH serves AgentRQ under a sub-path such as /agentrq, and the proxy strips that prefix before it forwards the request. PROXY_DOMAIN is the proxy's public host. COOKIE_SECURE=true marks cookies Secure when the proxy terminates TLS and AgentRQ serves plain HTTP.github.com/settings/developers with the callback https://your-domain.com/api/v1/auth/github/callback../_storage, which is /_storage in the container. Point it at a mounted volume so files survive when the container is recreated.local (the default) keeps skill files and attachments under <storage dir>/skills and <storage dir>/artifacts. s3 keeps them in the AGENTRQ_S3_* bucket. Each file gets a public link either way: <base url>/storage/... when local, the bucket when s3.skills/ and artifacts/. S3_PUBLIC_URL sets the base of public links, such as a CDN; it defaults to <endpoint>/<bucket>.7d, 30d) or Go durations (168h). Default 7d. Skill files are never deleted.npx web-push generate-vapid-keys. SUBSCRIBER is the mailto: or https: contact that push services see.MONOFLAKE_NODE (0–1023) must be unique per instance, or IDs collide. It also names the instance for daemon pairing, as node-<N>, unless AGENTRQ_INSTANCE_ID overrides it..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:
$ mkdir _storage; \
chmod 0777 _storage; \
docker run -d \
--name agentrq \
--restart unless-stopped \
-p 80:80 \
--env-file .env \
-v ./_storage:/_storage \
agentrq/agentrq:latest
✓ AgentRQ running at http://localhost./_storage 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 ./_storage:/_storage \
-v ./certs:/_certs \
agentrq/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 AGENTRQ_POSTGRES_ENABLED=true, fill in the other
AGENTRQ_POSTGRES_* values, and set AGENTRQ_SQLITE_ENABLED=false.
The schema is auto-migrated on startup in both modes.
AGENTRQ_STORAGE_DIR (./_storage/, next to the SQLite database), in artifacts/ and skills/. Include this directory in your backups, and
mount a persistent volume at this path in the cloud. To keep files off the server, set AGENTRQ_ARTIFACTS_STORAGE=s3 and/or AGENTRQ_SKILLS_STORAGE=s3 and configure an
S3-compatible bucket.
<AGENTRQ_BASE_URL>/storage/.... For S3 it points
at AGENTRQ_S3_PUBLIC_URL (or <endpoint>/<bucket>), and the bucket must
allow public reads under skills/ and artifacts/. See Attachments.
AGENTRQ_AUTH_WORKSPACE_TOKEN_KEY stable. This key encrypts integration OAuth tokens (such as Slack bot tokens) using AES-256-GCM. Workspace MCP authentication itself is stateless via JWTs.