Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

Make the base model key a deployment secret, and document Slack sign-in (#21)

Joshua Francea2e752f25ac2
diff --git a/.codex/skills/deploy-qm/SKILL.md b/.codex/skills/deploy-qm/SKILL.md
index e4d73d6a7..3a470a227 100644
--- a/.codex/skills/deploy-qm/SKILL.md
+++ b/.codex/skills/deploy-qm/SKILL.md
@@ -11,6 +11,13 @@ as the authoritative workflow. Read only the selected provider reference. Read
transport and one of its steps needs the operator's DNS. Read
`references/slack.md` only when Slack is requested.
+A deployment needs a base model key and a way for people to sign in. Collect
+both in the same pass. The base model provider is a deployment choice recorded
+as `modelProvider`, not a setting to leave for the Admin page. Sign-in is either
+the built-in `auth` broker, which needs an email transport, or an external OIDC
+provider such as Slack, which needs no email at all — read `references/email.md`
+only once the operator has chosen the broker.
+
Use the installed `@yc-software/qm` dependency through `npm exec qm -- <command>`. Do
not require or clone the QM source repository. Complete every acceptance check
and return the handoff required by `deployment.md`.
diff --git a/cli/src/backends/aws.ts b/cli/src/backends/aws.ts
index 5d34424c3..b7f87d0c4 100644
--- a/cli/src/backends/aws.ts
+++ b/cli/src/backends/aws.ts
@@ -215,6 +215,7 @@ export function serviceEnvironment(config: QmConfig, service: ServiceName): Reco
service === "core"
? {
...(config.model ? { PI_MODEL: config.model } : {}),
+ ...(config.modelProvider ? { MODEL_PROVIDER: config.modelProvider } : {}),
...virtualServiceEnv(config.services, config.env),
}
: {};
diff --git a/cli/src/backends/docker.ts b/cli/src/backends/docker.ts
index b0a8e3afa..232f078ab 100644
--- a/cli/src/backends/docker.ts
+++ b/cli/src/backends/docker.ts
@@ -313,6 +313,7 @@ function serviceEnv(ctx: DockerCtx, service: ServiceName): Record<string, string
out.RUN_STORE = "postgres";
out.DATABASE_URL = ctx.databaseUrl;
if (config.model) out.PI_MODEL = config.model;
+ if (config.modelProvider) out.MODEL_PROVIDER = config.modelProvider;
const layerSubs = existingLayerSubdirs(ctx);
if (layerSubs.length) out.DEPLOYMENT_LAYER = "/layer";
Object.assign(out, ctx.sandboxEnv);
diff --git a/cli/src/backends/doctor.ts b/cli/src/backends/doctor.ts
index d72197335..cd6db1395 100644
--- a/cli/src/backends/doctor.ts
+++ b/cli/src/backends/doctor.ts
@@ -1,6 +1,6 @@
import { existsSync, readFileSync } from "node:fs";
import { join, resolve } from "node:path";
-import { validatePortalTrust, type QmConfig } from "../config.ts";
+import { MODEL_PROVIDER_KEYS, validatePortalTrust, type ModelProvider, type QmConfig } from "../config.ts";
import { CliError, errMessage, step, warn } from "../log.ts";
import { capture, deploymentSecretValue, flyBin, isInvalidSecret, readEnvFile, which } from "../util.ts";
import { computedSecrets } from "../secrets.ts";
@@ -189,6 +189,57 @@ export async function doctorCommon(
);
}
if (config.services.includes("auth")) await authBrokerCheck(config, secrets, opts.requiredSecretValues === true);
+ await baseModelCheck(config, secrets);
+}
+
+/**
+ * Prove the base-model key is accepted before the deployment is called finished. The Admin
+ * page validates a key on entry; a deployment that ships its key from `.env` gets no such
+ * feedback, and an unusable key would otherwise surface as a failed first chat message.
+ */
+async function baseModelCheck(config: QmConfig, secrets: Map<string, string>): Promise<void> {
+ const provider = config.modelProvider;
+ if (!provider) {
+ step("base model: no modelProvider set — an administrator supplies the key from the Admin page");
+ return;
+ }
+ const name = MODEL_PROVIDER_KEYS[provider];
+ const key = deploymentSecretValue(name, secrets.get(name));
+ if (!key) {
+ warn(`${name} is not available locally — skipping the live ${provider} check`);
+ return;
+ }
+ await modelProviderCheck(provider, key);
+ step(`base model provider ${provider}: ${name} accepted`);
+}
+
+const MODEL_PROVIDER_PROBES: Readonly<
+ Record<ModelProvider, { url: string; headers: (key: string) => Record<string, string> }>
+> = {
+ anthropic: {
+ url: "https://api.anthropic.com/v1/models?limit=1",
+ headers: (key) => ({ "x-api-key": key, "anthropic-version": "2023-06-01" }),
+ },
+ openai: { url: "https://api.openai.com/v1/models", headers: (key) => ({ authorization: `Bearer ${key}` }) },
+ openrouter: { url: "https://openrouter.ai/api/v1/key", headers: (key) => ({ authorization: `Bearer ${key}` }) },
+};
+
+async function modelProviderCheck(provider: ModelProvider, apiKey: string): Promise<void> {
+ const probe = MODEL_PROVIDER_PROBES[provider];
+ let res: Response;
+ try {
+ res = await fetch(probe.url, { headers: probe.headers(apiKey), signal: AbortSignal.timeout(10_000) });
+ } catch (e) {
+ throw new CliError(
+ `could not reach the ${provider} API: ${errMessage(e)} — check network access (and any proxy) and retry`,
+ );
+ }
+ if (res.status === 401 || res.status === 403) {
+ throw new CliError(
+ `${provider} rejected ${MODEL_PROVIDER_KEYS[provider]} — the deployment would start but could not serve a single agent turn`,
+ );
+ }
+ if (!res.ok) throw new CliError(`the ${provider} API returned HTTP ${res.status}; retry when it recovers`);
}
async function resendCheck(apiKey: string): Promise<void> {
diff --git a/cli/src/backends/fly.ts b/cli/src/backends/fly.ts
index 97ee5e4c3..429b318cf 100644
--- a/cli/src/backends/fly.ts
+++ b/cli/src/backends/fly.ts
@@ -180,7 +180,13 @@ function deriveToml(ctx: FlyCtx, service: ServiceName): string {
const base = readFileSync(existsSync(nested) ? nested : join(ctx.templateRoot, `${service}.toml`), "utf8");
const sandboxEnv = service === "core" ? sandboxCoreEnv(ctx.config).env : {};
const virtualEnv = service === "core" ? virtualServiceEnv(ctx.config.services, ctx.config.env) : {};
- const modelEnv: Record<string, string> = service === "core" && ctx.config.model ? { PI_MODEL: ctx.config.model } : {};
+ const modelEnv: Record<string, string> =
+ service === "core"
+ ? {
+ ...(ctx.config.model ? { PI_MODEL: ctx.config.model } : {}),
+ ...(ctx.config.modelProvider ? { MODEL_PROVIDER: ctx.config.modelProvider } : {}),
+ }
+ : {};
const configuredEnv = { ...ctx.config.env[service] };
if (service === "core") {
delete configuredEnv.FLY_ORG;
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 675457fa8..27543f8ca 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -1,7 +1,15 @@
import { spawnSync } from "node:child_process";
import { dirname, join, resolve } from "node:path";
import { CliError, bold, dim, errMessage, note, red } from "./log.ts";
-import { findConfigPath, loadConfigAt, loadConfigInDir, readConfigOrgId } from "./config.ts";
+import {
+ findConfigPath,
+ isModelProvider,
+ loadConfigAt,
+ loadConfigInDir,
+ readConfigOrgId,
+ MODEL_PROVIDERS,
+ type ModelProvider,
+} from "./config.ts";
import { HOSTING_PROVIDER_IDS, hostingProviderChoices, isTarget, type Target } from "./providers.ts";
import { type LogOpts } from "./services.ts";
import { runInit } from "./commands/init.ts";
@@ -70,6 +78,14 @@ function targetFlag(flags: Flags): Target | undefined {
return target;
}
+function modelProviderFlag(flags: Flags): ModelProvider | undefined {
+ const provider = strFlag(flags, "model-provider");
+ if (provider !== undefined && !isModelProvider(provider)) {
+ throw new CliError(`--model-provider must be ${MODEL_PROVIDERS.join(" | ")}`, { clause: "cli.invocation" });
+ }
+ return provider;
+}
+
function version(): string {
return cliVersion();
}
@@ -84,7 +100,10 @@ ${bold("USAGE")}
${bold("DEPLOY (operator)")} ${dim("— runs in the deployment directory")}
init [path] [--org <id>] [--target ${HOSTING_PROVIDER_IDS.join("|")}]
- scaffold a deployment directory
+ [--model-provider ${MODEL_PROVIDERS.join("|")}]
+ scaffold a deployment directory (the base model
+ provider defaults to anthropic; its API key is a
+ required secret)
setup [path] interactive wizard: scaffold if needed, then walk the
missing secrets with per-provider instructions
up build images and bring the deployment up
@@ -216,12 +235,18 @@ async function dispatch(argv: string[]): Promise<void> {
}
case "init": {
- rejectUnknownFlags(flags, ["org", "target"]);
+ rejectUnknownFlags(flags, ["org", "target", "model-provider"]);
rejectExtraPositionals(positionals, 1);
const target = targetFlag(flags);
+ const modelProvider = modelProviderFlag(flags);
const org = strFlag(flags, "org");
const dir = positionals[0] !== undefined ? resolve(positionals[0]) : resolve(process.cwd());
- runInit({ dir, ...(org ? { org } : {}), ...(target ? { target } : {}) });
+ runInit({
+ dir,
+ ...(org ? { org } : {}),
+ ...(target ? { target } : {}),
+ ...(modelProvider ? { modelProvider } : {}),
+ });
return;
}
diff --git a/cli/src/commands/init.ts b/cli/src/commands/init.ts
index fee93d19a..3b704a435 100644
--- a/cli/src/commands/init.ts
+++ b/cli/src/commands/init.ts
@@ -2,7 +2,15 @@ import { randomBytes } from "node:crypto";
import { spawnSync } from "node:child_process";
import { chmodSync, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
import { dirname, isAbsolute, join, relative, resolve } from "node:path";
-import { CONFIG_FILENAME, configPathInDir, loadConfigAt, validOrgId, type Target, type QmConfig } from "../config.ts";
+import {
+ CONFIG_FILENAME,
+ configPathInDir,
+ loadConfigAt,
+ validOrgId,
+ type ModelProvider,
+ type Target,
+ type QmConfig,
+} from "../config.ts";
import { die, note, ok, warn } from "../log.ts";
import { cliPackageName, cliVersion } from "../manifest.ts";
import { computedSecrets, renderEnvExample } from "../secrets.ts";
@@ -246,7 +254,7 @@ function scaffoldDeploymentSkill(dir: string): void {
}
}
-export function runInit(opts: { org?: string; target?: Target; dir?: string }): void {
+export function runInit(opts: { org?: string; target?: Target; modelProvider?: ModelProvider; dir?: string }): void {
const orgId = opts.org ?? "default-org";
if (!validOrgId(orgId)) die(`--org must be a lowercase DNS label (a-z, 0-9, and hyphens between)`);
const dir = opts.dir ?? process.cwd();
@@ -261,9 +269,10 @@ export function runInit(opts: { org?: string; target?: Target; dir?: string }):
}
const target: Target = opts.target ?? "docker";
+ const modelProvider: ModelProvider = opts.modelProvider ?? "anthropic";
const provider = hostingProvider(target);
- writeFileSync(configPath, provider.scaffold.renderConfig(orgId));
- ok(`wrote ${CONFIG_FILENAME} (orgId=${orgId}, target=${target})`);
+ writeFileSync(configPath, provider.scaffold.renderConfig(orgId, modelProvider));
+ ok(`wrote ${CONFIG_FILENAME} (orgId=${orgId}, target=${target}, modelProvider=${modelProvider})`);
const config = loadConfigAt(configPath).config;
writePackage(dir, preparedPackage);
diff --git a/cli/src/config.ts b/cli/src/config.ts
index cd3602e91..e04c443bf 100644
--- a/cli/src/config.ts
+++ b/cli/src/config.ts
@@ -104,6 +104,25 @@ export function awsWorkloadArchitecture(config: QmConfig, workload: string): "ar
return service.architecture ?? "arm64";
}
+/**
+ * The vendor supplying the deployment's base model. Selecting one makes that vendor's
+ * API key a required deployment secret, so `qm setup` collects it and `qm up` refuses
+ * to deploy a stack that cannot run a single agent turn. Leaving it unset preserves the
+ * older flow, where an administrator supplies the key from the Admin page after deploy.
+ */
+export const MODEL_PROVIDERS = ["anthropic", "openai", "openrouter"] as const;
+export type ModelProvider = (typeof MODEL_PROVIDERS)[number];
+
+/** The API key each provider's base model is billed against. */
+export const MODEL_PROVIDER_KEYS: Readonly<Record<ModelProvider, string>> = {
+ anthropic: "ANTHROPIC_API_KEY",
+ openai: "OPENAI_API_KEY",
+ openrouter: "OPENROUTER_API_KEY",
+};
+
+export const isModelProvider = (value: unknown): value is ModelProvider =>
+ typeof value === "string" && (MODEL_PROVIDERS as readonly string[]).includes(value);
+
export interface QmConfig {
contract: typeof CONTRACT_VERSION;
orgId: string;
@@ -111,6 +130,7 @@ export interface QmConfig {
apiUrl?: string;
target: Target;
model?: string;
+ modelProvider?: ModelProvider;
basePort?: number;
services: DeclaredServiceName[];
plugins: PluginEntry[];
@@ -625,6 +645,14 @@ function validate(raw: unknown, path: string): QmConfig {
if (typeof apiUrl === "string") out.apiUrl = apiUrl.replace(/\/$/, "");
if (sandbox) out.sandbox = sandbox;
if (typeof o["model"] === "string") out.model = o["model"];
+ if (o["modelProvider"] !== undefined) {
+ if (!isModelProvider(o["modelProvider"])) {
+ throw new CliError(
+ `${path}: "modelProvider" must be one of ${MODEL_PROVIDERS.join(", ")} — it selects which provider key the deployment requires; omit it to supply the base model key from the Admin page instead`,
+ );
+ }
+ out.modelProvider = o["modelProvider"];
+ }
if (o["basePort"] !== undefined) {
const bp = o["basePort"];
if (typeof bp !== "number" || !Number.isInteger(bp) || bp <= 0) {
diff --git a/cli/src/provider-scaffold.ts b/cli/src/provider-scaffold.ts
index e6fa35d58..1c718eb44 100644
--- a/cli/src/provider-scaffold.ts
+++ b/cli/src/provider-scaffold.ts
@@ -1,6 +1,6 @@
import { createHash } from "node:crypto";
import { existsSync, readFileSync } from "node:fs";
-import type { QmConfig } from "./config.ts";
+import type { ModelProvider, QmConfig } from "./config.ts";
import type { Target } from "./providers.ts";
import { declaredVariables, terraformVars } from "./terraform.ts";
@@ -10,7 +10,7 @@ interface ScaffoldFile {
}
export interface ProviderScaffold {
- renderConfig(orgId: string): string;
+ renderConfig(orgId: string, modelProvider: ModelProvider): string;
ignores: readonly string[];
agentsAppendix: string;
files(config: QmConfig): ScaffoldFile[];
@@ -21,6 +21,7 @@ export interface ProviderScaffold {
interface ConfigValues {
target: Target;
+ modelProvider: ModelProvider;
publicUrl: string;
providerFields: string;
services: string[];
@@ -43,6 +44,18 @@ function renderConfig(orgId: string, values: ConfigValues): string {
// Where to deploy: "docker" runs local containers, "fly" deploys Fly apps,
// and "aws" runs the control plane on ECS and agent computers on Lambda MicroVMs.
"target": ${JSON.stringify(values.target)},
+
+ // The vendor supplying the base model: "anthropic", "openai", or "openrouter"
+ // (one key, many models). Naming one makes that vendor's API key a required
+ // deployment secret: \`qm setup\` collects it, \`qm doctor\` proves the provider
+ // accepts it, and \`qm up\` refuses a stack that cannot serve an agent turn.
+ // Delete this line to leave the base model unset and have an administrator add
+ // the key from the Admin page after deploy instead.
+ "modelProvider": ${JSON.stringify(values.modelProvider)},
+
+ // Optional base model id, passed to the harness (e.g. "claude-opus-4-6").
+ // Omit it to use the harness default for the provider above.
+ // "model": "",
${values.providerFields}
// First-party services to run. The full set: "core" (the agent runtime and API,
// always required), "slack" (the Slack surface, runs inside the core process),
@@ -59,9 +72,9 @@ ${values.providerFields}
// Extra directories of SKILL.md files, mounted into the agent.
"skills": [],
- // Non-secret env overrides, per service. HARNESS "pi" runs real agent turns;
- // after deployment, an administrator adds its model provider key in Admin.
- // "mock" runs the whole stack with fake turns and no model calls.
+ // Non-secret env overrides, per service. HARNESS "pi" runs real agent turns
+ // against the base model selected by "modelProvider" above. "mock" runs the
+ // whole stack with fake turns and no model calls.
"env": ${values.env}${values.secretEnv}${values.sandbox}
}
`;
@@ -131,9 +144,10 @@ cannot deregister or delete task definitions.
const noFiles = (): ScaffoldFile[] => [];
export const dockerScaffold: ProviderScaffold = {
- renderConfig: (orgId) =>
+ renderConfig: (orgId, modelProvider) =>
renderConfig(orgId, {
target: "docker",
+ modelProvider,
publicUrl: "http://localhost:8082",
providerFields: "",
services: ["core", "web-ui"],
@@ -154,9 +168,10 @@ export const dockerScaffold: ProviderScaffold = {
};
export const flyScaffold: ProviderScaffold = {
- renderConfig: (orgId) =>
+ renderConfig: (orgId, modelProvider) =>
renderConfig(orgId, {
target: "fly",
+ modelProvider,
publicUrl: `https://${orgId}-portal.fly.dev`,
providerFields: `
// Globally unique prefix for every Fly app in this deployment.
@@ -187,7 +202,7 @@ export const flyScaffold: ProviderScaffold = {
};
export const awsScaffold: ProviderScaffold = {
- renderConfig: (orgId) => {
+ renderConfig: (orgId, modelProvider) => {
const cluster = clusterName(orgId);
const services = Object.fromEntries(
[
@@ -208,6 +223,7 @@ export const awsScaffold: ProviderScaffold = {
);
return renderConfig(orgId, {
target: "aws",
+ modelProvider,
publicUrl: `https://${orgId}.example.com`,
providerFields: `
// AWS coordinates. Replace the account id and public URL before applying infra/.
diff --git a/cli/src/secrets.ts b/cli/src/secrets.ts
index 84fed6ee4..c2631a8cb 100644
--- a/cli/src/secrets.ts
+++ b/cli/src/secrets.ts
@@ -1,5 +1,5 @@
import { isVirtualService, type DeclaredServiceName } from "./services.ts";
-import type { QmConfig } from "./config.ts";
+import type { ModelProvider, QmConfig } from "./config.ts";
type SecretCondition =
| { kind: "env-equals"; service: DeclaredServiceName; name: string; value: string }
@@ -10,7 +10,8 @@ type SecretCondition =
| { kind: "service-enabled"; service: DeclaredServiceName }
| { kind: "service-absent"; service: DeclaredServiceName }
| { kind: "all"; conditions: SecretCondition[] }
- | { kind: "target"; target: QmConfig["target"] };
+ | { kind: "target"; target: QmConfig["target"] }
+ | { kind: "model-provider"; provider: ModelProvider };
export interface SecretSpec {
name: string;
@@ -37,12 +38,34 @@ export const MINT_JWK =
"node -e \"const {generateKeyPairSync}=require('node:crypto');process.stdout.write(JSON.stringify(generateKeyPairSync('ec',{namedCurve:'P-256'}).privateKey.export({format:'jwk'})))\"";
export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [
+ // The base-model key is required whenever the deployment names its provider, so that
+ // `qm setup` collects it and `qm up` cannot produce a stack that fails its first agent
+ // turn. Anthropic and OpenRouter keep an unconditional twin further down: omitting
+ // `modelProvider` leaves the key an optional fallback an administrator supplies from the
+ // Admin page, which is how deployments predating `modelProvider` behave. Those two stay
+ // ahead of their twins — `computedSecrets` describes a secret from the first spec whose
+ // condition matches, and the base-model wording is the accurate one once it applies.
+ {
+ name: "ANTHROPIC_API_KEY",
+ service: "core",
+ required: { when: { kind: "model-provider", provider: "anthropic" } },
+ description: 'Anthropic API key for the deployment base model (modelProvider "anthropic").',
+ },
+ {
+ name: "OPENROUTER_API_KEY",
+ service: "core",
+ required: { when: { kind: "model-provider", provider: "openrouter" } },
+ description: 'OpenRouter API key for the deployment base model (modelProvider "openrouter").',
+ },
{
name: "ANTHROPIC_API_KEY",
service: "core",
required: false,
description: "Optional deployment fallback for Pi; admins can configure the base model key after deploy.",
},
+ // OPENAI_API_KEY keeps the Codex rule ahead of the base-model rule: it is the more
+ // descriptive of the two, and `.env.example` documents a dormant secret from its first
+ // spec. Whichever rule fires, `computedSecrets` collapses them to one required secret.
{
name: "OPENAI_API_KEY",
service: "core",
@@ -50,6 +73,12 @@ export const FIRST_PARTY_SECRET_SPECS: readonly SecretSpec[] = [
description:
"OpenAI API key used by the Codex harness (its CLI cannot do browser OAuth in a container); an optional deployment fallback for Pi otherwise.",
},
+ {
+ name: "OPENAI_API_KEY",
+ service: "core",
+ required: { when: { kind: "model-provider", provider: "openai" } },
+ description: 'OpenAI API key for the deployment base model (modelProvider "openai").',
+ },
{
name: "OPENROUTER_API_KEY",
service: "core",
@@ -359,6 +388,7 @@ function conditionMatches(config: QmConfig, condition: SecretCondition): boolean
if (condition.kind === "service-absent") return !config.services.includes(condition.service);
if (condition.kind === "all") return condition.conditions.every((nested) => conditionMatches(config, nested));
if (condition.kind === "target") return config.target === condition.target;
+ if (condition.kind === "model-provider") return config.modelProvider === condition.provider;
if (condition.kind === "env-all-absent") {
return condition.names.every((name) => !config.env[condition.service]?.[name]?.trim());
}
@@ -535,6 +565,7 @@ function conditionClause(condition: SecretCondition): string {
if (condition.kind === "env-present") return `env.${condition.service}.${condition.name} is set`;
if (condition.kind === "env-in")
return `env.${condition.service}.${condition.name} is one of ${condition.values.map((value) => JSON.stringify(value)).join(", ")}`;
+ if (condition.kind === "model-provider") return `modelProvider is ${JSON.stringify(condition.provider)}`;
return `env.${condition.service}.${condition.name} is ${JSON.stringify(condition.value)}`;
}
@@ -565,13 +596,20 @@ export function renderEnvExample(config: QmConfig): string {
const inactive = FIRST_PARTY_SECRET_SPECS.filter(
(spec, i, all) => !activeNames.has(spec.name) && all.findIndex((s) => s.name === spec.name) === i,
);
- for (const spec of inactive) {
- const clauses = [
+ const clauseFor = (spec: SecretSpec): string =>
+ [
...(config.services.includes(spec.service) ? [] : [`the ${spec.service} service is enabled`]),
...(typeof spec.required === "boolean" ? [] : [conditionClause(spec.required.when)]),
- ];
+ ].join(" and ");
+ for (const spec of inactive) {
+ // One secret can answer to several independent rules — an OpenAI base model or the
+ // Codex harness, say. List them as alternatives so the catalog does not imply the
+ // first rule is the only way the secret becomes required.
+ const rules = FIRST_PARTY_SECRET_SPECS.filter((other) => other.name === spec.name);
+ const clauses = [...new Set(rules.map(clauseFor).filter(Boolean))];
+ const optionalEvenThen = rules.every((rule) => rule.required === false);
lines.push(`# ${spec.description} (${spec.service})`);
- lines.push(`# Needed when ${clauses.join(" and ")}${spec.required === false ? " (optional even then)" : ""}.`);
+ lines.push(`# Needed when ${clauses.join(" or ")}${optionalEvenThen ? " (optional even then)" : ""}.`);
if (spec.generate) lines.push(`# Generate with: ${generate(spec.generate)}`);
lines.push(spec.managedBy === "terraform" ? `# ${spec.name}= # populated by Terraform` : `# ${spec.name}=`);
lines.push("");
diff --git a/cli/templates/deployment/SKILL.md b/cli/templates/deployment/SKILL.md
index 31401698f..055743be7 100644
--- a/cli/templates/deployment/SKILL.md
+++ b/cli/templates/deployment/SKILL.md
@@ -11,6 +11,13 @@ before collecting secrets, because sign-in needs an email transport and one of
its steps needs the operator's DNS. Read `references/slack.md` only when Slack
is requested.
+A deployment needs a base model key and a way for people to sign in. Collect
+both in the same pass. The base model provider is a deployment choice recorded
+as `modelProvider`, not a setting to leave for the Admin page. Sign-in is either
+the built-in `auth` broker, which needs an email transport, or an external OIDC
+provider such as Slack, which needs no email at all — read `references/email.md`
+only once the operator has chosen the broker.
+
Use the repository's installed `@yc-software/qm` dependency through
`npm exec qm -- <command>`. Do not require or clone the QM source repository.
Do not stop at infrastructure health: complete the acceptance checks and return
diff --git a/cli/templates/deployment/deployment.md b/cli/templates/deployment/deployment.md
index 65a763dec..175040af6 100644
--- a/cli/templates/deployment/deployment.md
+++ b/cli/templates/deployment/deployment.md
@@ -19,9 +19,19 @@ it in place. If the repository has not been initialized, collect:
machine, is for a quick local test drive only, and is outside this
workflow; never present it as the recommended path for a real deployment;
- the first administrator's verified work email;
+- how people sign in: the built-in `auth` broker, which emails a one-time link,
+ or an external OIDC provider. Ask whether the company runs on Slack before
+ assuming the broker — Slack sign-in needs no email transport, no sending
+ domain, and no DNS, and domain verification is the step most likely to stall
+ a deploy. Recommend Slack sign-in to a Slack workspace and the broker
+ otherwise;
- model provider: Anthropic, OpenAI, or OpenRouter (one key that routes to
- many models). The key is entered later on the Admin page, so "decide later"
- is acceptable;
+ many models). This is a deployment choice, not a post-deploy one: it becomes
+ `modelProvider` in `qm.config.jsonc`, which makes that provider's API key a
+ required secret. Collect the key in the same pass as the other credentials —
+ a deployment that cannot answer one message is not finished. An operator who
+ genuinely wants to defer omits `modelProvider` and adds the key from the
+ Admin page later, but do not offer that as the default;
- model;
- region and provider account or organization;
- whether the provider hostname is acceptable;
@@ -51,10 +61,14 @@ and the derived slug, install an exact CLI version, and initialize its root:
```bash
npm exec --yes --package=@yc-software/qm@<exact-version> -- \
- qm init . --org <slug> --target <fly-or-aws>
+ qm init . --org <slug> --target <fly-or-aws> --model-provider <provider>
npm install
```
+`--model-provider` takes `anthropic`, `openai`, or `openrouter` and defaults to
+`anthropic`. It writes `modelProvider` into the scaffolded config, which is what
+promotes that provider's key from an optional fallback to a required secret.
+
For an already-initialized clone, install reproducibly. Use `npm ci` when
`package-lock.json` exists; otherwise use `npm install` to create it:
@@ -73,15 +87,21 @@ git check-ignore --quiet .env
Never print, paste into chat, or commit `.env`. Never initialize over an
existing deployment config.
-## 3. Configure the administrator and sign-in
+## 3. Configure the administrator, sign-in, and the base model
Set the exact lowercased administrator email in `.env` as
`ADMIN_GRANTS=<email>:org_admin`.
-Sign-in is the built-in `auth` broker, which emails a one-time link. There is no
-identity provider to register: the CLI generates the broker's signing key and
-the portal's client credentials and derives every `OIDC_*` value from
-`publicUrl`. Setting any of them by hand is refused.
+Follow the sign-in route chosen in step 1. Only the `auth` broker needs an email
+transport; skip to "Slack sign-in" below when the operator picked Slack, and
+skip `references/email.md` entirely with it.
+
+### The built-in broker
+
+The `auth` broker emails a one-time link. There is no identity provider to
+register: the CLI generates the broker's signing key and the portal's client
+credentials and derives every `OIDC_*` value from `publicUrl`. Setting any of
+them by hand is refused.
What the operator supplies is a way to send those emails. Do not ask them to
pick a transport by name; ask what they already use for email. An existing
@@ -94,7 +114,19 @@ Resend and controls DNS for a sending domain should pick `resend`. Set
Resend path needs DNS control you will not have, so raise it with the operator
early. Configure services, model, and the final public origin in the same pass.
-To use an external work-email OIDC provider instead, drop `"auth"` from
+### Slack sign-in
+
+A workspace that already runs on Slack can sign in with it and skip email
+altogether. Drop `"auth"` from `services` and follow
+`.codex/skills/deploy-qm/references/slack.md`, which covers the SSO app, the
+`env.portal` endpoints, the workspace trust boundary, and the client
+credentials. The bot app in that same reference is a separate decision — Slack
+sign-in does not require the agent in the workspace, and the agent does not
+require Slack sign-in.
+
+### Another OIDC provider
+
+To use a different work-email OIDC provider, drop `"auth"` from
`services`, register `<publicUrl>/auth/callback` with the provider, and put its
endpoints and the email gate in `env.portal`. For Google Workspace:
@@ -111,6 +143,24 @@ endpoints and the email gate in `env.portal`. For Google Workspace:
}
```
+### The base model
+
+Whichever sign-in route the deployment takes, the base model needs a key in the
+same pass. `modelProvider` decides which one `qm setup` asks for —
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY` — and the wizard
+prints where to mint it. The operator owns the billing relationship, so they
+create the key; you only place it. It is a required secret, so `qm doctor` calls
+the provider to prove the key is accepted and `qm up` refuses a deployment that
+has none. Treat a rejected key exactly like a rejected sign-in credential: stop
+and get a working one rather than deploying a stack that greets the
+administrator and then fails their first message.
+
+An operator may still prefer to hold the key centrally and rotate it from the
+Admin page. That is a deliberate choice, not the default: drop `modelProvider`
+from `qm.config.jsonc`, note in the handoff that the deployment has no base model
+yet, and finish by walking them through Model provider on the Admin page. Never
+leave a deployment modelless without saying so.
+
Read exactly one provider reference now and follow its provider-specific
preflight and setup order:
@@ -127,10 +177,17 @@ npm exec qm -- conformance
npm exec qm -- outputs --json
```
-Open `adminOnboardingUrl` from the JSON output. In Model provider, enter and
-validate the selected provider key. The write-only Admin surface stores it in
-durable encrypted storage; do not put the key in `.env`, config, chat, or
-terminal output.
+Open `adminOnboardingUrl` from the JSON output and confirm Model provider
+already reports the deployment's base model. It does when `modelProvider` is
+set: the key travelled with the rest of the deployment secrets, so there is
+nothing to paste here. Enter and validate a key on that page only when the
+operator chose to defer, or when they are replacing the deployment key with one
+they would rather rotate from Admin — the write-only surface stores it in
+durable encrypted storage and takes precedence over the deployment key.
+
+Never paste any provider key into chat or terminal output. `.env` is the one
+place a deployment key belongs, and `qm secrets push` moves it without printing
+it.
Open `webUiUrl`, sign in as the seeded administrator, send a message, and
receive a real model response. Ask the agent to create a fresh UUID in
@@ -148,31 +205,37 @@ Open `adminConnectorsUrl` from `outputs --json`. For each chosen connector:
Verify configured connectors appear and unconfigured connectors remain hidden.
-## 6. Add Slack
+## 6. Add the Slack bot
-Skip this when Slack was deferred. Otherwise read
-`.codex/skills/deploy-qm/references/slack.md`, then run:
+This is the agent in the workspace, not sign-in; a deployment using Slack
+sign-in already created its SSO app in step 3. Skip this when the bot was
+deferred. Otherwise read `.codex/skills/deploy-qm/references/slack.md`, then run:
```bash
npm exec qm -- slack render
npm exec qm -- outputs
```
-Create the app from the exact manifest URL. Enter its bot and app tokens in the
-Admin Slack card, invite it to a test channel, mention it, and receive a reply.
+Create the app from the exact bot manifest URL. Enter its bot and app tokens in
+the Admin Slack card, invite it to a test channel, mention it, and receive a
+reply.
## 7. Return the handoff
Return:
- the web, Admin onboarding, Admin connectors, and user connections URLs;
-- Slack app and test-channel links when enabled;
+- how people sign in, and the Slack SSO app link when that is the route;
+- Slack bot app and test-channel links when enabled;
- provider, account or organization, and region;
+- the base model provider and where its key lives — the deployment `.env` or the
+ Admin page — so the operator knows what to rotate and where;
- pass/fail for health, sign-in, web chat, agent-computer proof, connector
visibility, user OAuth, Slack reply, live check, conformance, and an
idempotent deployment rerun;
- `npm exec qm -- status`, logs, rollback, and teardown commands;
-- recurring cost or manual work still owned by the operator.
+- recurring cost or manual work still owned by the operator, including model
+ usage billed directly by the provider.
Do not claim completion with a missing test or placeholder. If blocked, leave
the repository resumable and name the exact next human action without exposing
diff --git a/cli/templates/deployment/references/slack.md b/cli/templates/deployment/references/slack.md
index 36e8590f3..f218c6602 100644
--- a/cli/templates/deployment/references/slack.md
+++ b/cli/templates/deployment/references/slack.md
@@ -1,4 +1,17 @@
-# Slack app
+# Slack apps
+
+Slack does two independent jobs for a deployment, and each is its own Slack app.
+Create only what the operator asked for.
+
+| App | Job | Enabled by |
+| -------- | ------------------------------------------------------------ | ------------------------------ |
+| `qm` | the agent in channels, DMs, and group messages | `"slack"` in `services` |
+| `qm SSO` | signs people in to the web surfaces with their Slack account | Slack OIDC instead of `"auth"` |
+
+A workspace can have one without the other: the bot alongside email sign-in, or
+Slack sign-in with no bot.
+
+## The bot app
QM uses one private Socket Mode app per deployment and workspace.
@@ -14,4 +27,59 @@ Bot dashboard: https://api.slack.com/apps/<bot-app-id>
Test channel: https://app.slack.com/client/<team-id>/<channel-id>
```
-Keep token values out of Git, chat, and terminal output.
+## The SSO app
+
+Slack sign-in replaces the built-in `auth` broker rather than supplementing it.
+It needs no email transport, no verified sender, and no DNS work, which makes it
+the shorter path for a workspace that already runs on Slack. Do not read
+`references/email.md` for this route.
+
+Drop `"auth"` from `services` and declare Slack's endpoints in `env.portal`:
+
+```json
+{
+ "OIDC_AUTH_ENDPOINT": "https://slack.com/openid/connect/authorize",
+ "OIDC_TOKEN_ENDPOINT": "https://slack.com/api/openid.connect.token",
+ "OIDC_USERINFO_ENDPOINT": "https://slack.com/api/openid.connect.userInfo",
+ "OIDC_ISSUER": "https://slack.com",
+ "OIDC_JWKS_URI": "https://slack.com/openid/connect/keys",
+ "PORTAL_EXPECTED_TEAM_ID": "<workspace-team-id>"
+}
+```
+
+The portal already defaults to exactly these endpoints, so sign-in would work
+without them — write them anyway. `qm slack render` and `qm outputs` decide a
+deployment uses Slack sign-in by finding `slack.com` in `env.portal`, and
+silently skip the SSO manifest and its links when the values are left implicit.
+
+Every deployment needs one tenant trust boundary or the portal refuses to start:
+`PORTAL_EXPECTED_TEAM_ID` (the workspace id, and Slack-only),
+`OIDC_ALLOWED_EMAIL_DOMAIN`, or `OIDC_ALLOWED_EMAILS`. Copy the workspace id from
+the Slack About dialog. `PORTAL_EXPECTED_TEAM_ID` is refused while `"auth"` is
+enabled — the two sign-in paths are mutually exclusive, so switch fully.
+
+`qm outputs` requires the `slack` service even when only the SSO app is wanted.
+Keep `"slack"` in `services` and leave its bot tokens unset if the operator does
+not want the agent in their workspace.
+
+Then render and read the links:
+
+```bash
+npm exec qm -- slack render
+npm exec qm -- outputs
+```
+
+`outputs` prints `qm SSO app` (the manifest creation URL), `Slack sign-in`
+(`<publicUrl>/auth/login`), and `Slack SSO callback`
+(`<publicUrl>/auth/callback`). Create the app from the exact creation URL — that
+manifest already carries the callback, so there is no redirect URL to register by
+hand. From Basic Information, put the client secret in `.env` as
+`OIDC_CLIENT_SECRET` and the client id in either `env.portal.OIDC_CLIENT_ID` or
+`.env`, then run `npm exec qm -- secrets push`.
+
+Prove it before calling sign-in done: open the `Slack sign-in` URL, complete
+Slack's consent screen, and land in the Web UI as the administrator. A portal
+answering on `/healthz` has proved nothing about sign-in.
+
+Keep token values, client secrets, and workspace ids out of Git, chat, and
+terminal output.
diff --git a/cli/test/init.test.ts b/cli/test/init.test.ts
index a013099b2..7d2cbded4 100644
--- a/cli/test/init.test.ts
+++ b/cli/test/init.test.ts
@@ -58,17 +58,25 @@ test("init scaffolds a loadable config, generated local secrets, and a valid san
assert.equal(config.target, "docker");
assert.equal(config.publicUrl, "http://localhost:8082");
assert.equal(config.env.core?.HARNESS, "pi");
+ assert.equal(config.modelProvider, "anthropic", "init names a base model provider by default");
assert.deepEqual(config.sandbox, { app: "acme-sandboxes" });
const env = readFileSync(join(dir, ".env.example"), "utf8");
assert.equal(env, renderEnvExample(config), ".env.example is exactly renderEnvExample output");
- for (const line of ["CORE_SIGNING_SECRET=", "SKILL_SIGNING_SECRET="]) {
+ // The scaffold names anthropic as the base model provider, so its key is required
+ // rather than deferred to Admin; the providers not selected stay optional.
+ for (const line of ["CORE_SIGNING_SECRET=", "SKILL_SIGNING_SECRET=", "ANTHROPIC_API_KEY="]) {
assert.ok(env.split("\n").includes(line), `.env.example should require ${line}`);
}
- for (const line of ["# ANTHROPIC_API_KEY= # optional", "# OPENROUTER_API_KEY= # optional"]) {
+ for (const line of ["# OPENROUTER_API_KEY= # optional"]) {
assert.ok(env.split("\n").includes(line), `.env.example should offer ${line}`);
}
- for (const line of ['# Needed when env.core.HARNESS is "codex".', "# OPENAI_API_KEY="]) {
+ // OPENAI_API_KEY answers to two independent rules; the catalog lists both so neither
+ // route to requiring it is hidden behind the other.
+ for (const line of [
+ '# Needed when env.core.HARNESS is "codex" or modelProvider is "openai".',
+ "# OPENAI_API_KEY=",
+ ]) {
assert.ok(env.split("\n").includes(line), `.env.example should defer ${line}`);
}
assert.ok(env.includes("# Generate with: openssl rand -hex 32"), "mintable secrets carry their generation command");
@@ -155,11 +163,11 @@ test("init --target fly scaffolds the full hosted topology and both Slack apps",
"AUTH_EMAIL_FROM=",
"RESEND_API_KEY=",
"PORTAL_SESSION_SECRET=",
+ "ANTHROPIC_API_KEY=",
]) {
assert.ok(env.split("\n").includes(line), `.env.example should require ${line} for the fly scaffold`);
}
for (const line of [
- "# ANTHROPIC_API_KEY= # optional",
"# OPENROUTER_API_KEY= # optional",
"# SLACK_APP_TOKEN= # optional",
"# SLACK_BOT_TOKEN= # optional",
@@ -239,11 +247,11 @@ test("init --target aws scaffolds the full hosted topology, Terraform, and the o
"AUTH_ALLOWED_EMAILS=",
"AUTH_EMAIL_FROM=",
"RESEND_API_KEY=",
+ "ANTHROPIC_API_KEY=",
]) {
assert.ok(env.includes(name), `hosted AWS scaffold requires ${name}`);
}
for (const name of [
- "# ANTHROPIC_API_KEY= # optional",
"# OPENROUTER_API_KEY= # optional",
"# SLACK_BOT_TOKEN= # optional",
"# SLACK_APP_TOKEN= # optional",
diff --git a/cli/test/secrets.test.ts b/cli/test/secrets.test.ts
index f8b0228fa..1427cf2d9 100644
--- a/cli/test/secrets.test.ts
+++ b/cli/test/secrets.test.ts
@@ -192,6 +192,42 @@ test("the sprites token is a catalog secret when the sandbox backend is sprites"
);
});
+test("naming a base model provider makes that provider's key a required deployment secret", () => {
+ for (const [provider, key] of [
+ ["anthropic", "ANTHROPIC_API_KEY"],
+ ["openai", "OPENAI_API_KEY"],
+ ["openrouter", "OPENROUTER_API_KEY"],
+ ] as const) {
+ const config = makeConfig({ modelProvider: provider });
+ assert.equal(secretByName(config, key).required, true, `${provider} requires ${key}`);
+ assert.match(
+ renderEnvExample(config),
+ new RegExp(`^${key}=$`, "m"),
+ `${key} is uncommented in .env.example so setup collects it`,
+ );
+ }
+});
+
+test("the providers a deployment did not select stay optional", () => {
+ const anthropic = makeConfig({ modelProvider: "anthropic" });
+ assert.equal(secretByName(anthropic, "OPENROUTER_API_KEY").required, false);
+ // OPENAI_API_KEY keeps its own Codex rule, so it is absent rather than optional here.
+ assert.ok(!computedSecrets(anthropic).some((secret) => secret.name === "OPENAI_API_KEY"));
+});
+
+test("an OpenAI base model and the Codex harness agree on one required key", () => {
+ const both = makeConfig({ modelProvider: "openai", env: { core: { HARNESS: "codex" } } });
+ const matches = computedSecrets(both).filter((secret) => secret.name === "OPENAI_API_KEY");
+ assert.equal(matches.length, 1, "overlapping rules collapse to a single secret");
+ assert.equal(matches[0]!.required, true);
+});
+
+test("omitting modelProvider preserves the pre-existing deferred-to-Admin behavior", () => {
+ const deferred = makeConfig();
+ assert.equal(secretByName(deferred, "ANTHROPIC_API_KEY").required, false);
+ assert.equal(secretByName(deferred, "OPENROUTER_API_KEY").required, false);
+});
+
test("conditional secret values use the runtime's trimmed enum semantics", () => {
const pi = makeConfig({ env: { core: { HARNESS: " pi " } } });
assert.equal(secretByName(pi, "ANTHROPIC_API_KEY").required, false);
diff --git a/src/deployment/secret-schema.ts b/src/deployment/secret-schema.ts
index af8151a2e..a8d5b1ccd 100644
--- a/src/deployment/secret-schema.ts
+++ b/src/deployment/secret-schema.ts
@@ -12,7 +12,10 @@ export interface RuntimeSecretSpec {
| "aws-deploy-gate"
| "google-oauth"
| "dropbox-oauth"
- | "linear-oauth";
+ | "linear-oauth"
+ | "model-anthropic"
+ | "model-openai"
+ | "model-openrouter";
}
export const CORE_SECRET_SPECS: readonly RuntimeSecretSpec[] = [
@@ -22,6 +25,12 @@ export const CORE_SECRET_SPECS: readonly RuntimeSecretSpec[] = [
{ name: "PORTAL_IDENTITY_SECRET", requiredWhen: "production" },
{ name: "SKILL_SIGNING_SECRET", requiredWhen: "production" },
{ name: "OPENAI_API_KEY", requiredWhen: "codex" },
+ // MODEL_PROVIDER names the vendor supplying the base model. The deployment CLI sets it
+ // from `modelProvider` in qm.config.jsonc, so a stack that declares a provider refuses
+ // to boot without that provider's key rather than accepting turns it cannot serve.
+ { name: "ANTHROPIC_API_KEY", requiredWhen: "model-anthropic" },
+ { name: "OPENAI_API_KEY", requiredWhen: "model-openai" },
+ { name: "OPENROUTER_API_KEY", requiredWhen: "model-openrouter" },
{ name: "DATABASE_URL", requiredWhen: "postgres" },
{ name: "SPRITES_TOKEN", requiredWhen: "sprites" },
{ name: "FLY_API_TOKEN", requiredWhen: "fly-sandbox" },
@@ -44,11 +53,20 @@ export function validateCoreSecretEnv(env: NodeJS.ProcessEnv): string[] {
if (spec.requiredWhen === "aws-deploy-gate") return Boolean(env.AWS_DEPLOY_APPS_DOMAIN);
if (spec.requiredWhen === "google-oauth") return Boolean(env.GOOGLE_OAUTH_CLIENT_ID);
if (spec.requiredWhen === "dropbox-oauth") return Boolean(env.DROPBOX_OAUTH_CLIENT_ID);
+ if (spec.requiredWhen === "model-anthropic") return env.MODEL_PROVIDER?.trim() === "anthropic";
+ if (spec.requiredWhen === "model-openai") return env.MODEL_PROVIDER?.trim() === "openai";
+ if (spec.requiredWhen === "model-openrouter") return env.MODEL_PROVIDER?.trim() === "openrouter";
return Boolean(env.LINEAR_OAUTH_CLIENT_ID);
};
- return CORE_SECRET_SPECS.filter((spec) => enabled(spec) && isInvalidSecret(spec.name, env[spec.name])).map(
- (spec) => spec.name,
- );
+ // OPENAI_API_KEY carries two specs (the Codex harness and an OpenAI base model), so
+ // deduplicate before reporting — a name should be named once however many rules want it.
+ return [
+ ...new Set(
+ CORE_SECRET_SPECS.filter((spec) => enabled(spec) && isInvalidSecret(spec.name, env[spec.name])).map(
+ (spec) => spec.name,
+ ),
+ ),
+ ];
}
function isInvalidSecret(name: string, value: string | undefined): boolean {
diff --git a/test/secret-schema-drift.test.ts b/test/secret-schema-drift.test.ts
index 060f2fd07..272709474 100644
--- a/test/secret-schema-drift.test.ts
+++ b/test/secret-schema-drift.test.ts
@@ -39,6 +39,29 @@ test("AWS deployment app domains reject a missing or placeholder gate secret", (
);
});
+test("a declared base model provider is enforced at boot, not just at deploy time", () => {
+ for (const [provider, key] of [
+ ["anthropic", "ANTHROPIC_API_KEY"],
+ ["openai", "OPENAI_API_KEY"],
+ ["openrouter", "OPENROUTER_API_KEY"],
+ ] as const) {
+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider } as NodeJS.ProcessEnv), [key]);
+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider, [key]: "real-key" } as NodeJS.ProcessEnv), []);
+ assert.deepEqual(validateCoreSecretEnv({ MODEL_PROVIDER: provider, [key]: "replace-me" } as NodeJS.ProcessEnv), [
+ key,
+ ]);
+ }
+ assert.deepEqual(validateCoreSecretEnv({} as NodeJS.ProcessEnv), [], "no provider declared, nothing required");
+});
+
+test("an OpenAI base model on the Codex harness reports its one missing key once", () => {
+ assert.deepEqual(
+ validateCoreSecretEnv({ MODEL_PROVIDER: "openai", HARNESS: "codex" } as NodeJS.ProcessEnv),
+ ["OPENAI_API_KEY"],
+ "two rules wanting the same key must not name it twice",
+ );
+});
+
test("production rejects weak encryption key material for managed credentials", () => {
const strong = "x".repeat(32);
const env = {