Skip to main content
Anubis is distributed as a Docker image in the GitHub Container Registry at ghcr.io/techarohq/anubis.

​
Available Tags

TagDescription
latestThe latest tagged release. Recommended for production.
v<version>A specific tagged release. Use for version pinning.
mainThe current build from the main branch. Use only if you need unreleased features.

​
Quick Start

1

Pull the Docker image

docker pull ghcr.io/techarohq/anubis:latest
2

Create a policy file

Create a botPolicy.yaml file to configure bot detection rules:
bots:
  - name: "OpenAI GPTBot"
    rules:
      userAgentContains: "GPTBot"
    action: deny

  - name: "Anthropic ClaudeBot"
    rules:
      userAgentContains: "Claude-Web"
    action: deny
For more details, see the Bot Policies documentation.
3

Run the container

docker run -d \
  --name anubis \
  -p 8923:8923 \
  -p 9090:9090 \
  -e TARGET=http://localhost:3000 \
  -e DIFFICULTY=4 \
  -e POLICY_FNAME=/config/botPolicy.yaml \
  -v $(pwd)/botPolicy.yaml:/config/botPolicy.yaml:ro \
  ghcr.io/techarohq/anubis:latest
4

Verify the deployment

Check that Anubis is running by accessing the health check endpoint:
curl http://localhost:9090/healthz
You should receive an OK response.

​
Docker Compose

For production deployments, use Docker Compose to manage Anubis alongside your application: 
services:
  anubis:
    image: ghcr.io/techarohq/anubis:latest
    environment:
      BIND: ":8923"
      DIFFICULTY: "4"
      METRICS_BIND: ":9090"
      TARGET: "http://app:3000"
      POLICY_FNAME: "/config/botPolicy.yaml"
      ED25519_PRIVATE_KEY_HEX_FILE: "/secrets/anubis.key"
      COOKIE_DOMAIN: "example.com"
      SLOG_LEVEL: "INFO"
    healthcheck:
      test: ["CMD", "anubis", "--healthcheck"]
      interval: 5s
      timeout: 30s
      retries: 5
      start_period: 500ms
    ports:
      - "8923:8923"
      - "9090:9090"
    volumes:
      - "./botPolicy.yaml:/config/botPolicy.yaml:ro"
      - "./anubis.key:/secrets/anubis.key:ro"
    restart: unless-stopped

  app:
    image: your-app:latest
    # Your application configuration

​
Environment Variables

Configure Anubis using environment variables. The most commonly used options:
VariableDefaultDescription
BIND:8923Network address for Anubis to listen on
BIND_NETWORKtcpNetwork family (tcp or unix)
TARGEThttp://localhost:3923URL of the service to protect
DIFFICULTY4Challenge difficulty (number of leading zeroes)
POLICY_FNAMEBuilt-inPath to bot policy YAML file
METRICS_BIND:9090Address for Prometheus metrics and health checks
COOKIE_DOMAINunsetDomain for Anubis cookies (e.g., example.com)
COOKIE_EXPIRATION_TIME168hHow long challenge passes remain valid
SLOG_LEVELINFOLog level (DEBUG, INFO, WARN, ERROR)
ED25519_PRIVATE_KEY_HEX_FILEunsetPath to signing key file (required for persistent storage)
For a complete list, see the Configuration reference.

​
Volume Mounts

The Docker image runs as user ID 1000 and group ID 1000. Ensure mounted volumes are readable by this user.

​
Policy File

Mount your bot policy configuration: 
-v /path/to/botPolicy.yaml:/config/botPolicy.yaml:ro
Set the environment variable: 
-e POLICY_FNAME=/config/botPolicy.yaml

​
Signing Key

For persistent storage backends or multi-instance deployments, mount a signing key: 
-v /path/to/anubis.key:/secrets/anubis.key:ro
Generate a key: 
openssl rand -hex 32 > anubis.key
chmod 600 anubis.key
Set the environment variable: 
-e ED25519_PRIVATE_KEY_HEX_FILE=/secrets/anubis.key

​
Unix Sockets

When using Unix domain sockets, create a shared volume: 
volumes:
  anubis-socket:

services:
  anubis:
    volumes:
      - "anubis-socket:/run/anubis"
    environment:
      BIND: "/run/anubis/anubis.sock"
      BIND_NETWORK: "unix"

​
Health Checks

Anubis provides two health check mechanisms:

​
HTTP Health Endpoint

Access the health check at the metrics port: 
curl http://localhost:9090/healthz
Returns OK when Anubis is serving traffic.

​
Docker Health Check

Use the built-in --healthcheck flag: 
healthcheck:
  test: ["CMD", "anubis", "--healthcheck"]
  interval: 5s
  timeout: 30s
  retries: 5
  start_period: 500ms

​
System Requirements

Anubis has minimal resource requirements:
  • Memory: 128Mi is typically sufficient for most deployments
  • CPU: Minimal CPU usage for typical workloads
Anubis may not be suitable for applications with long-lived WebSocket connections, as these maintain open connections that consume resources.

​
Prometheus Metrics

Anubis exposes Prometheus metrics on the metrics port (default :9090): 
curl http://localhost:9090/metrics
Add this to your Prometheus configuration: 
scrape_configs:
  - job_name: 'anubis'
    static_configs:
      - targets: ['anubis:9090']

​
Next Steps

Configuration

Learn about all configuration options

Bot Policies

Configure bot detection rules

Reverse Proxy Setup

Integrate with Nginx, Caddy, or other proxies

Environment Examples

Platform-specific deployment guides

Build docs developers (and LLMs) love

Get started for freeTalk to us