Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt

Use this file to discover all available pages before exploring further.

By the end of this guide, the Sluice agent will be reading events from your Redis broker and forwarding them to the dashboard — without modifying a single line of your application code.

​
Prerequisites

  • Docker (or any container runtime)
  • A Redis instance used as your Celery broker
  • A Sluice account (free, no credit card required)

​
1. Create a connection

Sign in to the Sluice dashboard and go to Connections. Click Add Connection, pick “Docker Agent”, and name your connection (e.g., “Production Celery”). You’ll receive:
  • An API key — starts with sk_
  • A Connection ID — a UUID that identifies this connection
Copy both values.

​
2. Run the agent

docker run -d \
  --name sluice-agent \
  -e SLUICE_API_KEY=sk_live_... \
  -e SLUICE_API_URL=https://sluice.sh/api \
  -e SLUICE_CONNECTION_ID=550e8400-e29b-41d4-a716-446655440000 \
  -e SLUICE_REDIS_URL=redis://your-redis:6379/0 \
  ghcr.io/sluice-sh/agent:v0.1.0
That’s it. One command.

​
3. Verify the connection

Check the agent logs to confirm it connected: 
docker logs sluice-agent
You should see: 
sluice-agent | Connecting to Redis at redis://your-redis:6379/0
sluice-agent | Detected framework: celery
sluice-agent | Subscribed to celery events stream
sluice-agent | Forwarding events to Sluice API

​
4. See your data

Open the Sluice dashboard. Jobs from your Celery workers will appear in real time.

​
How the agent works

The Go agent connects directly to your Redis broker and:
  1. Subscribes to Celery events — listens on celeryev.* PUB/SUB channels for task and worker events.
  2. Polls queue depths — reads queue lengths via LLEN on queue keys.
  3. Reads queue topology — scans _kombu.binding.* keys to discover which queues exist.
  4. Normalizes and forwards — converts Celery events to Sluice’s unified model and batches them to the Sluice API.
  5. Reconnects automatically — if Redis goes down, the agent retries with exponential backoff and resumes when it comes back.
Celery events must be enabled. The agent reads events from Redis PUB/SUB, but Celery disables events by default. Add these settings to your Celery config:
worker_send_task_events = True
task_send_sent_event = True
task_track_started = True
The Python SDK enables these automatically — the agent cannot, since it doesn’t modify your application.
The Docker agent requires a Redis broker. RabbitMQ is not supported by the agent in V0. The agent reads Celery events from Redis PUB/SUB channels and polls queue depths via Redis commands — none of which apply to AMQP brokers. If your Celery deployment uses RabbitMQ, use the Python SDK instead.

​
Kubernetes deployment

For production Kubernetes clusters, deploy the agent as a single-replica Deployment: 
apiVersion: apps/v1
kind: Deployment
metadata:
  name: sluice-agent
spec:
  replicas: 1
  selector:
    matchLabels:
      app: sluice-agent
  template:
    metadata:
      labels:
        app: sluice-agent
    spec:
      containers:
        - name: sluice-agent
          # Pin to a specific version — avoid :latest in production
          image: ghcr.io/sluice-sh/agent:v0.1.0
          env:
            - name: SLUICE_API_KEY
              valueFrom:
                secretKeyRef:
                  name: sluice-secrets
                  key: api-key
            - name: SLUICE_API_URL
              value: https://sluice.sh/api
            - name: SLUICE_CONNECTION_ID
              valueFrom:
                secretKeyRef:
                  name: sluice-secrets
                  key: connection-id
            - name: SLUICE_REDIS_URL
              value: redis://redis-master:6379/0
Run one agent per Redis instance. If your Celery workers use multiple Redis databases or instances, deploy one agent for each.

​
SDK vs Agent — which to choose

Python SDKDocker Agent
Code changes2 linesNone
Auto-configures Celery eventsYesNo (manual config needed)
Data richnessHighest (in-process access)High (Redis events + key reads)
DeploymentIn your Celery worker processSeparate container
Best forApp developers who own the codePlatform/DevOps teams

​
Next steps