diff --git a/packages/core/src/config/variable.ts b/packages/core/src/config/variable.ts index 8920fd1b2f1..7ed7f6fab88 100644 --- a/packages/core/src/config/variable.ts +++ b/packages/core/src/config/variable.ts @@ -3,6 +3,7 @@ export * as ConfigVariable from "./variable.js" import os from "os" import path from "path" import { Effect } from "effect" +import { type ParseError, parse } from "jsonc-parser" import { FSUtil } from "@opencode/util/fs-util" import { InvalidError } from "../v1/config/error.js" @@ -24,12 +25,17 @@ type SubstituteInput = ParseSource & { /** Apply {env:VAR} and {file:path} substitutions to config text. */ export const substitute = Effect.fn("ConfigVariable.substitute")(function* (input: SubstituteInput) { - const text = input.text.replace( - /\{env:([^}]+)\}/g, - (_, varName: string) => (input.env?.[varName] ?? process.env[varName]) || "", - ) - if (!text.includes("{file:")) return text - return yield* substituteFiles(input, text) + const env = (escape: boolean) => + input.text.replace(/\{env:([^}]+)\}/g, (_, name: string) => { + const value = (input.env?.[name] ?? process.env[name]) || "" + return escape ? JSON.stringify(value).slice(1, -1) : value + }) + // Escape only when raw values break the JSON (e.g. Windows paths), so configs that parse today keep their meaning. + const raw = yield* substituteFiles(input, env(false)) + const errors: ParseError[] = [] + if (input.text.includes("{env:")) parse(raw, errors, { allowTrailingComma: true }) + if (!errors.length) return raw + return yield* substituteFiles(input, env(true)) }) const substituteFiles = Effect.fnUntraced(function* (input: SubstituteInput, text: string) { diff --git a/packages/core/test/config/config.test.ts b/packages/core/test/config/config.test.ts index 680b47b74a2..e1c7a8cf460 100644 --- a/packages/core/test/config/config.test.ts +++ b/packages/core/test/config/config.test.ts @@ -14,6 +14,8 @@ import { Credential } from "@opencode/core/credential" import { ConfigV1 } from "../fixture/v1-config/config" import { ConfigPermissionV1 } from "@opencode/core/v1/config/permission" import { ConfigNormalize } from "@opencode/core/config/normalize" +import { ConfigVariable } from "@opencode/core/config/variable" +import { FSUtil } from "@opencode/util/fs-util" import { Watcher } from "@opencode/core/filesystem/watcher" import { Bus } from "@opencode/core/bus" import { Global } from "@opencode/util/global" @@ -1335,8 +1337,10 @@ describe("Config", () => { const previous = { token: process.env.OPENCODE_TEST_MCP_TOKEN, missing: process.env.OPENCODE_TEST_MISSING, + flag: process.env.OPENCODE_TEST_FLAG, } - process.env.OPENCODE_TEST_MCP_TOKEN = "secret" + process.env.OPENCODE_TEST_FLAG = "false" + process.env.OPENCODE_TEST_MCP_TOKEN = String.raw`C:\Users\new\"secret"` delete process.env.OPENCODE_TEST_MISSING return previous }), @@ -1353,6 +1357,7 @@ describe("Config", () => { `{ // Ignored reference: {file:.} "username": "user-{env:OPENCODE_TEST_MISSING}", + "snapshots": {env:OPENCODE_TEST_FLAG}, "mcp": { "servers": { "remote": { @@ -1375,11 +1380,12 @@ describe("Config", () => { const config = yield* Config.Service const document = (yield* config.entries()).find((entry) => entry.type === "document") expect(document?.info.username).toBe("user-") + expect(document?.info.snapshots).toBe(false) const remote = document?.info.mcp?.servers?.remote expect(remote?.type).toBe("remote") if (remote?.type !== "remote") return expect(remote.headers).toEqual({ - Authorization: "Bearer secret", + Authorization: String.raw`Bearer C:\Users\new\"secret"`, "X-Token": 'file\n"token"', "X-Missing": "Bearer ", }) @@ -1393,10 +1399,25 @@ describe("Config", () => { else process.env.OPENCODE_TEST_MCP_TOKEN = previous.token if (previous.missing === undefined) delete process.env.OPENCODE_TEST_MISSING else process.env.OPENCODE_TEST_MISSING = previous.missing + if (previous.flag === undefined) delete process.env.OPENCODE_TEST_FLAG + else process.env.OPENCODE_TEST_FLAG = previous.flag }), ), ) + it.effect("keeps env values unescaped when the config already parses", () => + Effect.gen(function* () { + const text = yield* ConfigVariable.substitute({ + type: "virtual", + source: "test", + dir: "/", + text: '{ "quoted": "{env:QUOTED}", "fragment": {env:FRAGMENT} }', + env: { QUOTED: String.raw`a\"b`, FRAGMENT: '{"k":"v"}' }, + }) + expect(JSON.parse(text)).toEqual({ quoted: 'a"b', fragment: { k: "v" } }) + }).pipe(Effect.provide(AppNodeBuilder.build(FSUtil.node))), + ) + it.live("does not load legacy config.json files", () => Effect.acquireDisposable(Effect.promise(() => tmpdir())).pipe( Effect.flatMap((tmp) => diff --git a/services/www/src/docs/content/config.mdx b/services/www/src/docs/content/config.mdx index fbe8b1a2d6d..4f79c93f870 100644 --- a/services/www/src/docs/content/config.mdx +++ b/services/www/src/docs/content/config.mdx @@ -556,3 +556,56 @@ headers, and model variants. Provider `settings.transport: "websocket"` selects its session WebSocket. See the [providers guide](/providers) for credentials, custom endpoints, provider packages, the WebSocket transport, and model configuration. + +## Variables + +You can use variable substitution in your config files to reference environment variables and file contents. Place references inside JSON strings. + +### Env vars + +Use `{env:VARIABLE_NAME}` to substitute environment variables: + +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "model": "{env:OPENCODE_MODEL}", + "providers": { + "anthropic": { + "settings": { + "apiKey": "{env:ANTHROPIC_API_KEY}", + }, + }, + }, +} +``` + +If the environment variable is not set, it will be replaced with an empty string. + +### Files + +Use `{file:path/to/file}` to substitute the contents of a file: + +```jsonc title="opencode.jsonc" +{ + "$schema": "https://opencode.ai/config.json", + "providers": { + "openai": { + "settings": { + "apiKey": "{file:~/.secrets/openai-key}", + }, + }, + }, +} +``` + +File paths can be: + +- Relative to the config file directory +- Absolute, or starting with `~/` for your home directory + +If the file does not exist, it will be replaced with an empty string. + +These are useful for: + +- Keeping sensitive data like API keys in separate files. +- Sharing common configuration snippets across multiple config files.