Repository navigation
[FEATURE]: add environment variables for portable mode and profile isolation #8968
Description
Feature hasn't been suggested before.
- I have verified this feature I'm about to request hasn't been suggested before.
Describe the enhancement you want to request
Following up on issue #4526 and PR #8963. While moving the data directory is a great start, OpenCode still writes logs, state, and transient caches to fixed global system paths. This makes it difficult to run truly isolated instances.
Proposed Solution Add support for:
- OPENCODE_CACHE_DIR: For all transient state (indexes, caches, npm plugins).
- OPENCODE_LOG_DIR: For session logs.
- OPENCODE_STATE_DIR: For UI state (model selection, prompt history, stashed prompts, frecency data).
Why?
- Environment Hygiene: Prevents metadata leakage between different project contexts.
- Portability: Allows a user to wrap an entire environment (config, data, cache, logs, state) into a single path for easier backup or migration.
- Multi-instance Support: Running multiple OpenCode sessions with different identities/configs without path collisions in ~/.cache, /.local/share, or /.local/state.
EDIT:
I've extended PR #8963 to cover this also. The PR now includes all four environment variables:
- OPENCODE_DATA_DIR (original request from [FEATURE]: Full portable mode. #4526)
- OPENCODE_CACHE_DIR (added to address this issue)
- OPENCODE_LOG_DIR (added to address this issue)
- OPENCODE_STATE_DIR (added to address this issue)
With all five environment variables (OPENCODE_CONFIG_DIR, OPENCODE_DATA_DIR, OPENCODE_CACHE_DIR, OPENCODE_LOG_DIR, OPENCODE_STATE_DIR), OpenCode achieves full portable mode with zero reliance on default XDG directories.
Activity
github-actions commentedon Jan 16, 2026
This issue might be a duplicate of existing issues. Please check:
These issues are closely related to your feature request for OPENCODE_CACHE_DIR and OPENCODE_LOG_DIR. The combined solutions would provide the full isolation and portability you're describing.
Feel free to ignore if you believe this request addresses something more specific.
feat: add OPENCODE_CACHE_DIR env var for portable mode
feat: add OPENCODE_LOG_DIR env var for portable mode
thdxr commentedon Mar 25, 2026
To stay organized issues are automatically closed after 90 days of no activity. If the issue is still relevant please open a new one.
feat: add OPENCODE_APPNAME for profile isolation
docs: fix Windows default paths in config documentation
[-][FEATURE]: Support OPENCODE_CACHE_DIR and OPENCODE_LOG_DIR for full isolation[/-][+]feat: add directory override env vars and OPENCODE_APPNAME for portable mode and profile isolation[/+][-]feat: add directory override env vars and OPENCODE_APPNAME for portable mode and profile isolation[/-][+][FEATURE]: Support OPENCODE_CACHE_DIR and OPENCODE_LOG_DIR for full isolation[/+][-][FEATURE]: Support OPENCODE_CACHE_DIR and OPENCODE_LOG_DIR for full isolation[/-][+][FEATURE]: add environment variables for portable mode and profile isolation[/+]