feat: add env vars for complete portable mode and isolation support

packages/opencode/src/flag/flag.ts

@@ -9,6 +9,10 @@ export namespace Flag {
   export const OPENCODE_CONFIG = process.env["OPENCODE_CONFIG"]
   export declare const OPENCODE_CONFIG_DIR: string | undefined
   export const OPENCODE_CONFIG_CONTENT = process.env["OPENCODE_CONFIG_CONTENT"]
+  export const OPENCODE_DATA_DIR = process.env["OPENCODE_DATA_DIR"]
+  export const OPENCODE_CACHE_DIR = process.env["OPENCODE_CACHE_DIR"]
+  export const OPENCODE_LOG_DIR = process.env["OPENCODE_LOG_DIR"]
+  export const OPENCODE_STATE_DIR = process.env["OPENCODE_STATE_DIR"]
   export const OPENCODE_DISABLE_AUTOUPDATE = truthy("OPENCODE_DISABLE_AUTOUPDATE")
   export const OPENCODE_DISABLE_PRUNE = truthy("OPENCODE_DISABLE_PRUNE")
   export const OPENCODE_DISABLE_TERMINAL_TITLE = truthy("OPENCODE_DISABLE_TERMINAL_TITLE")

packages/opencode/src/global/index.ts

@@ -2,13 +2,15 @@ import fs from "fs/promises"
 import { xdgData, xdgCache, xdgConfig, xdgState } from "xdg-basedir"
 import path from "path"
 import os from "os"
+import { Flag } from "../flag/flag"
 
 const app = "opencode"
 
-const data = path.join(xdgData!, app)
-const cache = path.join(xdgCache!, app)
+const data = Flag.OPENCODE_DATA_DIR || path.join(xdgData!, app)
+const cache = Flag.OPENCODE_CACHE_DIR || path.join(xdgCache!, app)
+const log = Flag.OPENCODE_LOG_DIR || path.join(data, "log")
 const config = path.join(xdgConfig!, app)
-const state = path.join(xdgState!, app)
+const state = Flag.OPENCODE_STATE_DIR || path.join(xdgState!, app)
 
 export namespace Global {
   export const Path = {
@@ -18,7 +20,7 @@ export namespace Global {
     },
     data,
     bin: path.join(data, "bin"),
-    log: path.join(data, "log"),
+    log,
     cache,
     config,
     state,

packages/web/src/content/docs/cli.mdx

@@ -558,6 +558,10 @@ OpenCode can be configured using environment variables.
 | `OPENCODE_CONFIG`                     | string  | Path to config file                               |
 | `OPENCODE_CONFIG_DIR`                 | string  | Path to config directory                          |
 | `OPENCODE_CONFIG_CONTENT`             | string  | Inline json config content                        |
+| `OPENCODE_DATA_DIR`                   | string  | Path to data directory                            |
+| `OPENCODE_CACHE_DIR`                  | string  | Path to cache directory                           |
+| `OPENCODE_LOG_DIR`                    | string  | Path to log directory                             |
+| `OPENCODE_STATE_DIR`                  | string  | Path to state directory                           |
 | `OPENCODE_DISABLE_AUTOUPDATE`         | boolean | Disable automatic update checks                   |
 | `OPENCODE_DISABLE_PRUNE`              | boolean | Disable pruning of old data                       |
 | `OPENCODE_DISABLE_TERMINAL_TITLE`     | boolean | Disable automatic terminal title updates          |

packages/web/src/content/docs/config.mdx

@@ -142,6 +142,67 @@ opencode run "Hello world"
 
 The custom directory is loaded after the global config and `.opencode` directories, so it **can override** their settings.
 
+### Custom data directory
+
+Specify a custom data directory using the `OPENCODE_DATA_DIR`
+environment variable. This controls where OpenCode stores runtime data
+like authentication tokens, logs, cached files, and LSP binaries.
+
+```bash
+export OPENCODE_DATA_DIR=/path/to/my/data-directory
+opencode run "Hello world"
+```
+
+By default, OpenCode stores data in `~/.local/share/opencode` on Linux/macOS
+or `%LOCALAPPDATA%\opencode` on Windows.
+
+---
+
+### Custom cache directory
+
+Specify a custom cache directory using the `OPENCODE_CACHE_DIR`
+environment variable. This controls where OpenCode stores cached data
+like npm plugins and their dependencies.
+
+```bash
+export OPENCODE_CACHE_DIR=/path/to/my/cache-directory
+opencode run "Hello world"
+```
+
+By default, OpenCode stores cache in `~/.cache/opencode` on Linux/macOS
+or `%LOCALAPPDATA%\opencode` on Windows.
+
+---
+
+### Custom log directory
+
+Specify a custom log directory using the `OPENCODE_LOG_DIR`
+environment variable. This controls where OpenCode stores log files.
+
+```bash
+export OPENCODE_LOG_DIR=/path/to/my/log-directory
+opencode run "Hello world"
+```
+
+By default, OpenCode stores logs in the data directory at `$OPENCODE_DATA_DIR/log`
+(or `~/.local/share/opencode/log` if `OPENCODE_DATA_DIR` is not set).
+
+---
+
+### Custom state directory
+
+Specify a custom state directory using the `OPENCODE_STATE_DIR`
+environment variable. This controls where OpenCode stores UI state
+like model selection, prompt history, stashed prompts, and frecency data.
+
+```bash
+export OPENCODE_STATE_DIR=/path/to/my/state-directory
+opencode run "Hello world"
+```
+
+By default, OpenCode stores state in `~/.local/state/opencode` on Linux/macOS
+or `%LOCALAPPDATA%\opencode` on Windows.
+
 ---
 
 ## Schema

packages/web/src/content/docs/plugins.mdx

@@ -45,7 +45,7 @@ Browse available plugins in the [ecosystem](/docs/ecosystem#plugins).
 
 ### How plugins are installed
 
-**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in `~/.cache/opencode/node_modules/`.
+**npm plugins** are installed automatically using Bun at startup. Packages and their dependencies are cached in the cache directory (`~/.cache/opencode/node_modules/` by default, or `$OPENCODE_CACHE_DIR/node_modules/` if set).
 
 **Local plugins** are loaded directly from the plugin directory. To use external packages, you must create a `package.json` within your config directory (see [Dependencies](#dependencies)), or publish the plugin to npm and [add it to your config](/docs/config#plugins).
 

packages/web/src/content/docs/troubleshooting.mdx

@@ -259,7 +259,7 @@ To resolve provider package issues:
 1. Clear the provider package cache:
 
    ```bash
-   rm -rf ~/.cache/opencode
+   rm -rf ${OPENCODE_CACHE_DIR:-${HOME}/.cache/opencode}
    ```
 
    On Windows, press `WIN+R` and delete: `%USERPROFILE%\.cache\opencode`