docs: document Warp file locations across macOS/Windows/Linux#110
Merged
Conversation
Adds a new reference page that lays out every Warp config, data, and state path across all three platforms and both release channels, plus fixes related pages whose Windows/Linux paths were inaccurate or incomplete: - New: terminal/settings/file-locations covering data_dir, config_local_dir, state_dir, ~/.warp, ~/.agents, and the WSL symlink workflow Windows + WSL users actually need. - Tab Configs page now lists per-OS tab_configs directories instead of only showing the macOS path. - Custom Themes background_image note now points at the per-OS themes directory instead of just ~/.warp/themes. - Uninstall doc fixes a Linux XDG_STATE_HOME -> XDG_DATA_HOME typo for themes/launch configs, calls out ~/.warp on Windows, and corrects the Windows Preview path to WarpPreview. - Settings file overview cross-links the new reference page. - Sidebar adds the new page under the Settings file group. Co-Authored-By: Oz <oz-agent@warp.dev>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR adds a cross-platform reference for Warp file locations and updates existing pages to stop using macOS-only paths. I found accuracy issues in the new WSL/home-directory guidance that would send Windows+WSL users to the wrong locations.
Concerns
- The cross-platform carve-out incorrectly says Preview may use
~/.warp-<channel>/for MCP/skills even though Stable and Preview share~/.warp/for those files. - The WSL symlink commands assume
$USERmatches the Windows profile name, which is not reliable. - The WSL section says
~/.warp/and~/.agents/are already shared between Windows and WSL, but WSL$HOMEis separate from Windows%USERPROFILE%.
Verdict
Found: 0 critical, 3 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| * **Non-portable config** - Local-only configuration that doesn't make sense to roam, such as `settings.toml` and `keybindings.yaml`. | ||
| * **Non-portable state** - Machine-specific state like logs, the local database, and the Codebase Context index. | ||
|
|
||
| In addition, a small set of cross-cutting files always live under `~/.warp/` (or `~/.warp-<channel>/` on macOS Preview) on every platform — currently MCP server config and bundled skills. These intentionally sit in the home directory so they're easy to reference from shell config, version control, or other tools. |
Contributor
There was a problem hiding this comment.
~/.warp-<channel>/, but the source-backed paths below say Stable and Preview share ~/.warp/ for those files. Remove the Preview exception so users do not look in ~/.warp-preview for MCP config or skills.
Collaborator
Author
There was a problem hiding this comment.
Addressed in adb1dd6. Reworded the cross-cutting carve-out paragraph in file-locations.mdx to state explicitly that both Stable and Preview share ~/.warp/ for MCP config and skills, and that Preview does not use ~/.warp-preview/ for these files. Only channels like OSS use a suffixed directory (e.g. ~/.warp-oss/). Also added matching clarifications to each bullet in the Preview channel paths section (macOS, Windows, Linux) so the same point is reinforced wherever a reader lands.
|
|
||
| ```bash | ||
| # Portable data: themes, tab configs, workflows, launch configurations. | ||
| ln -s "/mnt/c/Users/$USER/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data |
Contributor
There was a problem hiding this comment.
$USER is the Linux account name, which often differs from the Windows profile directory, so this can create a symlink to a path that does not exist. Resolve %USERPROFILE% through Windows and convert it with wslpath, or tell users to replace the Windows user name explicitly.
Collaborator
Author
There was a problem hiding this comment.
Addressed in adb1dd6. Rewrote the WSL section in file-locations.mdx so the primary approach now resolves the Windows profile path through cmd.exe and converts it with wslpath:
WIN_HOME=$(wslpath "$(cmd.exe /C 'echo %USERPROFILE%' 2>/dev/null | tr -d '\r')")
ln -s "$WIN_HOME/AppData/Roaming/warp/Warp/data" ~/.warp-windows-data
# ...etcThis avoids the original WIN_USER=YourWindowsUserName step and the implicit assumption that the WSL $USER matches the Windows profile name. The hard-coded fallback (/mnt/c/Users/<your-windows-username>) is still mentioned at the bottom for users who would rather not pipe through cmd.exe.
| ln -s "/mnt/c/Users/$USER/AppData/Local/warp/Warp/config" ~/.warp-windows-config | ||
| ``` | ||
|
|
||
| `~/.warp/` (MCP config, skills) and `~/.agents/` are already shared because both Windows and WSL use the same user home directory layout for those files. |
Contributor
There was a problem hiding this comment.
$HOME is separate from Windows %USERPROFILE%, so ~/.warp/ and ~/.agents/ are not automatically shared. If users need WSL tools to read Windows-side MCP or agent config, document separate links to the Windows profile paths instead.
Collaborator
Author
There was a problem hiding this comment.
Addressed in adb1dd6. Rewrote the intro of the WSL section to call this out explicitly:
WSL
$HOME(typically/home/<wsl-user>/) is a separate Linux filesystem from your Windows profile (%USERPROFILE%, typicallyC:\Users\<Windows-user>\), so~/.warp/and~/.agents/inside WSL are not automatically the same as the Windows-side directories with those names — every Warp directory you want to share needs its own symlink that points back to the Windows path.
The symlinks below it then point the WSL-side ~/.warp and ~/.agents at the Windows-side $WIN_HOME/.warp and $WIN_HOME/.agents (where $WIN_HOME is resolved from %USERPROFILE% via wslpath), which is the "separate links to the Windows profile paths" pattern you suggested.
- Drop the inaccurate 'or ~/.warp-<channel>/ on macOS Preview' note from the cross-platform carve-out: Stable and Preview both use ~/.warp/ for MCP config and bundled skills per warp_home_config_dir_name() in warp_core/src/paths.rs. Other channels (OSS, Dev, etc.) get a suffix. - Rework the WSL symlink section: WSL $HOME is separate from Windows %USERPROFILE%, so ~/.warp/ and ~/.agents/ are not shared automatically. Use a WIN_USER variable instead of $USER (the WSL Linux account name, often different from the Windows profile), and document additional symlinks for ~/.warp and ~/.agents so users can share them too. Co-Authored-By: Oz <oz-agent@warp.dev>
Member
Windows Preview Registry key is incorrect pathThe Registry key for Warp Preview on Windows is documented as Why:
Fix 1 —
|
dannyneira
approved these changes
May 19, 2026
Member
dannyneira
left a comment
dannyneira
left a comment
There was a problem hiding this comment.
approving to unblock, with comments on a needed fix
… WSL setup Addresses review feedback on PR #110: - Fix the Windows Preview Registry key in two places: it is HKCU:\\Software\\Warp.dev\\WarpPreview (no hyphen). The hyphenated Warp-Preview form is the macOS bundle identifier (dev.warp.Warp-Preview), not the Windows app name. Confirmed against script/windows/bundle.ps1 ($APP_NAME = 'WarpPreview') and registry_backed.rs (Software\\Warp.dev\\<app_name>). - Reword the cross-cutting carve-out paragraph in file-locations.mdx so it states explicitly that both Stable and Preview share ~/.warp/ for MCP config and skills, and only channels like OSS use a suffixed directory. - Rewrite the WSL section to promote wslpath + %USERPROFILE% resolution as the primary approach (instead of hard-coding the Windows username) and call out that WSL $HOME is a separate Linux filesystem from %USERPROFILE%, so ~/.warp and ~/.agents on the WSL side are not automatically the same as their Windows-side counterparts. Co-Authored-By: Oz <oz-agent@warp.dev>
Collaborator
Author
|
Thanks for catching this! Fixed in adb1dd6:
Verified against |
hongyi-chen
added a commit
that referenced
this pull request
May 21, 2026
…remove preview-period notes, restore File locations sidebar - Restore the 'File locations' sidebar entry under Settings file (added on main by PR #110, accidentally dropped during the rebase). - Drop the 'CIE' abbreviation throughout the customer-supplied inference pages. Use the full name 'custom inference endpoint' (or 'your endpoint' / 'endpoint-routed model' in context) instead. - Narrow the 'never consumes Warp credits' claim to 'doesn't consume AI credits' on the BYOK and custom inference endpoint pages, since Business / Enterprise local agent runs still consume platform credits. - Rewrite the 'No Warp credits consumed' Key features bullet on the custom inference endpoint page so it accurately calls out the platform-credits caveat on Business / Enterprise. - Drop the 'Self-serve preview period' paragraph from the platform-credits :::note callouts on the BYOK and custom inference endpoint pages. The July 1, 2026 cutover lives only in pricing-faqs.mdx now \u2014 canonical feature pages don't carry the launch-period detail. Co-Authored-By: Oz <oz-agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
May 21, 2026
…LLM) (#115) * docs(pricing-may-2026): customer-supplied inference (BYOK + CIE + BYOLLM) Part of the May 14, 2026 pricing-and-packaging docs launch. - BYOK is now available on the Free plan; page rewritten to open eligibility, refresh model examples, and add the BYOK/CIE/BYOLLM comparison table. - New Custom Inference Endpoint (CIE) page for OpenAI Chat Completions– compatible endpoints (OpenRouter, LiteLLM, z.ai, internal gateways). Sidebar entry added under Plans and billing. - BYOLLM reframed as Enterprise-only managed inference. AWS Bedrock GA; Google Vertex AI and Azure AI Foundry on the roadmap. Cloud-native credentials now span IAM/OIDC across all three cloud providers. - 10-employee org rule applies to BYOK and CIE; larger orgs need Business or Enterprise. - Platform-credits caveats: on Business/Enterprise local agent runs, customer-supplied inference still consumes platform credits even though no AI credits are charged. - plans-and-billing/index.mdx updated to surface the new CIE page. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): note July 1 self-serve preview period in BYOK + CIE platform-credits callouts Both BYOK and CIE pages now spell out that self-serve billing for platform credits (including Business BYOK / CIE) doesn't start until July 1, 2026. Between May 14 and June 30, 2026, platform-credit consumption is visible in the Warp app's usage breakdown for transparency on Build, Max, and Business, but no platform credits are deducted from your Reload pool or counted against your spend cap. Enterprise plans are billed per contract from May 14 and aren't affected by this preview period. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): correct launch date May 14 \u2192 May 21, 2026 Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): revert BYOLLM page to main, keep changes minimal Per launch direction: keep the Enterprise BYOLLM page largely unchanged for this launch. The BYOK/CIE/BYOLLM comparison still lives on the BYOK and CIE pages, so readers landing on either of those will see the three-way framing. This restores: - The original AWS-Bedrock-focused frontmatter description and opening paragraph (instead of the cross-provider reframing). - The original 'BYOLLM currently supports AWS Bedrock only. Coming soon: Azure Foundry and Google Vertex support.' caveat. - The original 'Cloud-native credentials - Authenticate using each user's AWS IAM identity' key feature. - The original 'How is BYOLLM different from BYOK?' FAQ with its 4-row comparison table. - The original Related resources list. Drops the launch-era additions: - The 'How BYOLLM differs from BYOK and Custom inference endpoint' section with the three-way comparison table. - The :::note about centrally configured BYOK / CIE for Enterprise being a fast-follow. - The :::note about platform credits for BYOLLM-routed local runs. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): drop CIE abbreviation, narrow credit claims, remove preview-period notes, restore File locations sidebar - Restore the 'File locations' sidebar entry under Settings file (added on main by PR #110, accidentally dropped during the rebase). - Drop the 'CIE' abbreviation throughout the customer-supplied inference pages. Use the full name 'custom inference endpoint' (or 'your endpoint' / 'endpoint-routed model' in context) instead. - Narrow the 'never consumes Warp credits' claim to 'doesn't consume AI credits' on the BYOK and custom inference endpoint pages, since Business / Enterprise local agent runs still consume platform credits. - Rewrite the 'No Warp credits consumed' Key features bullet on the custom inference endpoint page so it accurately calls out the platform-credits caveat on Business / Enterprise. - Drop the 'Self-serve preview period' paragraph from the platform-credits :::note callouts on the BYOK and custom inference endpoint pages. The July 1, 2026 cutover lives only in pricing-faqs.mdx now \u2014 canonical feature pages don't carry the launch-period detail. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): de-emphasize billing in BYOK + custom inference endpoint openings, consolidate plan notes - Reframe the BYOK and custom inference endpoint opening copy around model selection and data routing instead of billing. Move the AI-credits-consumption details out of the intro and down into the dedicated billing sections where they belong. - Collapse the two stacked :::note callouts about plan availability and the 10-or-fewer-employees rule into a single, briefer note on each page. - Move the Business / Enterprise platform-credits caveat off the top of the BYOK page and into the 'Credit usage' subsection alongside the related credit details. - Trim the 'BYOK on Enterprise and Business plans' section on the BYOK page so it doesn't restate the org-size rule already covered up top. - Replace the redundant 'Plan availability' section on the custom inference endpoint page with a focused 'Centrally managed configuration' section that only covers what's still unique to that page (user-level config today, admin-managed coming later).\n - Light copy polish on phrasing in both files. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): restore original BYOK opening, narrow only the credits claim to AI credits Per follow-up review, undo the polish on the BYOK intro and restore the original three-paragraph opening verbatim: - Title back to 'Bring Your Own API Key' (Title Case) - 'Warp supports Bring Your Own Key (BYOK) for users who want to connect Warp's agents to their own Anthropic, OpenAI, or Google API accounts.' - 'This lets you use your own API keys to access models directly, giving you full control over model selection, billing, and data routing. See Model Choice for a list of supported models.' - 'BYOK provides greater flexibility in model access and ensures Warp never consumes your AI credits for requests routed through your own keys.' The only substantive change vs the original is narrowing 'credits' to 'AI credits' in that last sentence, per earlier feedback that the unqualified 'never consumes Warp credits' claim is too broad now that Business / Enterprise local runs can consume platform credits. The combined plan-availability + 10-employee :::note below the intro stays as-is. Everything below the intro (BYOK works, Enabling BYOK, billing behavior, Credit usage with the platform-credits note, ZDR, Enterprise/Business config, Related resources) is unchanged. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): soften absolute 'no AI credits / 0 credits' claims in BYOK + CIE credit sections - Drop the 'No AI credits are consumed' bullet and the 'credit transparency footer shows 0 credits used' sentence from BYOK's Credit usage subsection. Replaced with a more general framing that says inference is billed through your provider account rather than drawing from your Warp AI credits, alongside the existing platform credits caveat for Business / Enterprise. - Same softening on the custom inference endpoint page's Warp AI credits subsection \u2014 collapse the three firm bullets into one general sentence and keep the platform-credits note. This avoids the misleadingly absolute '0 credits' claim, which is inaccurate for Business / Enterprise local runs where platform credits can still apply. Co-Authored-By: Oz <oz-agent@warp.dev> * docs(pricing-may-2026): reframe custom inference endpoint intro to lead with powering Warp's agents Mirror the BYOK page's intro pattern so it's explicit upfront that a custom inference endpoint is used to power Warp's agents. New opening: Warp supports custom inference endpoints for users who want to power Warp's agents with any OpenAI-compatible inference endpoint \u2014 a model router, hosted gateway, or internal infrastructure they already run. This lets you route AI requests through your preferred provider, run inference behind your own gateway, or use a router like OpenRouter or LiteLLM, while keeping the agent experience inside Warp. No other changes. Co-Authored-By: Oz <oz-agent@warp.dev> * Cleanup pass: BYOK acronym + BYOLLM table scope - bring-your-own-api-key.mdx intro: fix the wrong BYOK expansion ('Bring Your Own Key (BYOK)') to match the page title and standard usage ('Bring Your Own API Key (BYOK)'). - bring-your-own-api-key.mdx + custom-inference-endpoint.mdx comparison tables: tighten the BYOLLM row so it reflects current launch scope ('AWS Bedrock today; Azure Foundry and Google Vertex coming soon') instead of implying all three ship at launch. Co-Authored-By: Oz <oz-agent@warp.dev> * PR #115 review: address Tyler's comments - bring-your-own-api-key.mdx 'Platform credits' note: Tyler correctly pointed out that platform credits also apply for cloud agent runs. Rewrite the line to lead with the cloud-agent case ('apply to every cloud agent run on any plan') and then cover the local-runs case ('and to local agent runs on Business and Enterprise when using BYOK, a custom inference endpoint, or BYOLLM'). - bring-your-own-api-key.mdx 'How BYOK works' opening: drop the misleading 'directly to the model provider' phrasing since requests still flow through Warp's infrastructure. Now reads 'Warp uses these API keys when routing your agent requests to the model provider you've configured.' Tyler's third comment was a stylistic preference for 'need' over 'require' on the page note, which already uses 'need' here. The parallel 'require' phrasing in pricing-faqs.mdx will be normalized on PR #116. Co-Authored-By: Oz <oz-agent@warp.dev> --------- Co-authored-by: Oz <oz-agent@warp.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds documentation that covers where Warp stores files on each platform, motivated by customer feedback that Warp's Windows config layout is undocumented and that
docs.warp.dev/terminal/windows/tab-configs/references the macOS-only~/.warp/tab_configs/path. Filed concurrently as warpdotdev/warp#11356.What's in this PR
New page:
terminal/settings/file-locationsSingle reference that lists every directory and file Warp reads or writes on disk, organized into three buckets (portable user data, non-portable config, non-portable state) plus the cross-platform
~/.warp/carve-out. Covers macOS, Windows, and Linux for both Stable and Preview channels, and includes a "Symlinking Warp's config from WSL" section for users running Warp on Windows alongside WSL — the exact workflow the original customer feedback called out.Sidebar entry added under Terminal → Settings file, after All settings reference.
Updates to existing pages
terminal/windows/tab-configs.mdx— replaces the bare~/.warp/tab_configs/mention with a per-OS Tabs block (macOS / Windows / Linux for both Stable and Preview), and links to the new reference page.terminal/appearance/custom-themes.mdx— fixes thebackground_image: path:YAML note to call out the per-OS themes directory instead of only the macOS path.terminal/settings/index.mdx— cross-links the new reference page from the File location section and Related pages.support-and-community/troubleshooting-and-support/logging-out-and-uninstalling.mdx:XDG_STATE_HOME→XDG_DATA_HOMEfor themes/launch configs (the variable was wrong; the fallback path happened to land in the right place).\warp\Warp-Preview\to\warp\WarpPreview\(verified againstdirectories::ProjectDirsbehavior withapplication_name = "WarpPreview"and confirmed by warp_core tests).~/.warpremoval on Windows and Linux (MCP config and skills live in the home directory on every platform).src/sidebar.ts— adds the new page to the Settings file group.How the paths were verified
Paths in this PR were validated against
warp-internalsource rather than inferred from the docs:warp_core::paths::data_dir,config_local_dir,state_dir,cache_dir, and thewarp_home_*helpers inwarp-internal/crates/warp_core/src/paths.rs.paths_tests.rscases that assert the exact Windows project path iswarp\Warp(Stable),warp\WarpPreview(Preview), andwarp\WarpOss(OSS), withcache_dir=AppData\Local\warp\WarpOss\cacheandstate_dir=AppData\Local\warp\WarpOss\data.app/src/user_config/mod.rs(themes, tab_configs, default_tab_configs, launch_configurations, workflows all live underdata_dir()).app/src/keyboard.rs(keybindings.yaml atconfig_local_dir().join("keybindings.yaml")).feedbackskill'sreferences/logs.mdfor log paths.Validation
python3 .agents/skills/check_for_broken_links/check_links.py --internal-only→ 0 broken links across 2586 internal links / 331 files.python3 .agents/skills/style_lint/style_lint.py --changed→ no new issues introduced by this PR. The 6 warnings it surfaces are all on pre-existing lines I didn't touch (the "Tab Configs" headers — a proper Warp feature name explicitly exempted byAGENTS.md— and asettings.tomlfilename reference flagged as a UI element).Conversation: https://staging.warp.dev/conversation/4d92f7ea-4b06-4887-81a2-2441323b14fb
Run: https://oz.staging.warp.dev/runs/019e4250-e3ba-7642-bc98-74b891ed569c
This PR was generated with Oz.