---
title: "Self-Hosting AgentRQ | AgentRQ Docs"
url: https://agentrq.com/docs/howto-self-hosting
description: "Run AgentRQ on your own infrastructure. Full data sovereignty, Apache-2.0 licensed, SQLite or PostgreSQL. Step-by-step setup guide."
---

[Docs](https://agentrq.com/docs/) / How-To / Self-Hosting

Self-Hosting

# 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.

Agent-friendly Setup: [Open SETUP.md](https://agentrq.com/docs/SETUP.md)

## Why Self-Host?

Data Sovereignty

Your task data, file attachments, and agent conversations never leave your infrastructure. Run on-prem, in your VPC, or on a local developer machine.

Open Source

Apache-2.0 licensed. Audit the code, fork it, customize it, or contribute back. The same codebase that powers `app.agentrq.com`.

Full Control

Configure your own auth, database, storage, and domain. Run it airgapped if needed. No external service dependencies beyond Google OAuth2.

No Per-Seat Pricing

Run it for your entire team at zero incremental cost. You only pay for the infrastructure you choose to run it on.

Repository

[github.com/agentrq/agentrq](https://github.com/agentrq/agentrq)

## Prerequisites

- Docker — the only runtime dependency. Install from [docs.docker.com/get-docker](https://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://localhost` is fine. For production, point a domain at your server — AgentRQ can handle TLS automatically via Let's Encrypt.

1

## Pull the Docker Image

The official image is published on Docker Hub at `agentrq/agentrq:latest`. No build step required — pull and run.

Terminal

```
$ docker pull agentrq/agentrq:latest
```

Source Code

Apache-2.0 licensed. The full source is available at [github.com/agentrq/agentrq](https://github.com/agentrq/agentrq) if you prefer to build from source.

2

## Create Your .env File

Create a `.env` file in your working directory. All configuration is done via environment variables:

.env

```
# ── 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=you@example.com
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=user@example.com
AGENTRQ_SMTP_PASSWORD=yourpassword
AGENTRQ_SMTP_FROM=AgentRQ <no-reply@example.com>

# ── 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:you@example.com

# ── 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=
```

AGENTRQ_AUTH_JWT_SECRET

Signs user session JWTs. Use a long random string (32+ chars). Changing it invalidates all active sessions.

AGENTRQ_SSL_ENABLED

Set to `true` to enable built-in TLS via Let's Encrypt. Requires a public domain and port 80/443 reachable from the internet.

AGENTRQ_SQLITE_DSN

Path to the SQLite database file inside the container. Mount a host volume here to persist data across restarts.

AGENTRQ_AUTH_ROOT_LOGIN_ENABLED

Enables a root login bypass using `ROOT_ACCESS_TOKEN`. Useful for initial setup. Disable in production.

AGENTRQ_AUTH_WORKSPACE_TOKEN_KEY

Encrypts integration OAuth access tokens (e.g. Slack bot tokens) using AES-256-GCM. Must be exactly 32 bytes. Keep this key stable across restarts.

AGENTRQ_DDOS_*

Controls DDoS protection. Enabled by default with 20 req/sec threshold and 5m block duration. Tune for your traffic patterns.

AGENTRQ_RATELIMIT_*

Per-IP and per-user rate limiting. Defaults: 60 req/IP and 100 req/user per 60s window. Adjust for teams with high agent concurrency.

AGENTRQ_BASE_PATH / PROXY_DOMAIN / COOKIE_SECURE

For running behind a reverse proxy. `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.

AGENTRQ_ACCOUNTS_OAUTH2_CLI_GITHUB_*

Optional GitHub sign-in. Leave empty and the button stays hidden. Create an OAuth app at `github.com/settings/developers` with the callback `https://your-domain.com/api/v1/auth/github/callback`.

AGENTRQ_STORAGE_DIR

Writable directory for attachments, and for skill files when they are stored locally. Defaults to `./_storage`, which is `/_storage` in the container. Point it at a mounted volume so files survive when the container is recreated.

AGENTRQ_SKILLS_STORAGE / ARTIFACTS_STORAGE

`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.

AGENTRQ_S3_*

Any S3-compatible store (AWS S3, MinIO, Cloudflare R2), addressed path-style. The bucket must exist and allow public reads under `skills/` and `artifacts/`. `S3_PUBLIC_URL` sets the base of public links, such as a CDN; it defaults to `<endpoint>/<bucket>`.

AGENTRQ_APP_ATTACHMENT_RETENTION

Attachments older than this are deleted daily at midnight UTC. Accepts days (`7d`, `30d`) or Go durations (`168h`). Default `7d`. Skill files are never deleted.

AGENTRQ_WEBPUSH_*

VAPID keys for PWA push notifications. Generate them with `npx web-push generate-vapid-keys`. `SUBSCRIBER` is the `mailto:` or `https:` contact that push services see.

MONOFLAKE_NODE / AGENTRQ_INSTANCE_ID

Needed only when you run more than one instance. `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.

Keep .env out of git

Add `.env` to your `.gitignore`. The file contains secrets — never commit it to version control.

3

## Google OAuth2 Setup

AgentRQ uses Google OAuth2 for user authentication. You need to create OAuth2 credentials in Google Cloud Console.

1. 1.
   Go to [Google Cloud Console → APIs & Services → Credentials](https://console.cloud.google.com/apis/credentials)
2. 2.
   Click + Create Credentials → OAuth 2.0 Client ID
3. 3.
   Application type: Web application
4. 4.
   Add the following Authorized Redirect URI:
   Redirect URI
   ```
   https://your-domain.com/api/v1/auth/google/callback
   ```
5. 5.
   Click Create — copy the Client ID and Client Secret into your `.env` as `AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_ID` and `AGENTRQ_ACCOUNTS_OAUTH2_CLI_GOOGLE_CLIENT_SECRET`

Localhost Development

For local dev, also add `http://localhost/api/v1/auth/google/callback` as an authorized redirect URI. Google allows multiple redirect URIs per OAuth2 credential.

4

## Run with Docker

Run the container, mounting a local directory for persistent storage and passing your `.env` file:

Terminal

```
$ 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
```

-v ./_storage:/_storage

Mounts a local `./_storage` directory into the container. Your SQLite database and file attachments are stored here — it persists across container restarts.

With TLS enabled

Also expose port 443 and mount a certs volume: `-p 443:443 -v ./certs:/_certs`

With built-in TLS

```
$ 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.

5

## 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.

.mcp.json — self-hosted

```
{
  "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

SQLite (Default)

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.

PostgreSQL (Production)

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.

File Attachment Storage

By default, attachments and skill files are stored under `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.

Public File Links

Every attachment and skill file has a public link that needs no sign-in, so agents and previews can fetch it. For local storage the link is served by your instance at `<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](https://agentrq.com/docs/howto-attachments).

Keep `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.

## Related Pages

[Token Security How to rotate and secure your MCP tokens](https://agentrq.com/docs/howto-token-rotation) [Workspaces Managing workspaces and MCP tokens](https://agentrq.com/docs/workspaces) [Agent SETUP.md Agent-friendly setup markdown file for quick local ingestion](https://agentrq.com/docs/SETUP.md) [Quick Start Using the hosted version at app.agentrq.com](https://agentrq.com/docs/getting-started)