@monster-orange/den 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,46 @@ All notable changes to Den are documented here. Each release lists the
 config and manifest changes a distribution must make to move to it under
 **Migrations**.
 
+## [0.2.3] - 2026-11-04
+
+### Added
+
+- **`secret_env`: secrets resolved by Den into a stack's or a service's env**
+  (R16), so a consumer no longer wraps `<provider> run -- <cli> restart
+  <repo>` by hand, and a plain restart no longer drops a key. In a manifest,
+  `compose.secret_env` (for the docker compose process: the compose file's
+  `${VAR}` or pass-through `environment:` entries) and
+  `services.<svc>.secret_env` (for that service's own up/restart command)
+  map an env var to a fully qualified ref, `<vault>/<item>/<field>`. For
+  Doppler that is `<project>/<config>/<key>`; for 1Password vault / item /
+  field; for `env` the field is the env var to read. Existing refs (the
+  engine's named secrets, test users) are unchanged. Resolved through the
+  configured `secrets.provider` at `up` and `restart` (also the in-place
+  restart of one compose service), all or nothing, before anything stops or
+  starts. A missing key fails that target, exit 1, naming the key, ref and
+  provider. Values go only into the spawned process's env: never into the
+  compose override, logs, activity records, MCP output or messages. A dry
+  run (`-n`) never asks the provider; it lists the key names it would
+  inject. A CLI-tabs start of a service with `secret_env` runs as a daemon,
+  so the values stay out of the tab's shell. `validate` rejects a ref that
+  is not exactly three non-empty parts, and a key that is not an env var
+  name. See "Secrets in a target's env" in `docs/distributions.md`.
+
+### Fixed
+
+- **`<cli> mcp connect` for Claude Code failed whenever the server has env**
+  ("Invalid environment variable format: <name>"): `claude mcp add`'s `-e`
+  takes several values, so the server name after the env pairs was read as
+  one more. The name now comes right after `add`.
+- **The up/restart secrets check said the backend was "not ready" when it
+  was signed in with no default scope.** `secret_env` refs name their own
+  scope, so they still resolve; it now says "signed in, no default scope
+  set" instead of warning.
+
+### Migrations
+
+- None required.
+
 ## [0.2.2] - 2026-11-04
 
 ### Added

package/docs/distributions.md

@@ -213,6 +213,57 @@ ones (`⇄ hybrid`).
   production_envs: [prod] # default: [prod, production]
   ```
 
+## Secrets in a target's env
+
+`secret_env` puts secrets from the configured secrets provider
+(`secrets.provider`: `doppler`, `1password` or `env`) into the env of what
+Den starts, instead of wrapping `<provider> run -- <cli> restart <repo>` by
+hand:
+
+```yaml
+# .acme.yml
+compose:
+  secret_env: # the docker compose process's env, at stack up / restart
+    OPENAI_API_KEY: shop/dev_personal/OPENAI_API_KEY
+services:
+  worker:
+    secret_env: # the env of this service's own up / restart command
+      STRIPE_KEY: Engineering/Stripe Test/secret key
+```
+
+Each value is a fully qualified ref, `<vault>/<item>/<field>`:
+
+| Provider    | `a/b/c` means                                                              |
+| ----------- | -------------------------------------------------------------------------- |
+| `doppler`   | `--project a --config b`, key `c` (`secrets.doppler` is not consulted)     |
+| `1password` | vault `a`, item `b`, field `c`                                             |
+| `env`       | the env var `c` of the process running Den (`secrets.keys` is not applied) |
+
+A `compose.secret_env` key reaches a container only through the compose
+file: `${OPENAI_API_KEY}` in it, or a pass-through `environment:
+[OPENAI_API_KEY]`.
+
+- **When.** `up` and `restart`, including `restart <repo>/<service>` of one
+  compose service (`stack up`, `stack restart`, `stack restart --service`),
+  from the CLI, the web UI and MCP. Every key is resolved before anything
+  stops or starts.
+- **Missing.** A key the provider cannot resolve (unset, empty, no access)
+  fails that target, exit 1, naming the key, the ref and the provider. The
+  rest of the set is not used: nothing starts with a partial set, and a
+  restart leaves the old instance running.
+- **Where values go.** Only into the spawned process's env (the docker
+  compose process, or the service's command). Never into the generated
+  compose override, logs, activity records, MCP output, dry runs or
+  messages. A CLI-tabs (`cli_tabs`) start of a service with `secret_env`
+  runs as a daemon, since a tab would put them in its shell history.
+- **Dry run.** `-n`/`--dry-run` never asks the provider. It lists the key
+  names it would inject: `shop: would inject secret_env compose:
+OPENAI_API_KEY (names only; not resolved in a dry run)`.
+- **Validation.** `<cli> validate` rejects a ref that is not exactly three
+  non-empty parts and a key that is not an env var name
+  (`[A-Za-z_][A-Za-z0-9_]*`). A `stacks:` entry in the org config takes
+  `secret_env` too.
+
 ## den.yml: the product profile
 
 Every runtime name derives from `product.name`. Set only what you want to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monster-orange/den",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Den: a local multi-repo dev orchestrator, HTTPS edge and E2E harness",
   "type": "module",
   "bin": {

package/scripts/setup-secrets.ts

@@ -72,6 +72,17 @@ async function main(): Promise<number> {
     const r = await provider.preflight();
     if (r.ok) return 0;
     if (gate && !cfg.required) {
+      // Signed in but no default scope: secret_env refs name their own
+      // (<project>/<config>/<key>), so only the engine's own secrets lack one.
+      if (await provider.isReady()) {
+        console.error(
+          chalk.gray(
+            `   ${label}: signed in, no default scope set (secret_env refs still resolve;` +
+              ` test logins and the saved sudo password need one: \`make ${product().cli}-setup-secrets\`).`,
+          ),
+        );
+        return 0;
+      }
       console.error(
         chalk.yellow(
           `⚠️  ${label} is not ready — continuing.\n` +

package/src/shared/environment-manager/service-runner.ts

@@ -27,6 +27,15 @@ import {
   shellQuote,
 } from "../terminal/tabs.js";
 import { readCatalog } from "./catalog.js";
+import { getSecretsProvider } from "../secrets/index.js";
+import {
+  assertSecretEnvSpec,
+  resolveSecretEnv,
+  secretEnvKeys,
+  type SecretEnvSpec,
+} from "../secrets/secret-env.js";
+import type { SecretsProvider } from "../secrets/types.js";
+import { composeCommands } from "../stacks/manifest-commands.js";
 import { buildServiceEnv } from "./service-env.js";
 import {
   devOpContainerNames,
@@ -1069,6 +1078,12 @@ export interface RunCommandOptions {
    * the detach window is invisible to fail-fast callers.
    */
   onServiceExit?: (exitCode: number) => void;
+  /**
+   * R16: the service's resolved `secret_env` (see prepareServiceSecretEnv),
+   * set only in the spawned process's env. An up/restart of a service that
+   * declares secret_env is refused unless every key is here.
+   */
+  secretEnv?: Record<string, string>;
 }
 
 export interface RunCommandResult {
@@ -1135,6 +1150,108 @@ function repoStartedFallback(
       };
 }
 
+// ── secret_env (R16) ─────────────────────────────────────────────────────────
+
+/** Commands that start a service process, and so get its secret_env. */
+function startsService(command: string): boolean {
+  return command === "up" || command === "restart";
+}
+
+/** A service's declared `services.<svc>.secret_env` (validated), or undefined. */
+function serviceSecretEnvSpec(
+  resolved: ResolvedService,
+): SecretEnvSpec | undefined {
+  const raw = readManifest(resolved.repoPath)?.services?.[resolved.subsystem]
+    ?.secret_env;
+  return assertSecretEnvSpec(
+    raw,
+    `${resolved.address}: services.${resolved.subsystem}.secret_env`,
+  );
+}
+
+/**
+ * The address whose command a run of `command` on `address` actually spawns
+ * (a service with no up of its own runs its repo's up), or null when none.
+ */
+function spawningAddress(
+  address: string,
+  command: string,
+  workspace?: string,
+): string | null {
+  const p = previewServiceCommand(address, command, workspace);
+  return p.kind === "run" || p.kind === "via-repo" ? p.address : null;
+}
+
+/**
+ * The secret_env key NAMES a run of `command` on `address` would inject,
+ * for a dry run or status: never a value, and the provider is never asked.
+ * `service` is the service's own secret_env (set in its command's env);
+ * `compose` is the repo's compose.secret_env, which Den's synthesized stack
+ * command resolves for the docker compose process.
+ */
+export function previewServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+): { address: string; service: string[]; compose: string[] } | null {
+  if (!startsService(command)) return null;
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return null;
+  const manifest = readManifest(resolved.repoPath);
+  const service = Object.keys(
+    manifest?.services?.[resolved.subsystem]?.secret_env ?? {},
+  ).sort();
+  const declared = manifest?.services?.[resolved.subsystem]?.commands?.local;
+  const synthesized =
+    manifest?.compose && !declared?.[command]
+      ? composeCommands(
+          manifest,
+          resolved.subsystem,
+          resolved.repoName,
+          workspace ?? "default",
+        )[command]
+      : undefined;
+  const compose = synthesized
+    ? Object.keys(manifest?.compose?.secret_env ?? {}).sort()
+    : [];
+  if (!service.length && !compose.length) return null;
+  return { address: resolved.address, service, compose };
+}
+
+export type ServiceSecretEnvResult =
+  | { ok: true; secretEnv: Record<string, string> }
+  | { ok: false; message: string };
+
+/**
+ * Resolve the `secret_env` of the service a run of `command` on `address`
+ * spawns, for runServiceCommand's `secretEnv`. All or nothing; the provider
+ * is only asked when the service declares secret_env, and only for up and
+ * restart. Messages name keys, refs and the provider, never values.
+ */
+export async function prepareServiceSecretEnv(
+  address: string,
+  command: string,
+  workspace?: string,
+  provider: () => SecretsProvider = getSecretsProvider,
+): Promise<ServiceSecretEnvResult> {
+  if (!startsService(command)) return { ok: true, secretEnv: {} };
+  const target = spawningAddress(address, command, workspace);
+  const resolved = target ? resolveService(target, workspace) : null;
+  if (!resolved) return { ok: true, secretEnv: {} };
+  let spec: SecretEnvSpec | undefined;
+  try {
+    spec = serviceSecretEnvSpec(resolved);
+  } catch (e) {
+    return { ok: false, message: (e as Error).message };
+  }
+  if (!secretEnvKeys(spec).length) return { ok: true, secretEnv: {} };
+  const r = await resolveSecretEnv(spec, provider(), resolved.address);
+  return r.ok
+    ? { ok: true, secretEnv: r.env }
+    : { ok: false, message: r.message };
+}
+
 /** What a run of `command` on `address` would do, without running it. */
 export type ServiceCommandPreview =
   | { kind: "run"; address: string }
@@ -1516,6 +1633,41 @@ export function runServiceCommand(
     onLine,
   );
 
+  // R16: a service that declares secret_env never starts without every key
+  // (a caller that did not resolve them is refused, not run without them).
+  let secretEnv: Record<string, string> = {};
+  if (startsService(command)) {
+    let declared: string[];
+    try {
+      declared = secretEnvKeys(serviceSecretEnvSpec(resolved));
+    } catch (e) {
+      onLine(`Error: ${(e as Error).message}`);
+      closeAsync(1);
+      return dummy();
+    }
+    const missing = declared.filter((k) => !options.secretEnv?.[k]);
+    if (missing.length) {
+      onLine(
+        `Error: ${resolved.address} declares secret_env ${missing.join(", ")}, which were not resolved; not starting it`,
+      );
+      closeAsync(1);
+      return dummy();
+    }
+    secretEnv = Object.fromEntries(
+      declared.map((k) => [k, options.secretEnv?.[k] as string]),
+    );
+  }
+  const hasSecrets = Object.keys(secretEnv).length > 0;
+  // Secrets go only in the spawned process's env. A tab would need them in
+  // its command line (and so its shell history), so such a start runs as a
+  // daemon instead.
+  const runEnv: NodeJS.ProcessEnv = { ...env, ...secretEnv };
+  if (hasSecrets && runtime === "tab" && startsService(command))
+    onLine(
+      `${resolved.address} has secret_env: running as a daemon, not in a tab, to keep the values out of the tab's shell`,
+    );
+  const useTab = runtime === "tab" && !hasSecrets;
+
   // Manifest downs that are just `opctl container down <name>` must not be
   // spawned raw: opctl re-elevates with `sudo -E` and fails on sudoers without
   // SETENV even when there is nothing to stop — which is why files-api/api
@@ -1571,7 +1723,7 @@ export function runServiceCommand(
     // HITL command — inherit the full TTY; onLine is not called.
     const proc = spawnInteractive(
       cmdString,
-      { ...process.env, ...env },
+      { ...process.env, ...runEnv },
       onClose,
       repoPath,
     );
@@ -1621,11 +1773,11 @@ export function runServiceCommand(
     }
   };
 
-  if (runtime === "tab" && command === "up") {
+  if (useTab && command === "up") {
     return openCommandInTab(cmdString);
   }
 
-  if (runtime === "tab" && command === "restart") {
+  if (useTab && command === "restart") {
     closeExistingTab();
     if (requestedCmdDef) return openCommandInTab(cmdString);
 
@@ -1743,7 +1895,7 @@ export function runServiceCommand(
   const proc = spawnStreaming(
     cmdString,
     [],
-    { ...process.env, ...env },
+    { ...process.env, ...runEnv },
     onLine,
     wrappedOnClose,
     repoPath,

package/src/shared/manifest/schema.ts

@@ -9,6 +9,7 @@
 
 import { z } from "zod";
 import { journeysAppSchema } from "../../pillars/journeys/app-config.js";
+import { SECRET_ENV_KEY_RE, secretEnvRefError } from "../secrets/secret-env.js";
 
 export const CURRENT_SCHEMA_VERSION = 1;
 export const KNOWN_VERSIONS = [1] as const;
@@ -69,6 +70,16 @@ const logSource = z.union([
   }),
 ]);
 
+// secret_env (R16): ENV_NAME → "<vault>/<item>/<field>", resolved through the
+// secrets provider at up/restart and passed only in the process env.
+const secretEnvConfig = z.record(
+  z.string().regex(SECRET_ENV_KEY_RE, "must be a valid env var name"),
+  z.string().superRefine((ref, ctx) => {
+    const err = secretEnvRefError(ref);
+    if (err) ctx.addIssue({ code: z.ZodIssueCode.custom, message: err });
+  }),
+);
+
 // ── Service management config ─────────────────────────────────────────────────
 //
 // Keys for commands/logs/health are environment names (local, dev, …).
@@ -105,6 +116,7 @@ const serviceTarget = z
 const serviceManagementConfig = z.object({
   runs: z.record(z.string(), z.enum(["local", "remote"])).optional(),
   target: serviceTarget.optional(),
+  secret_env: secretEnvConfig.optional(),
   depends_on: z.array(dependsOnEntry).optional(),
   commands: z.record(z.string(), z.record(z.string(), commandDef)).optional(),
   logs: z.record(z.string(), logSource).optional(),
@@ -280,6 +292,9 @@ const composeConfig = z.object({
       z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])),
     )
     .optional(),
+  // Env vars resolved from the secrets provider into the docker compose
+  // process's env at up/restart. Never written to the override.
+  secret_env: secretEnvConfig.optional(),
 });
 
 // ── v1 manifest schema ────────────────────────────────────────────────────────

package/src/shared/secrets/doppler.ts

@@ -4,7 +4,8 @@
  *
  * Project/config come from `secrets.doppler.{project,config}` in
  * config/den.yml, else from the directory's `doppler setup` scope,
- * else from DOPPLER_PROJECT / DOPPLER_CONFIG / DOPPLER_TOKEN.
+ * else from DOPPLER_PROJECT / DOPPLER_CONFIG / DOPPLER_TOKEN. A scoped ref
+ * (a `secret_env` value, `<project>/<config>/<key>`) names its own.
  */
 import { execFile, spawn } from "child_process";
 import { promisify } from "util";
@@ -29,8 +30,12 @@ export class DopplerProvider implements SecretsProvider {
     this.timeout = opts.timeoutMs ?? 30_000;
   }
 
-  /** `--project/--config` flags when configured explicitly. */
-  scopeArgs(): string[] {
+  /**
+   * `--project/--config` flags: a scoped ref's own vault/item, else the
+   * configured ones (when set explicitly).
+   */
+  scopeArgs(ref?: SecretRef): string[] {
+    if (ref?.scoped) return ["--project", ref.vault, "--config", ref.item];
     const a: string[] = [];
     if (this.opts.project) a.push("--project", this.opts.project);
     if (this.opts.config) a.push("--config", this.opts.config);
@@ -56,7 +61,7 @@ export class DopplerProvider implements SecretsProvider {
     const key = this.keyFor(ref);
     const { stdout } = await execFileAsync(
       "doppler",
-      ["secrets", "get", key, "--plain", ...this.scopeArgs()],
+      ["secrets", "get", key, "--plain", ...this.scopeArgs(ref)],
       { timeout: this.timeout },
     );
     return String(stdout).trim();
@@ -77,7 +82,7 @@ export class DopplerProvider implements SecretsProvider {
     await new Promise<void>((resolve, reject) => {
       const child = spawn(
         "doppler",
-        ["secrets", "set", key, "--silent", ...this.scopeArgs()],
+        ["secrets", "set", key, "--silent", ...this.scopeArgs(ref)],
         { stdio: ["pipe", "ignore", "pipe"] },
       );
       let stderr = "";

package/src/shared/secrets/index.ts

@@ -26,6 +26,7 @@ export { flatKeyFor, toEnvName, refPath } from "./keys.js";
 export { DopplerProvider } from "./doppler.js";
 export { EnvProvider } from "./env.js";
 export { OnePasswordProvider } from "./onepassword.js";
+export * from "./secret-env.js";
 
 export interface SecretsConfig {
   provider?: SecretsProviderName;

package/src/shared/secrets/keys.ts

@@ -16,6 +16,7 @@ export function refPath(ref: SecretRef): string {
 
 /**
  * Resolve the flat key a key/value backend should use for `ref`:
+ *   0. a scoped ref's field, as is (it is fully qualified: no overrides);
  *   1. `ref.key` when the caller pinned one;
  *   2. the `secrets.keys` override map (`"vault/item/field": KEY`);
  *   3. the field itself when it already looks like an env var (API keys);
@@ -25,6 +26,7 @@ export function flatKeyFor(
   ref: SecretRef,
   overrides: Record<string, string> = {},
 ): string {
+  if (ref.scoped) return ref.field;
   if (ref.key) return ref.key;
   const mapped = overrides[refPath(ref)];
   if (mapped) return mapped;

package/src/shared/secrets/secret-env.ts

@@ -0,0 +1,149 @@
+/**
+ * `secret_env` (R16): environment variables whose values Den resolves from
+ * the configured secrets provider when it starts or restarts a target.
+ *
+ *   compose:
+ *     secret_env:
+ *       OPENAI_API_KEY: proj/dev_personal/OPENAI_API_KEY
+ *   services:
+ *     api:
+ *       secret_env:
+ *         SOME_KEY: vault/item/field
+ *
+ * Each value is a fully qualified `a/b/c` path, parsed into a SCOPED
+ * {@link SecretRef} (see its `scoped` field for what each provider does with
+ * it). Values only ever travel in the spawned process's env: never into the
+ * compose override, logs, activity records, MCP output, dry runs or errors.
+ * Everything here that produces text names keys and refs, never values.
+ *
+ * This module only imports types, so the manifest schema can use the parser.
+ */
+import type { SecretRef, SecretsProvider } from "./types.js";
+
+/** A `secret_env` block: env var name → `a/b/c` ref. */
+export type SecretEnvSpec = Record<string, string>;
+
+/** Env var names Den will set (POSIX-portable). */
+export const SECRET_ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Why `raw` is not a valid secret_env ref, or null when it is. */
+export function secretEnvRefError(raw: unknown): string | null {
+  if (typeof raw !== "string")
+    return 'must be a string "<vault>/<item>/<field>"';
+  const parts = raw.split("/");
+  if (
+    parts.length !== 3 ||
+    parts.some((p) => p.trim() === "" || p !== p.trim())
+  )
+    return `"${raw}" must be exactly three non-empty parts, "<vault>/<item>/<field>" (Doppler: <project>/<config>/<key>)`;
+  return null;
+}
+
+/** Parse an `a/b/c` ref into a scoped SecretRef. Throws when malformed. */
+export function parseSecretEnvRef(raw: string): SecretRef {
+  const err = secretEnvRefError(raw);
+  if (err) throw new Error(`secret_env ref ${err}`);
+  const [vault, item, field] = raw.split("/");
+  return { vault, item, field, scoped: true };
+}
+
+/**
+ * Problems with a whole `secret_env` block, as `KEY: message` strings ([]
+ * when it is valid). `where` prefixes each message.
+ */
+export function secretEnvSpecErrors(spec: unknown, where: string): string[] {
+  if (spec === undefined) return [];
+  if (spec === null || typeof spec !== "object" || Array.isArray(spec))
+    return [`${where} must be a map of ENV_NAME: "<vault>/<item>/<field>"`];
+  const out: string[] = [];
+  for (const [k, v] of Object.entries(spec)) {
+    if (!SECRET_ENV_KEY_RE.test(k))
+      out.push(`${where}.${k}: "${k}" is not a valid env var name`);
+    const err = secretEnvRefError(v);
+    if (err) out.push(`${where}.${k}: ref ${err}`);
+  }
+  return out;
+}
+
+/** The validated block, or throws listing every problem. */
+export function assertSecretEnvSpec(
+  spec: unknown,
+  where: string,
+): SecretEnvSpec | undefined {
+  if (spec === undefined) return undefined;
+  const errors = secretEnvSpecErrors(spec, where);
+  if (errors.length) throw new Error(errors.join("\n"));
+  return { ...(spec as SecretEnvSpec) };
+}
+
+/** One key that could not be resolved. Never carries a value. */
+export interface SecretEnvMissing {
+  key: string;
+  ref: string;
+}
+
+export type SecretEnvResolution =
+  | { ok: true; env: Record<string, string> }
+  | { ok: false; missing: SecretEnvMissing[]; message: string };
+
+/**
+ * The failure text for unresolved keys: key, ref and provider, never a value
+ * and never the provider's own error output (which could echo one).
+ */
+export function describeSecretEnvMissing(
+  target: string,
+  missing: SecretEnvMissing[],
+  provider: string,
+): string {
+  const lines = missing.map(
+    (m) => `  ${m.key} (ref ${m.ref}, provider ${provider}): not resolved`,
+  );
+  return (
+    `${target}: ${missing.length} secret_env key(s) could not be resolved; not starting it:\n` +
+    lines.join("\n")
+  );
+}
+
+/**
+ * Resolve every key of `spec` through `provider`. All or nothing: when any
+ * key is missing (unset, empty, unreadable) the result is a failure naming
+ * each missing key, and no partial env is returned.
+ */
+export async function resolveSecretEnv(
+  spec: SecretEnvSpec | undefined,
+  provider: SecretsProvider,
+  target: string,
+): Promise<SecretEnvResolution> {
+  const entries = Object.entries(spec ?? {});
+  if (!entries.length) return { ok: true, env: {} };
+  const results = await Promise.all(
+    entries.map(async ([key, raw]) => {
+      if (secretEnvRefError(raw)) return { key, raw, value: null };
+      let value: string | null = null;
+      try {
+        value = await provider.tryGet(parseSecretEnvRef(raw));
+      } catch {
+        value = null;
+      }
+      return { key, raw, value };
+    }),
+  );
+  const missing = results
+    .filter((r) => !r.value)
+    .map((r) => ({ key: r.key, ref: String(r.raw) }));
+  if (missing.length)
+    return {
+      ok: false,
+      missing,
+      message: describeSecretEnvMissing(target, missing, provider.name),
+    };
+  return {
+    ok: true,
+    env: Object.fromEntries(results.map((r) => [r.key, r.value as string])),
+  };
+}
+
+/** The keys of a block, sorted: what a dry run or status may show. */
+export function secretEnvKeys(spec: SecretEnvSpec | undefined): string[] {
+  return Object.keys(spec ?? {}).sort();
+}

package/src/shared/secrets/types.ts

@@ -22,6 +22,16 @@ export interface SecretRef {
    * `flatKeyFor`.
    */
   key?: string;
+  /**
+   * Set on a fully qualified ref (a `secret_env` value, `a/b/c`): every part
+   * names a real location and no provider config fills it in.
+   *  - Doppler: vault = `--project`, item = `--config`, field = the key
+   *    (`secrets.doppler` and `secrets.keys` are not consulted).
+   *  - 1Password: vault / item / field as for any ref.
+   *  - env: field is the env var name (`secrets.keys` is not consulted).
+   * Unscoped refs (the default) keep the provider's configured scope.
+   */
+  scoped?: true;
 }
 
 export type SecretsProviderName = "doppler" | "1password" | "env";

package/src/shared/stacks/config.ts

@@ -17,6 +17,7 @@ import {
 } from "../environment-manager/workspaces.js";
 import { readManifest } from "../manifest/read-manifest.js";
 import type { ManifestComposeConfig } from "../types/index.js";
+import { assertSecretEnvSpec } from "../secrets/secret-env.js";
 import { assertStackName, parseTarget } from "./render.js";
 import type { StackConfig } from "./types.js";
 
@@ -41,6 +42,10 @@ function toStack(
   const routes = raw.routes ?? {};
   Object.values(routes).forEach(parseTarget);
   const files = list(raw.files, `${where}.files`);
+  const secretEnv =
+    "secret_env" in raw
+      ? assertSecretEnvSpec(raw.secret_env, `${where}.secret_env`)
+      : undefined;
   return {
     name,
     repo,
@@ -69,6 +74,7 @@ function toStack(
           ),
         }
       : {}),
+    ...(secretEnv && Object.keys(secretEnv).length ? { secretEnv } : {}),
   };
 }
 

package/src/shared/stacks/runtime.ts

@@ -16,6 +16,12 @@ import {
   renderStackRoutes,
   routedNetworks,
 } from "./render.js";
+import {
+  resolveSecretEnv,
+  secretEnvKeys,
+  type SecretEnvResolution,
+} from "../secrets/secret-env.js";
+import type { SecretsProvider } from "../secrets/types.js";
 import type { ResolvedProject, StackConfig } from "./types.js";
 
 function run(
@@ -117,6 +123,35 @@ function composeEnv(ctx: StackContext, s: StackConfig): NodeJS.ProcessEnv {
   };
 }
 
+/**
+ * Resolve a stack's `secret_env` through `provider` (all or nothing). Call
+ * it before anything starts or stops, and hand the env to stackUp /
+ * stackRestartService. Nothing in the result's message carries a value.
+ */
+export function resolveStackSecretEnv(
+  s: StackConfig,
+  provider: SecretsProvider,
+): Promise<SecretEnvResolution> {
+  return resolveSecretEnv(s.secretEnv, provider, `stack ${s.name}`);
+}
+
+/**
+ * The resolved secrets for a compose process that starts containers. Fails
+ * closed: a stack that declares `secret_env` is never started without every
+ * key (that is how a plain restart used to drop one).
+ */
+function secretComposeEnv(
+  s: StackConfig,
+  secretEnv: Record<string, string> | undefined,
+): Record<string, string> {
+  const missing = secretEnvKeys(s.secretEnv).filter((k) => !secretEnv?.[k]);
+  if (missing.length)
+    throw new Error(
+      `stack ${s.name}: secret_env ${missing.join(", ")} not resolved; not starting it`,
+    );
+  return secretEnv ?? {};
+}
+
 function baseArgs(ctx: StackContext, s: StackConfig): string[] {
   return [
     "compose",
@@ -168,8 +203,15 @@ function running(container: string): boolean {
 export function stackUp(
   ctx: StackContext,
   s: StackConfig,
-  opts: { build?: boolean } = {},
+  opts: {
+    build?: boolean;
+    /** The stack's resolved `secret_env` (see resolveStackSecretEnv). */
+    secretEnv?: Record<string, string>;
+  } = {},
 ) {
+  const secrets = secretComposeEnv(s, opts.secretEnv);
+  // `compose config` runs without them: its JSON (which feeds the override)
+  // must not carry a secret.
   const resolved = resolve(ctx, s);
   // Provider side of each link: its referenced services join a private network.
   const needs = providerServices(s);
@@ -200,7 +242,11 @@ export function stackUp(
       ...(opts.build ? ["--build"] : []),
       "--remove-orphans",
     ],
-    { cwd: repoDir(s), env: composeEnv(ctx, s), inherit: true },
+    {
+      cwd: repoDir(s),
+      env: { ...composeEnv(ctx, s), ...secrets },
+      inherit: true,
+    },
   );
   // This stack as a provider: consumers already running keep their link
   // network, but a restarted provider's new containers must rejoin it.
@@ -274,14 +320,16 @@ export function stackRestartService(
   ctx: StackContext,
   s: StackConfig,
   service: string,
+  opts: { secretEnv?: Record<string, string> } = {},
 ): void {
+  const secrets = secretComposeEnv(s, opts.secretEnv);
   const override = path.join(stackDir(ctx, s), "override.yml");
   const args = fs.existsSync(override)
     ? overrideArgs(ctx, s)
     : baseArgs(ctx, s);
   must("docker", [...args, "restart", service], {
     cwd: repoDir(s),
-    env: composeEnv(ctx, s),
+    env: { ...composeEnv(ctx, s), ...secrets },
     inherit: true,
   });
 }

package/src/shared/stacks/types.ts

@@ -10,6 +10,8 @@
  *       uses: [ragstack]                    # start first + private link network
  *       env:                                 # compose ${VAR} substitution
  *         RAG_PROXY_TARGET: "http://{ragstack.ragstack-server}:80"
+ *       secret_env:                          # from the secrets provider, at up/restart
+ *         OPENAI_API_KEY: proj/dev/OPENAI_API_KEY
  *
  * `{stack.service}` expands to that service's container name.
  */
@@ -36,6 +38,12 @@ export interface StackConfig {
    * `${VAR}` substitution) cannot change.
    */
   serviceEnv?: Record<string, Record<string, string>>;
+  /**
+   * `secret_env` (R16): env var → `<vault>/<item>/<field>` ref. Resolved
+   * through the secrets provider by `stack up` / `stack restart` and passed
+   * only in the docker compose process's env, never in the override file.
+   */
+  secretEnv?: Record<string, string>;
 }
 
 /** What `docker compose config --format json` tells us about a service. */

package/src/shared/types/index.ts

@@ -276,6 +276,12 @@ export interface ServiceManagementConfig {
   runs?: Partial<Record<Environment, ServiceRunsValue>>;
   /** Where a remote service runs: the env, an account label, a URL to probe. */
   target?: ServiceTargetConfig;
+  /**
+   * R16: env var → `<vault>/<item>/<field>` ref, resolved through the
+   * secrets provider when this service's up/restart command runs, and set
+   * only in that process's env (see src/shared/secrets/secret-env.ts).
+   */
+  secret_env?: Record<string, string>;
 }
 
 export type ServiceRunsValue = "local" | "remote";
@@ -572,6 +578,15 @@ export interface ManifestComposeConfig {
   profiles?: string[];
   /** service → replacement healthcheck `test` (written to den's override, not the repo). */
   healthchecks?: Record<string, string[]>;
+  /** service → env vars set on that service in the override (wins by key). */
+  service_env?: Record<string, Record<string, string | number | boolean>>;
+  /**
+   * R16: env var → `<vault>/<item>/<field>` ref, resolved through the
+   * secrets provider at stack up/restart and set only in the docker compose
+   * process's env (for the compose file's `${VAR}` / pass-through
+   * `environment:` entries). Never written to the override.
+   */
+  secret_env?: Record<string, string>;
 }
 
 export interface MigrationResult {

package/src/ui/cli/index.ts

@@ -99,6 +99,8 @@ import { waitForReady } from "../../shared/environment-manager/readiness.js";
 import {
   canonicalServiceAddress,
   previewServiceCommand,
+  previewServiceSecretEnv,
+  prepareServiceSecretEnv,
   resolveService,
   type ServiceCommandPreview,
 } from "../../shared/environment-manager/service-runner.js";
@@ -1453,6 +1455,20 @@ class DenCLI {
           console.log(chalk.gray(`  ${p.note}`));
         if (p.kind === "error") console.log(chalk.red(`  ✗ ${p.note}`));
       }
+      // R16: key names only. A dry run never asks the secrets provider.
+      for (const a of new Set(runs)) {
+        const sec = previewServiceSecretEnv(a, command, workspace);
+        if (!sec) continue;
+        const parts = [
+          ...(sec.service.length ? [sec.service.join(", ")] : []),
+          ...(sec.compose.length ? [`compose: ${sec.compose.join(", ")}`] : []),
+        ];
+        console.log(
+          chalk.gray(
+            `  ${sec.address}: would inject secret_env ${parts.join("; ")} (names only; not resolved in a dry run)`,
+          ),
+        );
+      }
       if (previews.some((p) => p.kind === "error")) process.exitCode = 1;
       console.log(chalk.gray(`  (--dry-run: not ${doing} anything)\n`));
       return;
@@ -1590,7 +1606,22 @@ class DenCLI {
         }
       }
 
+      // R16: resolve the service's secret_env before anything spawns. A
+      // missing key fails this target; nothing starts with a partial set.
+      const secrets = await prepareServiceSecretEnv(
+        address,
+        command,
+        workspace,
+      );
+
       const started = await new Promise<boolean>((resolve) => {
+        if (!secrets.ok) {
+          console.log(chalk.red(`  ✗ ${command} ${chalk.bold(address)}`));
+          for (const l of secrets.message.split("\n"))
+            console.log(chalk.gray(`      ${l}`));
+          resolve(false);
+          return;
+        }
         const spinner = ora(`${command} ${chalk.bold(address)}...`).start();
         let detachTimer: ReturnType<typeof setTimeout> | null = null;
         let settled = false;
@@ -1672,6 +1703,7 @@ class DenCLI {
           runtime,
           workspace,
           force: command === "down" ? force : false,
+          secretEnv: secrets.secretEnv,
           onLine: (line) => {
             spinner.text = `${command} ${chalk.bold(address)}: ${chalk.gray(line.slice(0, 80))}`;
             const trimmed = line.trim();

package/src/ui/cli/stack-command.ts

@@ -8,8 +8,11 @@
 import chalk from "chalk";
 import { routeUrl } from "../../shared/edge/render.js";
 import { edgeUp } from "../../shared/edge/runtime.js";
+import { getSecretsProvider } from "../../shared/secrets/index.js";
+import type { SecretsProvider } from "../../shared/secrets/types.js";
 import { projectName, startOrder } from "../../shared/stacks/render.js";
 import {
+  resolveStackSecretEnv,
   stackDown,
   stackHealth,
   stackLogs,
@@ -18,6 +21,7 @@ import {
   stackUp,
 } from "../../shared/stacks/runtime.js";
 import { loadStackContext, stackStatuses } from "../../shared/stacks/status.js";
+import type { StackConfig } from "../../shared/stacks/types.js";
 
 function serviceFlag(args: string[]): { service?: string; rest: string[] } {
   const rest: string[] = [];
@@ -29,6 +33,29 @@ function serviceFlag(args: string[]): { service?: string; rest: string[] } {
   return { service, rest };
 }
 
+/**
+ * Every named stack's `secret_env`, resolved before anything starts or
+ * stops: one missing key fails the whole command with nothing changed.
+ * The provider is only asked when some stack declares secret_env.
+ */
+export async function resolveStacksSecretEnv(
+  targets: StackConfig[],
+  provider: () => SecretsProvider = getSecretsProvider,
+): Promise<Map<string, Record<string, string>>> {
+  const out = new Map<string, Record<string, string>>();
+  const needing = targets.filter((s) => Object.keys(s.secretEnv ?? {}).length);
+  if (!needing.length) return out;
+  const p = provider();
+  const failures: string[] = [];
+  for (const s of needing) {
+    const r = await resolveStackSecretEnv(s, p);
+    if (r.ok) out.set(s.name, r.env);
+    else failures.push(r.message);
+  }
+  if (failures.length) throw new Error(failures.join("\n"));
+  return out;
+}
+
 export async function cmdStack(argv: string[]): Promise<void> {
   const { service, rest } = serviceFlag(argv);
   const [sub = "ls", ...args] = rest;
@@ -62,21 +89,32 @@ export async function cmdStack(argv: string[]): Promise<void> {
       return;
     case "up": {
       // Re-render the edge so its cert covers every stack, then start the stacks.
+      const order = startOrder(pick(), stacks);
+      const secrets = await resolveStacksSecretEnv(order.map((n) => stacks[n]));
       await edgeUp(edge);
-      for (const n of startOrder(pick(), stacks)) {
+      for (const n of order) {
         console.log(chalk.cyan(`\n▶ ${n} (${projectName(n, ctx.workspace)})`));
-        stackUp(ctx, stacks[n], { build: args.includes("--build") });
+        stackUp(ctx, stacks[n], {
+          build: args.includes("--build"),
+          secretEnv: secrets.get(n),
+        });
         for (const route of Object.keys(stacks[n].routes))
           console.log(chalk.green(`  ✓ ${routeUrl(`${route}.${n}`, edge)}`));
       }
       return;
     }
-    case "restart":
+    case "restart": {
+      // Resolved before the down: a missing secret leaves the stack running.
+      const secrets = await resolveStacksSecretEnv(
+        pick().map((n) => stacks[n]),
+      );
       if (service) {
         // One compose service, in place: no edge re-render, no recreate.
         for (const n of pick()) {
           console.log(chalk.cyan(`↻ ${n} ${service}`));
-          stackRestartService(ctx, stacks[n], service);
+          stackRestartService(ctx, stacks[n], service, {
+            secretEnv: secrets.get(n),
+          });
         }
         return;
       }
@@ -84,9 +122,13 @@ export async function cmdStack(argv: string[]): Promise<void> {
       for (const n of pick()) {
         console.log(chalk.cyan(`↻ ${n}`));
         stackDown(ctx, stacks[n]);
-        stackUp(ctx, stacks[n], { build: args.includes("--build") });
+        stackUp(ctx, stacks[n], {
+          build: args.includes("--build"),
+          secretEnv: secrets.get(n),
+        });
       }
       return;
+    }
     case "health": {
       let ok = true;
       for (const n of pick()) {

package/src/ui/mcp/connect.ts

@@ -107,10 +107,12 @@ export const MCP_CLIENTS: readonly McpClient[] = [
               "claude",
               "mcp",
               "add",
+              // The name first: claude's -e takes several values, so a name
+              // after the env pairs is read as one more pair.
+              s.name,
               "--scope",
               "user",
               ...envFlags("-e", s.env),
-              s.name,
               "--",
               s.command,
               ...s.args,

package/src/ui/server/index.ts

@@ -68,6 +68,7 @@ import {
 } from "../../shared/environment-manager/health.js";
 import {
   runServiceCommand,
+  prepareServiceSecretEnv,
   resolveService,
   listDaemons,
   unregisterDaemon,
@@ -1477,6 +1478,8 @@ async function handleRequest(
           {
             run: runServiceCommand,
             health: (r) => checkServiceHealth(r, "local"),
+            secretEnv: (address, cmd, workspace) =>
+              prepareServiceSecretEnv(address, cmd, workspace),
           },
         );
         return;

package/src/ui/server/lifecycle-exec.ts

@@ -21,6 +21,7 @@ import type { ResolvedService } from "../../shared/types/index.js";
 import type {
   RunCommandOptions,
   RunCommandResult,
+  ServiceSecretEnvResult,
 } from "../../shared/environment-manager/service-runner.js";
 import type { ServiceHealthResult } from "../../shared/environment-manager/health.js";
 
@@ -34,6 +35,16 @@ export function isLifecycleExecCmd(c: string): c is LifecycleExecCmd {
 export interface LifecycleExecDeps {
   run: (o: RunCommandOptions) => RunCommandResult;
   health: (r: ResolvedService) => Promise<ServiceHealthResult>;
+  /**
+   * R16: resolve the service's secret_env (prepareServiceSecretEnv). Unset,
+   * nothing is resolved, and the runner refuses to start a service that
+   * declares secret_env.
+   */
+  secretEnv?: (
+    address: string,
+    cmd: LifecycleExecCmd,
+    workspace?: string,
+  ) => Promise<ServiceSecretEnvResult>;
   /** Health poll interval after a detached start (default 1s). */
   pollMs?: number;
   /** Stop polling after this long (default 120s). */
@@ -106,12 +117,24 @@ export async function streamLifecycleExec(
     }
   }
 
+  // R16: all of the service's secret_env, or nothing starts. The message
+  // names keys, refs and the provider, never a value.
+  const secrets = deps.secretEnv
+    ? await deps.secretEnv(resolved.address, cmd, o.workspace)
+    : { ok: true as const, secretEnv: undefined };
+  if (!secrets.ok) {
+    if (!clientGone) emit({ type: "error", text: secrets.message });
+    finish(1, true);
+    return;
+  }
+
   const result = deps.run({
     address: resolved.address,
     command: cmd,
     workspace: o.workspace,
     runtime: "daemon",
     env: o.env,
+    secretEnv: secrets.secretEnv,
     onLine: (text) => {
       if (!clientGone) emit({ type: "line", text });
     },

package/src/ui/server/workspace-routes.ts

@@ -44,6 +44,7 @@ import {
   checkServiceHealth,
   claimHealthyService,
   runServiceCommand,
+  prepareServiceSecretEnv,
   resolveService,
   hasRunningOpctlContainers,
   releaseWorkspaceDaemons,
@@ -1411,6 +1412,10 @@ export async function handleWorkspaceRoutes(
     const startTime = Date.now();
     let overallExit = 0;
     let ranCount = 0;
+    // R16: each started service's resolved secret_env, by position in
+    // `ordered`. Resolved before a restart's down, so a missing key leaves
+    // the service running; the values only go into the runner's spawn env.
+    const preparedSecrets = new Map<number, Record<string, string>>();
 
     // Run services sequentially in dependency order
     const runNext = (i: number): void => {
@@ -1508,6 +1513,32 @@ export async function handleWorkspaceRoutes(
         }
       }
 
+      if ((cmd === "up" || cmd === "restart") && !preparedSecrets.has(i)) {
+        void (async () => {
+          // Phase 2 of a restart is a true `up`, so resolve for that.
+          const r = await prepareServiceSecretEnv(address, "up", ws.name);
+          if (cancelled) return;
+          if (!r.ok) {
+            ranCount++;
+            overallExit = 1;
+            emit({ type: "label", text: address });
+            emit({ type: "error", text: r.message });
+            emit({
+              type: "svc-done",
+              address,
+              exitCode: 1,
+              repoName: svcRepoName,
+              subsystem: svcSubsystem,
+            });
+            runNext(i + 1);
+            return;
+          }
+          preparedSecrets.set(i, r.secretEnv);
+          runNext(i);
+        })();
+        return;
+      }
+
       ranCount++;
 
       emit({ type: "label", text: address });
@@ -1540,6 +1571,7 @@ export async function handleWorkspaceRoutes(
           // the UI just hides the command they came here to watch.
           runtime: "daemon",
           env: getSudoEnv(),
+          secretEnv: preparedSecrets.get(i),
           onLine: (line) => emit({ type: "line", text: line }),
           onClose: (exitCode) => {
             // Release outer-scope refs so the disconnect handler no longer