Add env:// SecretRef and Dockerfile for cloud deploy (#43)

* feat: add env:// SecretRef and Dockerfile for cloud deploy

SecretRef gains a second shape — { source: env, var: NAME } — that reads
process.env directly with no spawn. The existing { source: exec } shape
is unchanged. This makes cloud platforms (Railway, Fly, Docker, k8s)
work end-to-end, since op:// and keychain:// can't run there.

Also adds a multi-stage node:20-alpine Dockerfile with a /data volume
for state, and a README "Deploy in the cloud" section covering Docker,
Railway, Fly, and which platforms to avoid.

* chore: address simplify findings

- Drop redundant `npm cache clean --force` after `npm ci` (no-op).
- Add `*.log`, `.env.*`, `coverage`, `.vitest-cache` to .dockerignore.
- Add isSecretRef test for bare `var:` (undefined) in YAML.

* chore: address review findings

- Add _detectPrevBackend test for env-source SecretRef returning "unknown".
- Extract ExecSecretRef / EnvSecretRef named types so the public
  signature of _resolveSecretRefWithOverrides reads ExecSecretRef
  instead of Extract<SecretRef, { source: "exec" }>.
- Switch README docker run example to --env-file to keep secrets out
  of shell history and ps output.

* docs(readme): note that openai-codex provider is unsupported in cloud deploy

Author: yerzhansa

.dockerignore

@@ -0,0 +1,36 @@
+# Build artifacts — rebuilt inside the image
+node_modules
+dist
+*.tgz
+
+# VCS / IDE
+.git
+.gitignore
+.idea
+.vscode
+.DS_Store
+
+# Tests, docs, scripts not needed at runtime
+tests
+.tests
+docs
+.agents
+.claude
+.github
+scripts
+
+# Local secrets / configs
+.env
+.env.*
+.env.example
+CLAUDE.local.md
+
+# Local artifacts
+*.log
+coverage
+.vitest-cache
+
+# Repo metadata not needed in image
+README.md
+CONTRIBUTING.md
+LICENSE

Dockerfile

@@ -0,0 +1,35 @@
+# syntax=docker/dockerfile:1.7
+
+# ── builder ────────────────────────────────────────────────────────────────
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY tsconfig.json ./
+COPY src ./src
+RUN npm run build
+
+# ── runtime ────────────────────────────────────────────────────────────────
+FROM node:20-alpine AS runtime
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV CYCLING_COACH_HOME=/data
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY --from=builder /app/dist ./dist
+COPY SOUL.md ./SOUL.md
+COPY skills ./skills
+
+RUN addgroup -S app && adduser -S -G app app \
+    && mkdir -p /data \
+    && chown -R app:app /data /app
+
+USER app
+VOLUME ["/data"]
+
+CMD ["node", "dist/index.js"]

README.md

@@ -163,26 +163,42 @@ Env vars take precedence over YAML.
 
 ## Storing secrets outside config.yaml
 
-If you don't want API keys to live as plaintext in `~/.cycling-coach/config.yaml`, any secret field (`llm.api_key`, `intervals.api_key`, `telegram.bot_token`) can be replaced with a **SecretRef** — a reference to an external command that prints the secret to stdout. Cycling Coach runs the command at startup, reads stdout, and uses the value.
+If you don't want API keys to live as plaintext in `~/.cycling-coach/config.yaml`, any secret field (`llm.api_key`, `intervals.api_key`, `telegram.bot_token`) can be replaced with a **SecretRef**. Two shapes are supported:
+
+- **`source: exec`** — runs an external command (1Password CLI, Vault, `age`, etc.) and reads its stdout. Best for local desktop use with a password manager.
+- **`source: env`** — reads a process env var directly (no spawn). Best for cloud / Docker / Railway / Kubernetes where the platform injects secrets as env vars.
 
 ```yaml
+# exec — local with 1Password
 llm:
   provider: anthropic
   model: claude-sonnet-4-6
   api_key:
     source: exec
     command: op
     args: [read, "op://Personal/Anthropic/credential"]
+
+# env — cloud / Docker
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-6
+  api_key:
+    source: env
+    var: ANTHROPIC_API_KEY
 ```
 
-**Precedence**: env var > SecretRef > plain YAML. Setting `ANTHROPIC_API_KEY` in your shell still wins — useful for debugging a vault issue without touching YAML.
+**Precedence**: env var (the legacy `ANTHROPIC_API_KEY` / `INTERVALS_API_KEY` / `TELEGRAM_BOT_TOKEN` keys) > SecretRef > plain YAML. Setting `ANTHROPIC_API_KEY` in your shell still wins — useful for debugging a vault issue without touching YAML.
 
-**Requirements**:
+**`exec` requirements**:
 - The `command` must print **only the secret** to stdout. JSON blobs, labels, or extra output will be stored verbatim and downstream APIs will reject them.
 - A single trailing `\n` or `\r\n` is trimmed; all other whitespace is preserved.
 - Empty output, non-zero exit, a 30s timeout, or output over 64KB is a fatal startup error with a clear stderr message.
 - `shell: false` — `command` and `args` are passed directly to the OS. `~`, `$HOME`, globs, and shell operators are **not** expanded. Use absolute paths.
 
+**`env` requirements**:
+- `var` must name an env var that is set and non-empty at startup. Unset → `ENOENT`; empty string → `EMPTY`. Both are fatal startup errors.
+- The value is used verbatim — no trimming, no shell interpretation. If your platform's secret manager appends a newline, set the env var without it.
+
 ### Using the setup wizard with a password manager
 
 If you have the [1Password CLI (`op`)](https://developer.1password.com/docs/cli/) or you're on macOS, `cycling-coach setup` can create the backend items for you — no YAML hand-editing, no manual `op item create` / `security add-generic-password` calls.
@@ -268,6 +284,72 @@ telegram:
 
 SecretRef support was added in a recent release. Downgrading cycling-coach while `config.yaml` contains SecretRef blocks will fail at startup — older versions treat non-string secret values as malformed. Keep plain strings or env vars if you need to roll back.
 
+## Deploy in the cloud
+
+Cycling Coach is a single Node process holding a long-polling connection to Telegram, with state on a local volume at `$CYCLING_COACH_HOME` (defaults to `~/.cycling-coach`). It needs:
+
+- An always-on container or VM (no scale-to-zero — long-polling stops when the process stops).
+- A persistent volume mounted at `/data` (or wherever you point `CYCLING_COACH_HOME`).
+- Secrets injected as env vars, referenced from `config.yaml` via `source: env` (see [Storing secrets outside config.yaml](#storing-secrets-outside-configyaml)).
+- One instance only — sessions are sharded by Telegram chat ID on local disk; do not enable autoscaling.
+- A BYOK provider (`anthropic` / `openai` / `google`). `LLM_PROVIDER=openai-codex` is **not supported in containers** — it depends on an interactive OAuth flow that writes to the data dir, which can't run headless. Use Anthropic, OpenAI, or Google in the cloud.
+
+### Docker
+
+A `Dockerfile` is included. Build and run locally:
+
+```bash
+docker build -t cycling-coach .
+
+docker run -d --name cycling-coach \
+  -v cycling-coach-data:/data \
+  --env-file .env \
+  cycling-coach
+```
+
+Use `--env-file` rather than inline `-e KEY=value` flags — inline values land in shell history and are visible to other users via `ps`. Your `.env` should contain `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`), `INTERVALS_API_KEY`, `INTERVALS_ATHLETE_ID`, and `TELEGRAM_BOT_TOKEN`.
+
+The image runs as a non-root user, mounts `/data` for state, and reads `/data/config.yaml` if present. With the `-e` env vars above, no `config.yaml` is required — the legacy env-var fallback (`ANTHROPIC_API_KEY` etc.) covers the three secret fields.
+
+For finer control (custom model, idle timeout, etc.) drop a `config.yaml` into the volume:
+
+```yaml
+# /data/config.yaml
+llm:
+  provider: anthropic
+  model: claude-sonnet-4-6
+  api_key:
+    source: env
+    var: ANTHROPIC_API_KEY
+intervals:
+  api_key:
+    source: env
+    var: INTERVALS_API_KEY
+  athlete_id: "i12345"
+telegram:
+  bot_token:
+    source: env
+    var: TELEGRAM_BOT_TOKEN
+```
+
+### Railway
+
+Railway autodetects the `Dockerfile` and deploys with no extra config files. Steps:
+
+1. Push this repo to GitHub.
+2. In Railway, **New Project → Deploy from GitHub repo**.
+3. Add a **Volume** mounted at `/data`.
+4. Add the env vars in **Variables**: `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GOOGLE_GENERATIVE_AI_API_KEY`), `INTERVALS_API_KEY`, `INTERVALS_ATHLETE_ID`, `TELEGRAM_BOT_TOKEN`.
+5. Deploy. Railway shows logs; `Telegram bot started` confirms it's polling.
+
+Railway does not scale services with attached volumes to zero, so the bot stays connected.
+
+### Other platforms
+
+- **Fly.io** — works with the same Dockerfile. In `fly.toml` set `auto_stop_machines = false` and `min_machines_running = 1`, otherwise Fly will stop the machine on idle inbound HTTP and the bot stops polling. Mount a 1 GB volume at `/data`.
+- **VPS (Hetzner, DigitalOcean, Lightsail, Oracle Free)** — `docker run` as above, or use systemd. Mount a host directory at `/data` for state.
+- **Avoid** scale-to-zero serverless (Lambda, Cloud Run with `min=0`, Cloudflare Workers, Vercel) and platforms with ephemeral filesystems (Heroku) — both break this app.
+
 ## Development
 
 ```bash

src/config.ts

@@ -120,7 +120,7 @@ function readSecretField(value: unknown, path: SecretFieldPath): string | Secret
   if (isSecretRef(value)) return value;
   throw new SecretResolutionError(
     "INVALID_REF",
-    `Config field ${path} is not a valid SecretRef. Expected a string, or { source: "exec", command: string, args?: string[] }.`,
+    `Config field ${path} is not a valid SecretRef. Expected a string, { source: "exec", command: string, args?: string[] }, or { source: "env", var: string }.`,
   );
 }
 
@@ -255,7 +255,8 @@ export async function resolveConfigSecrets(cfg: Config): Promise<Config> {
   for (const [path, ref] of pending) {
     const value = await resolveSecretRef(ref);
     assignFieldByPath(next, path, value);
-    console.log(`Resolved secret: ${path} (exec: ${ref.command})`);
+    const desc = ref.source === "env" ? `env: ${ref.var}` : `exec: ${ref.command}`;
+    console.log(`Resolved secret: ${path} (${desc})`);
   }
 
   return next;

src/secrets/resolve.ts

@@ -1,15 +1,35 @@
 import { spawn } from "node:child_process";
-import { SecretRef, SecretResolutionError } from "./types.js";
+import { ExecSecretRef, SecretRef, SecretResolutionError } from "./types.js";
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_BYTES = 64 * 1024;
 
 export async function resolveSecretRef(ref: SecretRef): Promise<string> {
+  if (ref.source === "env") {
+    return resolveEnvRef(ref.var);
+  }
   return await _resolveSecretRefWithOverrides(ref, {});
 }
 
+function resolveEnvRef(name: string): string {
+  const value = process.env[name];
+  if (value === undefined) {
+    throw new SecretResolutionError(
+      "ENOENT",
+      `Secret env var '${name}' is not set.`,
+    );
+  }
+  if (value === "") {
+    throw new SecretResolutionError(
+      "EMPTY",
+      `Secret env var '${name}' is set but empty.`,
+    );
+  }
+  return value;
+}
+
 export async function _resolveSecretRefWithOverrides(
-  ref: SecretRef,
+  ref: ExecSecretRef,
   overrides: { timeoutMs?: number; maxBytes?: number },
 ): Promise<string> {
   const timeoutMs = overrides.timeoutMs ?? DEFAULT_TIMEOUT_MS;

src/secrets/types.ts

@@ -1,8 +1,6 @@
-export type SecretRef = {
-  source: "exec";
-  command: string;
-  args?: string[];
-};
+export type ExecSecretRef = { source: "exec"; command: string; args?: string[] };
+export type EnvSecretRef = { source: "env"; var: string };
+export type SecretRef = ExecSecretRef | EnvSecretRef;
 
 export type SecretResolutionErrorCode =
   | "ENOENT"
@@ -21,23 +19,36 @@ export class SecretResolutionError extends Error {
   }
 }
 
-const ALLOWED_KEYS = new Set(["source", "command", "args"]);
+const ALLOWED_KEYS_EXEC = new Set(["source", "command", "args"]);
+const ALLOWED_KEYS_ENV = new Set(["source", "var"]);
 
 export function isSecretRef(value: unknown): value is SecretRef {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     return false;
   }
   const obj = value as Record<string, unknown>;
-  for (const key of Object.keys(obj)) {
-    if (!ALLOWED_KEYS.has(key)) return false;
+
+  if (obj.source === "exec") {
+    for (const key of Object.keys(obj)) {
+      if (!ALLOWED_KEYS_EXEC.has(key)) return false;
+    }
+    if (typeof obj.command !== "string" || obj.command.length === 0) return false;
+    if (obj.args !== undefined) {
+      if (!Array.isArray(obj.args)) return false;
+      for (const a of obj.args) {
+        if (typeof a !== "string") return false;
+      }
+    }
+    return true;
   }
-  if (obj.source !== "exec") return false;
-  if (typeof obj.command !== "string" || obj.command.length === 0) return false;
-  if (obj.args !== undefined) {
-    if (!Array.isArray(obj.args)) return false;
-    for (const a of obj.args) {
-      if (typeof a !== "string") return false;
+
+  if (obj.source === "env") {
+    for (const key of Object.keys(obj)) {
+      if (!ALLOWED_KEYS_ENV.has(key)) return false;
     }
+    if (typeof obj.var !== "string" || obj.var.length === 0) return false;
+    return true;
   }
-  return true;
+
+  return false;
 }

src/setup.ts

@@ -116,6 +116,7 @@ const FIELD_KEYCHAIN_ACCOUNT: Record<SecretFieldPath, string> = {
 export function _detectPrevBackend(value: unknown): BackendChoice | "unknown" {
   if (typeof value === "string") return "plain";
   if (isSecretRef(value)) {
+    if (value.source === "env") return "unknown";
     const cmd = value.command;
     if (cmd === "op" || cmd.endsWith("/op")) return "op";
     if (cmd === "/usr/bin/security" || cmd.endsWith("/security")) return "keychain";

tests/config.secret-ref.test.ts

@@ -146,4 +146,53 @@ describe("config — SecretRef integration", () => {
     expect(cfg.intervals.apiKey).toBe("iv-key");
     expect(cfg.telegram.botToken).toBe("tg-key");
   });
+
+  it("env-source SecretRef on all three fields resolves from process.env", async () => {
+    process.env.MY_LLM_KEY = "llm-from-env";
+    process.env.MY_IV_KEY = "iv-from-env";
+    process.env.MY_TG_KEY = "tg-from-env";
+    try {
+      seed({
+        llm: {
+          provider: "anthropic",
+          api_key: { source: "env", var: "MY_LLM_KEY" },
+          model: "claude-sonnet-4-6",
+        },
+        intervals: {
+          api_key: { source: "env", var: "MY_IV_KEY" },
+          athlete_id: "i1",
+        },
+        telegram: {
+          bot_token: { source: "env", var: "MY_TG_KEY" },
+        },
+      });
+      const { loadConfig, resolveConfigSecrets } = await import("../src/config.js");
+      const cfg = await resolveConfigSecrets(loadConfig());
+      expect(cfg.llm.apiKey).toBe("llm-from-env");
+      expect(cfg.intervals.apiKey).toBe("iv-from-env");
+      expect(cfg.telegram.botToken).toBe("tg-from-env");
+    } finally {
+      delete process.env.MY_LLM_KEY;
+      delete process.env.MY_IV_KEY;
+      delete process.env.MY_TG_KEY;
+    }
+  });
+
+  it("env-source SecretRef throws ENOENT when var is unset", async () => {
+    seed({
+      llm: {
+        provider: "anthropic",
+        api_key: { source: "env", var: "DEFINITELY_UNSET_XYZ_123" },
+        model: "claude-sonnet-4-6",
+      },
+    });
+    const { loadConfig, resolveConfigSecrets } = await import("../src/config.js");
+    const { SecretResolutionError } = await import("../src/secrets/types.js");
+    const err = await resolveConfigSecrets(loadConfig()).catch(
+      (e) => e as SecretResolutionError,
+    );
+    expect(err).toBeInstanceOf(SecretResolutionError);
+    expect(err.code).toBe("ENOENT");
+    expect(err.message).toContain("DEFINITELY_UNSET_XYZ_123");
+  });
 });