diff --git a/CLAUDE.md b/CLAUDE.md
index 4986367e..99a62276 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -93,7 +93,7 @@ When running `make dev` in agentex/, the following services start:
 - **Port 5003**: FastAPI backend server
 - **Port 5432**: PostgreSQL (application database)
 - **Port 5433**: PostgreSQL (Temporal database)
-- **Port 6379**: Redis (streams and caching)
+- **Port 6379**: Redis (streams and caching) — required for streaming/messaging; the Docker stack starts it automatically, and a local Redis will conflict on this port (see [Redis Port Conflicts](#redis-port-conflicts))
 - **Port 27017**: MongoDB (document storage)
 - **Port 7233**: Temporal server
 - **Port 8080**: Temporal Web UI
diff --git a/README.md b/README.md
index bc22fe3d..d104ff35 100644
--- a/README.md
+++ b/README.md
@@ -53,6 +53,8 @@ https://github.com/user-attachments/assets/9badad0d-f939-4243-ba39-68cafdae0078
 
 - **Install Python 3.12+ (Required)**: https://www.python.org/downloads/
 
+> **Redis is required.** Agentex uses Redis for streaming and messaging. You do **not** need to install it yourself — the Docker stack (`./dev.sh` / `make dev`) starts it for you. If you already run Redis locally it will conflict on port `6379`, so stop it first (see [Troubleshooting](#redis-port-conflict)).
+
 #### macOS/Linux
 
 ```bash
diff --git a/agentex/docs/docs/concepts/streaming.md b/agentex/docs/docs/concepts/streaming.md
index 80e0dba1..f088f896 100644
--- a/agentex/docs/docs/concepts/streaming.md
+++ b/agentex/docs/docs/concepts/streaming.md
@@ -8,6 +8,9 @@ Streaming enables real-time delivery of messages as they're being generated, pro
 
 Agentex decouples streaming from LLM provider streaming. You're not limited to streaming LLM responses - you can stream any content: progress updates, status messages, multi-step workflows, or custom notifications.
 
+!!! note "Streaming requires Redis"
+    Streaming and messaging are delivered through Redis streams, so a reachable Redis is **required** for any agent that streams or sends messages. Locally, the Docker stack starts Redis for you. In deployment, the `REDIS_URL` environment variable must point at your Redis instance — see [Deploying Your Agent](../deployment/overview.md#prerequisites).
+
 
 
 ## Streaming by Agent Type
diff --git a/agentex/docs/docs/configuration.md b/agentex/docs/docs/configuration.md
index 449ca79b..d9094bb5 100644
--- a/agentex/docs/docs/configuration.md
+++ b/agentex/docs/docs/configuration.md
@@ -125,6 +125,9 @@ agent:
       secret_key: "connection-string"
 ```
 
+!!! note "`REDIS_URL` is a required credential for streaming/messaging"
+    The examples above are your *own* secrets, but `REDIS_URL` is required by the platform for any agent that streams or sends messages — it is not optional. Map it here so it is synced to your deployment. See [Deploying Your Agent](deployment/overview.md#prerequisites).
+
 ### Key Points:
 
 - **`name`**: Must be unique across your organization (used for task routing)
diff --git a/agentex/docs/docs/deployment/cicd.md b/agentex/docs/docs/deployment/cicd.md
index 993a2e32..0c7b186c 100644
--- a/agentex/docs/docs/deployment/cicd.md
+++ b/agentex/docs/docs/deployment/cicd.md
@@ -187,6 +187,9 @@ This will build and push your agent image to `your-registry-here/your-repository
 
 Agents require credentials (API keys, database URLs, etc.) that live in your secrets manager (AWS Secrets Manager, Azure Key Vault, etc.), not in code. The `agentex secrets sync` command bridges your secrets manager to Kubernetes by injecting credentials directly into the target namespace.
 
+!!! note "`REDIS_URL` is a required baseline secret"
+    `agentex secrets sync` is not only for your own custom credentials. Any agent that streams or sends messages also needs `REDIS_URL` synced as a secret (shown as `REDIS_URL_SECRET` below) — it is **required**, not optional. Without it, the agent starts up fine but fails the first time it streams. See [Deploying Your Agent](overview.md#prerequisites).
+
 **Authentication requirements**: Your CI/CD runner (e.g., GitHub Actions runner) needs access to both your secrets manager (to read secrets) and your Kubernetes cluster (to create Secret objects).
 
 **How it works**: The workflow fetches secrets from your secrets manager and constructs a YAML file containing the credentials and image pull secrets. This YAML is then passed to the sync command, which creates Kubernetes Secret objects in your namespace.
@@ -199,7 +202,7 @@ credentials:
     api-key-jdoe: abc12345
     api-key-jsmith: def6789
   REDIS_URL_SECRET:
-    redis-url-secret: redis://localhost/
+    redis-url-secret: <your-redis-connection-string>  # e.g. rediss://<host>:6380 (TLS) or redis://<host>:6379
 imagePullSecrets:
   pull-secret-1:
     registry: registry-url
diff --git a/agentex/docs/docs/deployment/overview.md b/agentex/docs/docs/deployment/overview.md
index 359efa85..db5c239d 100644
--- a/agentex/docs/docs/deployment/overview.md
+++ b/agentex/docs/docs/deployment/overview.md
@@ -10,6 +10,7 @@ Before deploying, you need:
 - **Cluster access** - Contact your cluster administrators for access
 - **Namespace** - Get a namespace provisioned for your agent
 - **Permissions** - RBAC access to create deployments and secrets
+- **Redis** - A reachable Redis instance. Agents require it for streaming and messaging, so its connection string must be provided as the `REDIS_URL` secret (synced in step 2 below). Unlike local development — where the Docker stack provides Redis automatically — a deployed agent has no Redis unless you configure one.
 
 Verify your setup:
 ```bash