diff --git a/packages/opencode/src/config/config.ts b/packages/opencode/src/config/config.ts
index 9aaa31ea..2d896a53 100644
--- a/packages/opencode/src/config/config.ts
+++ b/packages/opencode/src/config/config.ts
@@ -10,6 +10,7 @@ import fs from "fs/promises"
 import { lazy } from "../util/lazy"
 import { NamedError } from "../util/error"
 import matter from "gray-matter"
+import { Flag } from "../flag/flag"
 
 export namespace Config {
   const log = Log.create({ service: "config" })
@@ -23,6 +24,12 @@ export namespace Config {
       }
     }
 
+    // Override with custom config if provided
+    if (Flag.OPENCODE_CONFIG) {
+      result = mergeDeep(result, await load(Flag.OPENCODE_CONFIG))
+      log.debug("loaded custom config", { path: Flag.OPENCODE_CONFIG })
+    }
+
     result.agent = result.agent || {}
     const markdownAgents = [
       ...(await Filesystem.globUp("agent/*.md", Global.Path.config, Global.Path.config)),
diff --git a/packages/opencode/src/flag/flag.ts b/packages/opencode/src/flag/flag.ts
index e6f54440..afc610b6 100644
--- a/packages/opencode/src/flag/flag.ts
+++ b/packages/opencode/src/flag/flag.ts
@@ -1,6 +1,7 @@
 export namespace Flag {
   export const OPENCODE_AUTO_SHARE = truthy("OPENCODE_AUTO_SHARE")
   export const OPENCODE_DISABLE_WATCHER = truthy("OPENCODE_DISABLE_WATCHER")
+  export const OPENCODE_CONFIG = process.env["OPENCODE_CONFIG"]
 
   function truthy(key: string) {
     const value = process.env[key]?.toLowerCase()
diff --git a/packages/web/src/content/docs/docs/config.mdx b/packages/web/src/content/docs/docs/config.mdx
index 34184107..abd05c33 100644
--- a/packages/web/src/content/docs/docs/config.mdx
+++ b/packages/web/src/content/docs/docs/config.mdx
@@ -34,6 +34,17 @@ This is also safe to be checked into Git and uses the same schema as the global
 
 ---
 
+### Custom config file
+
+You can specify a custom config file using the `OPENCODE_CONFIG` environment variable. This takes precedence over the global and project configs.
+
+```bash
+export OPENCODE_CONFIG=/path/to/my/custom-config.json
+opencode run "Hello world"
+```
+
+---
+
 ## Schema
 
 The config file has a schema that's defined in [**`opencode.ai/config.json`**](https://opencode.ai/config.json).