From f3306af0c92917536f28a617ca3b3fbd93ff2c73 Mon Sep 17 00:00:00 2001 From: Saaketh Sodanapalli Date: Thu, 17 Sep 2026 18:48:21 -0700 Subject: [PATCH] Document CANYONOS_REDIS_HOST/PORT contract for backing services (CAN-388) A ported checkpointer/cache/store defaulting to localhost silently crashes under CanyonOS, since each agent/workflow gets its own container. Document the injected CANYONOS_REDIS_HOST/CANYONOS_REDIS_PORT contract in adapter.md and add the matching symptom to troubleshooting.md. Co-Authored-By: Claude Sonnet 5 --- .../porting-to-canyonos/references/adapter.md | 13 +++++++++++++ .../references/troubleshooting.md | 1 + 2 files changed, 14 insertions(+) diff --git a/.claude/skills/porting-to-canyonos/references/adapter.md b/.claude/skills/porting-to-canyonos/references/adapter.md index d8bdd70..a177136 100644 --- a/.claude/skills/porting-to-canyonos/references/adapter.md +++ b/.claude/skills/porting-to-canyonos/references/adapter.md @@ -117,3 +117,16 @@ memory keyed by session -- carries that id *inside* `query`: accept either a bare string or a JSON object in that one field and pass the id through to the source unchanged. Do not add a second workflow parameter for it; the platform never sends one. + +## Backing services default to the wrong host + +A checkpointer, cache, or store the source constructs (e.g. a Redis- or +Postgres-backed client) often defaults to `localhost` when no connection +variable is set. Under CanyonOS's Local provider each agent and the workflow +get their own container, so `localhost` there is that container's own +loopback, not a shared service -- the client raises a connection error at +startup instead of connecting. Local and EC2 both inject `CANYONOS_REDIS_HOST` +and `CANYONOS_REDIS_PORT` into every container pointing at the real Redis +instance; rebuild any such default from those instead of trusting the source's +`localhost` default, while still honoring an explicit override the source +already reads (e.g. `REDIS_URL`). diff --git a/.claude/skills/porting-to-canyonos/references/troubleshooting.md b/.claude/skills/porting-to-canyonos/references/troubleshooting.md index 9e336c7..1b23258 100644 --- a/.claude/skills/porting-to-canyonos/references/troubleshooting.md +++ b/.claude/skills/porting-to-canyonos/references/troubleshooting.md @@ -38,6 +38,7 @@ read [llm-proxy.md](llm-proxy.md) or [ec2.md](ec2.md). | Calls to one agent reach another | Two config entries share an `entrypoint`, so one stub was written over the other | | Runtime-named module disappears | Shared runtime copy overwrote a module at the root of the source copy with the same name | | An application file is missing from the image | The sweep carries every file, but never a hidden path, a symlink, private key material, or a name the build context owns (`Dockerfile`, `requirements.txt`, `workflow_launcher.py`); the build prints one note per exclusion | +| Container crashes with a connection error to `localhost` for Redis, Postgres, etc. | A checkpointer/cache/store client kept the source's `localhost` default; rebuild it from `CANYONOS_REDIS_HOST`/`CANYONOS_REDIS_PORT` (or the equivalent), read [adapter.md](adapter.md#backing-services-default-to-the-wrong-host) | | Peer container raises `ImportError` for a name in another agent's module | That agent's package `__init__.py` re-exports from its entrypoint, which is a stub in this image; V033 | | `attempted relative import with no known parent package` | The entrypoint's own imports are relative, and it is loaded by path with no parent package; V035 | | `ModuleNotFoundError` for a distribution this image's own code never imports | The entrypoint's package `__init__` or a sibling imports it; add it to this entry's `requirements:` |