Desktop application changeddesktop
Nearest release: v2.1.304, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 19 Oct 2026 19:44 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+351added
Lines−407removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits79to this page, all time
#### Auto mode availability
The whole hunk
from line 4, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 4
44
55The Claude Desktop app has three tabs: **Chat** for conversations, **Cowork** for [Dispatch and longer agentic work](https://claude.com/product/cowork), and **Code** for software development. This page is the reference for the Code tab.
66
7<CardGroup cols={3}>
8 <Card title="Download for macOS" icon="apple" href="https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code&utm_medium=docs">
9 Universal build for Intel and Apple Silicon
10 </Card>
11
12 <Card title="Download for Windows" icon="windows" href="https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code&utm_medium=docs">
13 For x64 processors
14 </Card>
15
16 <Card title="Get Claude for Linux (beta)" icon="linux" href="/docs/en/desktop-linux">
17 apt or .deb for Ubuntu and Debian
18 </Card>
19</CardGroup>
7> **[Download for macOS](https://claude.ai/api/desktop/darwin/universal/dmg/latest/redirect?utm_source=claude_code\&utm_medium=docs)**
8>
9> Universal build for Intel and Apple Silicon
10
11> **[Download for Windows](https://claude.ai/api/desktop/win32/x64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs)**
12>
13> For x64 processors
14
15> **[Get Claude for Linux (beta)](/docs/en/desktop-linux)**
16>
17> apt or .deb for Ubuntu and Debian
2018
2119For Windows ARM64, download the [ARM64 installer](https://claude.ai/api/desktop/win32/arm64/setup/latest/redirect?utm_source=claude_code\&utm_medium=docs). On Linux, install with apt; see [Claude Desktop on Linux](/docs/en/desktop-linux).
2220
from line 94
9694
9795The `dontAsk` permission mode is available only in the [CLI](/docs/en/permission-modes#allow-only-pre-approved-tools-with-dontask-mode).
9896
99<Tip title="Best practice">
100 Start complex tasks in Plan so Claude maps out an approach before making changes. Once you approve the plan, switch to Accept edits or Manual to execute it. See [explore first, then plan, then code](/docs/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.
101</Tip>
97> [!TIP]
98>
99> Start complex tasks in Plan so Claude maps out an approach before making changes. Once you approve the plan, switch to Accept edits or Manual to execute it. See [explore first, then plan, then code](/docs/en/best-practices#explore-first-then-plan-then-code) for more on this workflow.
102100
103101Cloud sessions support Accept edits, Plan, and Auto. Accept edits corresponds to `default` mode: cloud sessions pre-approve file edits, so the selector shows Accept edits instead of Manual. Bypass permissions isn't available in cloud sessions, including sessions in a [self-hosted environment](/docs/en/self-hosted-environments).
104102
105103Enterprise admins can restrict which permission modes are available. See [enterprise configuration](#enterprise-configuration) for details.
106104
107<h4 id="auto-mode-availability">
108 Auto mode availability
109</h4>
105#### Auto mode availability
110106
111107Auto mode is available to all users on the Anthropic API and requires Claude Opus 4.6 or later, Sonnet 4.6 or later, Haiku 5.5, or a [Fable model](/docs/en/model-config#work-with-fable). Organization administrators can turn auto mode off with the `disableAutoMode` key in [managed settings](#managed-settings).
112108
from line 114
118114
119115In a local session, click an HTML, PDF, or video path in the chat to open it in the Browser pane.
120116
121<Note>
122 In an [SSH session](#ssh-sessions), Claude can't open your app in the Browser pane, because it doesn't have the pane's tools there. To look at the app yourself, [forward its port to your computer](#reach-a-port-on-the-remote-machine).
123</Note>
117> [!NOTE]
118>
119> In an [SSH session](#ssh-sessions), Claude can't open your app in the Browser pane, because it doesn't have the pane's tools there. To look at the app yourself, [forward its port to your computer](#reach-a-port-on-the-remote-machine).
124120
125121If the Browser pane isn't open after Claude starts a server in a local session, click **Open** on the server's card in the chat.
126122
from line 192
196192
197193To archive the session automatically once the PR merges or closes, turn on [auto-archive](#archive-a-session) in **Settings > Claude Code**.
198194
199<Note>
200 PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.
201
202 In an [SSH session](#ssh-sessions), set up `git` and `gh` on the remote machine before you click **Create PR**, because Claude pushes the branch and runs `gh pr create` there. Install `gh` there yourself, because Desktop doesn't prompt you to in an SSH session. Then check there that `git push` works and that `gh auth status` reports that you are logged in.
203</Note>
195> [!NOTE]
196>
197> PR monitoring requires the [GitHub CLI (`gh`)](https://cli.github.com/) to be installed and authenticated on your machine. If `gh` is not installed, Desktop prompts you to install it the first time you try to create a PR.
198>
199> In an [SSH session](#ssh-sessions), set up `git` and `gh` on the remote machine before you click **Create PR**, because Claude pushes the branch and runs `gh pr create` there. Install `gh` there yourself, because Desktop doesn't prompt you to in an SSH session. Then check there that `git push` works and that `gh auth status` reports that you are logged in.
204200
205201## Arrange your workspace
206202
from line 204
208204
209205To work across screens, pop a pane such as the diff or terminal out into its own window, and dock it back when you're done. Claude keeps working in the main window.
210206
211<Note>
212 The pane layout, terminal, file editor, and view modes in this section require Claude Desktop v1.2581.0 or later. Open **Claude > Check for Updates…** on macOS or **Help > Check for Updates…** on Windows to update.
213</Note>
207> [!NOTE]
208>
209> The pane layout, terminal, file editor, and view modes in this section require Claude Desktop v1.2581.0 or later. Open **Claude > Check for Updates…** on macOS or **Help > Check for Updates…** on Windows to update.
214210
215211### See session details
216212
from line 300
304300
305301Computer use lets Claude open your apps, control your screen, and work directly on your machine the way you would. Ask Claude to interact with a desktop tool that has no CLI, or automate something that only works through a GUI. For running and testing iOS apps, Desktop opens the dedicated [iOS Simulator pane](/docs/en/desktop-ios-simulator) instead of controlling your screen; the pane works without enabling computer use.
306302
307<Note>
308 Computer use is a research preview on macOS and Windows that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running.
309</Note>
303> [!NOTE]
304>
305> Computer use is a research preview on macOS and Windows that requires a Pro or Max plan. It is not available on Team or Enterprise plans. The Claude Desktop app must be running.
310306
311307Computer use is off by default. [Enable it in Settings](#enable-computer-use) before Claude can control your screen. On macOS, you also need to grant Accessibility and Screen Recording permissions.
312308
313309On macOS, computer use can also run in the background: Claude works in the apps you've approved while you keep working.
314310
315<Warning>
316 Unlike the [sandboxed Bash tool](/docs/en/sandboxing), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.
317</Warning>
311> [!WARNING]
312>
313> Unlike the [sandboxed Bash tool](/docs/en/sandboxing), computer use runs on your actual desktop with access to whatever you approve. Claude checks each action and flags potential prompt injection from on-screen content, but the trust boundary is different. See the [computer use safety guide](https://support.claude.com/en/articles/14128542) for best practices.
318314
319315### When computer use applies
320316
from line 328
332328
333329Computer use is off by default. If you ask Claude to do something that needs it while it's off, Claude tells you it could do the task if you enable computer use in Settings.
334330
335<Steps>
336 <Step title="Update the desktop app">
337 Make sure you have the latest version of Claude Desktop. On macOS and Windows, download or update at [claude.com/download](https://claude.com/download); on Linux, update through your package manager ([instructions](/docs/en/desktop-linux)). Then restart the app.
338 </Step>
339
340 <Step title="Turn on the toggle">
341 In the desktop app, go to **Settings > This computer > System**. Under **Computer use**, turn on **Enable computer use**. On Windows, the toggle takes effect immediately and setup is complete. On macOS, continue to the next step.
342
343 If you don't see the toggle, confirm you're on macOS or Windows with a Pro or Max plan, then update and restart the app.
344 </Step>
345
346 <Step title="Grant macOS permissions">
347 On macOS, grant two system permissions before the toggle takes effect:
348
349 * **Accessibility**: lets Claude click, type, and scroll
350 * **Screen Recording**: lets Claude see what's on your screen
351
352 The Settings page shows the current status of each permission. If either is denied, click the badge to open the relevant System Settings pane.
353 </Step>
354</Steps>
331**1. Update the desktop app**
332
333Make sure you have the latest version of Claude Desktop. On macOS and Windows, download or update at [claude.com/download](https://claude.com/download); on Linux, update through your package manager ([instructions](/docs/en/desktop-linux)). Then restart the app.
334
335**2. Turn on the toggle**
336
337In the desktop app, go to **Settings > This computer > System**. Under **Computer use**, turn on **Enable computer use**. On Windows, the toggle takes effect immediately and setup is complete. On macOS, continue to the next step.
338
339If you don't see the toggle, confirm you're on macOS or Windows with a Pro or Max plan, then update and restart the app.
340
341**3. Grant macOS permissions**
342
343On macOS, grant two system permissions before the toggle takes effect:
344
345* **Accessibility**: lets Claude click, type, and scroll
346* **Screen Recording**: lets Claude see what's on your screen
347
348The Settings page shows the current status of each permission. If either is denied, click the badge to open the relevant System Settings pane.
355349
356350### App permissions
357351
from line 392
398392
399393To include gitignored files like `.env` in new worktrees, create a [`.worktreeinclude` file](/docs/en/worktrees#copy-gitignored-files-into-worktrees) in your project root. See [What worktrees share with the main checkout](/docs/en/worktrees#what-worktrees-share-with-the-main-checkout) for where a worktree session reads project settings, hooks, and skills.
400394
401<Note>
402 Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check; if it prints a version number, Git is installed. If you run into Git errors, ask Claude in the [Cowork tab](https://claude.com/product/cowork) to help troubleshoot your setup.
403</Note>
395> [!NOTE]
396>
397> Session isolation requires [Git](https://git-scm.com/downloads). Most Macs include Git by default. Run `git --version` in Terminal to check; if it prints a version number, Git is installed. If you run into Git errors, ask Claude in the [Cowork tab](https://claude.com/product/cowork) to help troubleshoot your setup.
404398
405399### Add folders to a session
406400
from line 478
484478
485479See [Use Claude Code in the cloud](/docs/en/claude-code-on-the-web) for more on how cloud sessions work. When one body of work needs many cloud sessions, select **Projects** in the sidebar to create a [project](/docs/en/claude-projects), where Claude starts and tracks the sessions for you from one conversation.
486480
487<Note>
488 A task in an [SSH session](#ssh-sessions) can also [keep going while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.
489</Note>
481> [!NOTE]
482>
483> A task in an [SSH session](#ssh-sessions) can also [keep going while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected), but with a Claude account it can stop when its sign-in expires.
490484
491485### Continue in another surface
492486
from line 534
540534
541535Click **+** next to the prompt box, before or during the session, to add connectors in a local or [SSH](#ssh-sessions) session with a Claude account. Select **Add connectors** to open the connector directory. If the menu shows **Connectors** instead, select it, then **Browse connectors**.
542536
543<Note>
544 These cases are covered on other pages:
545
546 * **Connectors is grayed out in a WSL session**: see [If the terminal or connectors are unavailable](/docs/en/desktop-wsl#check-for-the-terminal-and-connectors)
547 * **Cloud sessions**: see [How connectors reach Claude Code](/docs/en/mcp#how-connectors-reach-claude-code)
548</Note>
537> [!NOTE]
538>
539> These cases are covered on other pages:
540>
541> * **Connectors is grayed out in a WSL session**: see [If the terminal or connectors are unavailable](/docs/en/desktop-wsl#check-for-the-terminal-and-connectors)
542> * **Cloud sessions**: see [How connectors reach Claude Code](/docs/en/mcp#how-connectors-reach-claude-code)
549543
550544Once connected, Claude can read your calendar, send messages, create issues, and interact with your tools directly. You can ask Claude what connectors are configured in your session. To manage or disconnect connectors, go to **Settings > Connectors** in the desktop app.
551545
from line 627
633627| `args` | string\[] | Arguments passed to `program`. Only used when `program` is set |
634628| `url` | string | The address the preview opens instead of `http://localhost:<port>`. See [open the preview at a specific URL](#open-the-preview-at-a-specific-url) |
635629
636<a id="when-to-use-program-vs-runtimeexecutable" />
637
638630##### When to use `program` vs `runtimeExecutable`
639631
640632Use `runtimeExecutable` with `runtimeArgs` to start a dev server through a package manager. For example, `"runtimeExecutable": "npm"` with `"runtimeArgs": ["run", "dev"]` runs `npm run dev`.
641633
642634Use `program` when you have a standalone script you want to run with `node` directly. For example, `"program": "server.js"` runs `node server.js`. Pass additional flags with `args`.
643
644<a id="open-the-preview-at-a-specific-url" />
645635
646636##### Open the preview at a specific URL
647637
from line 694
704694
705695These configurations show common setups for different project types:
706696
707<Tabs>
708 <Tab title="Next.js">
709 This configuration runs a Next.js app using Yarn on port 3000:
710
711 ```json theme={null}
697**Next.js**
698
699This configuration runs a Next.js app using Yarn on port 3000:
700
701```json theme={null}
702{
703 "version": "0.0.1",
704 "configurations": [
712705 {
713 "version": "0.0.1",
714 "configurations": [
715 {
716 "name": "web",
717 "runtimeExecutable": "yarn",
718 "runtimeArgs": ["dev"],
719 "port": 3000
720 }
721 ]
706 "name": "web",
707 "runtimeExecutable": "yarn",
708 "runtimeArgs": ["dev"],
709 "port": 3000
722710 }
723 ```
724 </Tab>
725
726 <Tab title="Multiple servers">
727 For a monorepo with a frontend and an API server, define multiple configurations. The frontend uses `autoPort: true` so it picks a free port if 3000 is taken, while the API server requires port 8080 exactly:
728
729 ```json theme={null}
711 ]
712}
713```
714
715**Multiple servers**
716
717For a monorepo with a frontend and an API server, define multiple configurations. The frontend uses `autoPort: true` so it picks a free port if 3000 is taken, while the API server requires port 8080 exactly:
718
719```json theme={null}
720{
721 "version": "0.0.1",
722 "configurations": [
730723 {
731 "version": "0.0.1",
732 "configurations": [
733 {
734 "name": "frontend",
735 "runtimeExecutable": "npm",
736 "runtimeArgs": ["run", "dev"],
737 "cwd": "apps/web",
738 "port": 3000,
739 "autoPort": true
740 },
741 {
742 "name": "api",
743 "runtimeExecutable": "npm",
744 "runtimeArgs": ["run", "start"],
745 "cwd": "server",
746 "port": 8080,
747 "env": { "NODE_ENV": "development" },
748 "autoPort": false
749 }
750 ]
724 "name": "frontend",
725 "runtimeExecutable": "npm",
726 "runtimeArgs": ["run", "dev"],
727 "cwd": "apps/web",
728 "port": 3000,
729 "autoPort": true
730 },
731 {
732 "name": "api",
733 "runtimeExecutable": "npm",
734 "runtimeArgs": ["run", "start"],
735 "cwd": "server",
736 "port": 8080,
737 "env": { "NODE_ENV": "development" },
738 "autoPort": false
751739 }
752 ```
753 </Tab>
754
755 <Tab title="Node.js script">
756 To run a Node.js script directly instead of using a package manager command, use the `program` field:
757
758 ```json theme={null}
740 ]
741}
742```
743
744**Node.js script**
745
746To run a Node.js script directly instead of using a package manager command, use the `program` field:
747
748```json theme={null}
749{
750 "version": "0.0.1",
751 "configurations": [
759752 {
760 "version": "0.0.1",
761 "configurations": [
762 {
763 "name": "server",
764 "program": "server.js",
765 "args": ["--verbose"],
766 "port": 4000
767 }
768 ]
753 "name": "server",
754 "program": "server.js",
755 "args": ["--verbose"],
756 "port": 4000
769757 }
770 ```
771 </Tab>
772</Tabs>
758 ]
759}
760```
773761
774762## Environment configuration
775763
from line 772
784772
785773A saved environment is an entry in the [environment selector](#start-a-session) that records where Claude runs, so you can start later sessions there. A local or SSH environment also holds the folders Claude works in. Saved local and SSH environments [require Claude Desktop v2.37337.0 or later](#check-which-layout-you-have).
786774
787<Steps>
788 <Step title="Open the New environment dialog">
789 Open the environment selector under the prompt box and select **New environment** at the bottom of its menu.
790 </Step>
791
792 <Step title="Choose where Claude runs">
793 Select the **Local**, **SSH**, or [**Cloud**](#cloud-sessions) tab and fill in the form on that tab. On the **SSH** tab, choose a [connection](#ssh-sessions) and a folder on the remote machine.
794 </Step>
795
796 <Step title="Save the environment">
797 Select **Create environment**, or **Add environment** on the **Cloud** tab.
798 </Step>
799</Steps>
775**1. Open the New environment dialog**
776
777Open the environment selector under the prompt box and select **New environment** at the bottom of its menu.
778
779**2. Choose where Claude runs**
780
781Select the **Local**, **SSH**, or [**Cloud**](#cloud-sessions) tab and fill in the form on that tab. On the **SSH** tab, choose a [connection](#ssh-sessions) and a folder on the remote machine.
782
783**3. Save the environment**
784
785Select **Create environment**, or **Add environment** on the **Cloud** tab.
800786
801787#### Environments that Desktop creates for you
802788
from line 804
818804
819805Add the variables to a saved local environment and start your sessions from it. Desktop [sets some variables itself](#environment-variables-desktop-sets-itself), such as `API_TIMEOUT_MS`, and your sessions get its value for those instead of yours.
820806
821<Note>
822 If your environment selector is above the prompt box, you have the [earlier layout](#check-which-layout-you-have), which has no saved local environments. Use the [local environment editor](#use-the-local-environment-editor) instead.
823</Note>
824
825<Steps>
826 <Step title="Open the environment's form">
827 Open [**New environment**](#create-a-saved-environment) or [**Edit environment**](#use-edit-or-remove-a-saved-environment).
828 </Step>
829
830 <Step title="Enter the variables">
831 Select **Environment variables**, enter one `KEY=value` per line, and select **Done**.
832 </Step>
833
834 <Step title="Save the environment">
835 Select **Create environment** or **Save**.
836 </Step>
837</Steps>
807> [!NOTE]
808>
809> If your environment selector is above the prompt box, you have the [earlier layout](#check-which-layout-you-have), which has no saved local environments. Use the [local environment editor](#use-the-local-environment-editor) instead.
810
811**1. Open the environment's form**
812
813Open [**New environment**](#create-a-saved-environment) or [**Edit environment**](#use-edit-or-remove-a-saved-environment).
814
815**2. Enter the variables**
816
817Select **Environment variables**, enter one `KEY=value` per line, and select **Done**.
818
819**3. Save the environment**
820
821Select **Create environment** or **Save**.
838822
839823Only sessions you start from that environment get the variables.
840824
from line 881
897881
898882SSH sessions let you run Claude Code on a remote machine while using the desktop app as your interface. This is useful for working with codebases that live on cloud VMs, dev containers, or servers with specific hardware or dependencies.
899883
900<Note>
901 If you use Desktop with a [third-party provider](/docs/en/third-party-integrations), SSH sessions need their own setup. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
902</Note>
884> [!NOTE]
885>
886> If you use Desktop with a [third-party provider](/docs/en/third-party-integrations), SSH sessions need their own setup. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
903887
904888Add an SSH connection in the [**New environment** dialog](#create-a-saved-environment), then start a session on that connection. If a new session has no environment selector under the prompt box, you have the earlier layout. See [Check which layout you have](#check-which-layout-you-have).
905889
906<Steps>
907 <Step title="Open the New environment dialog">
908 Before you start a session, open the environment selector under the prompt box and select **New environment** at the bottom of its menu.
909 </Step>
910
911 <Step title="Add the connection">
912 On the **SSH** tab of the **New environment** dialog, open the **Host** list, select **Add SSH connection…**, and fill in the connection details:
913
914 * **Name**: a friendly label for this connection.
915 * **SSH host**: `user@hostname` or a host defined in `~/.ssh/config`.
916 * **SSH port**: defaults to 22 if left empty, or uses the port from your SSH config.
917 * **SSH key (optional)**: path to your private key, such as `~/.ssh/id_ed25519`. Leave empty to use your SSH config or SSH agent.
918 * **Worktree folder**: a folder on the remote machine, such as `~/worktrees`, where new sessions create their worktrees. Leave empty to use the [remote machine's default](#choose-where-ssh-session-worktrees-go).
919
920 Then select **Add SSH connection**.
921 </Step>
922
923 <Step title="Start a session on the connection">
924 Select a folder on the remote machine and click **Create environment**. You keep the machine and folder together as a [saved environment](#create-a-saved-environment) for later sessions. Desktop selects it for the new session, so type your task and press **Enter**.
925 </Step>
926</Steps>
890**1. Open the New environment dialog**
891
892Before you start a session, open the environment selector under the prompt box and select **New environment** at the bottom of its menu.
893
894**2. Add the connection**
895
896On the **SSH** tab of the **New environment** dialog, open the **Host** list, select **Add SSH connection…**, and fill in the connection details:
897
898* **Name**: a friendly label for this connection.
899* **SSH host**: `user@hostname` or a host defined in `~/.ssh/config`.
900* **SSH port**: defaults to 22 if left empty, or uses the port from your SSH config.
901* **SSH key (optional)**: path to your private key, such as `~/.ssh/id_ed25519`. Leave empty to use your SSH config or SSH agent.
902* **Worktree folder**: a folder on the remote machine, such as `~/worktrees`, where new sessions create their worktrees. Leave empty to use the [remote machine's default](#choose-where-ssh-session-worktrees-go).
903
904Then select **Add SSH connection**.
905
906**3. Start a session on the connection**
907
908Select a folder on the remote machine and click **Create environment**. You keep the machine and folder together as a [saved environment](#create-a-saved-environment) for later sessions. Desktop selects it for the new session, so type your task and press **Enter**.
927909
928910The remote machine can run Linux, macOS, or [Windows](#windows-remote-machines). Desktop installs Claude Code on the remote machine automatically the first time you connect. Once connected, SSH sessions support permission modes, connectors, plugins, and MCP servers.
929911
from line 926
944926
945927An SSH session doesn't get them from those files, even when `claude` in a terminal on that machine does. The session can then hang, or show **The connection from … to the API failed** or **Authentication failed**, and signing in again doesn't help.
946928
947<Steps>
948 <Step title="Add the variables">
949 For the CA file, use [`NODE_EXTRA_CA_CERTS`](/docs/en/network-config#custom-ca-certificates), because Claude Code doesn't trust a CA from `SSL_CERT_FILE` in `~/.claude/settings.json`. This example sets a proxy and a CA file:
950
951 ```json ~/.claude/settings.json theme={null}
952 {
953 "env": {
954 "HTTPS_PROXY": "http://proxy.example.com:8080",
955 "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
956 }
957 }
958 ```
959 </Step>
960
961 <Step title="Send your message again">
962 Send your message again, because a variable that you add or change in that file takes effect within seconds. Start a new session if it still fails.
963 </Step>
964</Steps>
929**1. Add the variables**
930
931For the CA file, use [`NODE_EXTRA_CA_CERTS`](/docs/en/network-config#custom-ca-certificates), because Claude Code doesn't trust a CA from `SSL_CERT_FILE` in `~/.claude/settings.json`. This example sets a proxy and a CA file:
932
933```json ~/.claude/settings.json theme={null}
934{
935 "env": {
936 "HTTPS_PROXY": "http://proxy.example.com:8080",
937 "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
938 }
939}
940```
941
942**2. Send your message again**
943
944Send your message again, because a variable that you add or change in that file takes effect within seconds. Start a new session if it still fails.
965945
966946##### Find a proxy or CA variable set elsewhere on the remote machine
967947
968948Check whether the Linux remote machine sets the proxy or CA variable elsewhere, because sessions use that value and [ignore the one in any settings file](/docs/en/settings-reference#how-env-values-interact-with-your-shell):
969949
970<Steps>
971 <Step title="List the variables that the remote machine sets">
972 In a terminal on your computer, run `ssh devbox env`, with your own host.
973 </Step>
974
975 <Step title="Change the variable where it is set">
976 If the list has the variable, change it in the file that sets it, such as `~/.zshenv`, `/etc/environment`, or `~/.bashrc` on the remote machine.
977 </Step>
978
979 <Step title="Give sessions the new value">
980 Restart the remote machine, or quit Desktop and end the helper's processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude's work.
981 </Step>
982</Steps>
950**1. List the variables that the remote machine sets**
951
952In a terminal on your computer, run `ssh devbox env`, with your own host.
953
954**2. Change the variable where it is set**
955
956If the list has the variable, change it in the file that sets it, such as `~/.zshenv`, `/etc/environment`, or `~/.bashrc` on the remote machine.
957
958**3. Give sessions the new value**
959
960Restart the remote machine, or quit Desktop and end the helper's processes, as in the first two steps to [remove the helper](#files-and-processes-on-the-remote-machine). Do this when no task is running, because either way interrupts Claude's work.
983961
984962#### Use your SSH configuration on macOS and Linux
985963
from line 990
1012990
1013991To run a session inside a container that publishes no SSH port, reach it with a `ProxyCommand`, because Desktop doesn't run the `RemoteCommand` of the entry you connect to. If your entry uses `RemoteCommand` to step into the container, the session runs on the machine that the entry logs in to, not in the container.
1014992
1015<Steps>
1016 <Step title="Add the entry">
1017 Add the following entry at the end of your `~/.ssh/config`, or directly above your first `Host *` entry if you have one. Replace the Docker container `devbox`, its user `dev`, and the machine `build.example.com` with your own. The entry's command starts an SSH server inside the container for each connection:
1018
1019 ```text ~/.ssh/config theme={null}
1020 Host devbox-container
1021 User dev
1022 ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i
1023 ```
1024 </Step>
1025
1026 <Step title="Prepare the container">
1027 * Install the OpenSSH server, with a host key that stays the same when you rebuild the image or recreate the container
1028 * Give the account named in `User` a way to log in, such as an `authorized_keys` file
1029 * Check that the container meets the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions)
1030 </Step>
1031
1032 <Step title="Check the allowlist">
1033 If your administrator [restricts SSH hosts](#restrict-which-ssh-hosts-users-can-connect-to), run `ssh -G devbox-container` in a terminal on your computer. Ask them to allow the `hostname` that it prints, here `devbox-container`, in `sshHostAllowlist`. When they allow that name, they allow whatever your entry's `ProxyCommand` connects to.
1034 </Step>
1035
1036 <Step title="Test the entry, then connect">
1037 Run `ssh devbox-container` in a terminal on your computer. Fix what it reports, and run it again until it opens a shell in the container without asking you anything:
1038
1039 * **If `ssh` asks for a password, passphrase, or code**: switch to a login that works without a prompt, such as a key that your SSH agent holds
1040 * **If `ssh` reports `Cannot execute command-line and remote command.` or `Bad packet length`**: take `RemoteCommand` and `RequestTTY` out of your entry for `build.example.com`. After that, `ssh build.example.com` in a terminal on your computer opens a shell on that machine, not in the container.
1041 * **If `ssh` reports `Connection closed by UNKNOWN port 65535`**: run `ssh build.example.com docker exec devbox /usr/sbin/sshd -t` in the same terminal.
1042 * If it prints `Missing privilege separation directory: /run/sshd`, create that folder in the container.
1043 * If it prints `no hostkeys available` and the container has host keys, add `-u root` after `exec` in this command and in the entry.
1044
1045 Then enter `devbox-container` in the **SSH host** field.
1046 </Step>
1047</Steps>
993**1. Add the entry**
994
995Add the following entry at the end of your `~/.ssh/config`, or directly above your first `Host *` entry if you have one. Replace the Docker container `devbox`, its user `dev`, and the machine `build.example.com` with your own. The entry's command starts an SSH server inside the container for each connection:
996
997```text ~/.ssh/config theme={null}
998Host devbox-container
999 User dev
1000 ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i
1001```
1002
1003**2. Prepare the container**
1004
1005* Install the OpenSSH server, with a host key that stays the same when you rebuild the image or recreate the container
1006* Give the account named in `User` a way to log in, such as an `authorized_keys` file
1007* Check that the container meets the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions)
1008
1009**3. Check the allowlist**
1010
1011If your administrator [restricts SSH hosts](#restrict-which-ssh-hosts-users-can-connect-to), run `ssh -G devbox-container` in a terminal on your computer. Ask them to allow the `hostname` that it prints, here `devbox-container`, in `sshHostAllowlist`. When they allow that name, they allow whatever your entry's `ProxyCommand` connects to.
1012
1013**4. Test the entry, then connect**
1014
1015Run `ssh devbox-container` in a terminal on your computer. Fix what it reports, and run it again until it opens a shell in the container without asking you anything:
1016
1017* **If `ssh` asks for a password, passphrase, or code**: switch to a login that works without a prompt, such as a key that your SSH agent holds
1018* **If `ssh` reports `Cannot execute command-line and remote command.` or `Bad packet length`**: take `RemoteCommand` and `RequestTTY` out of your entry for `build.example.com`. After that, `ssh build.example.com` in a terminal on your computer opens a shell on that machine, not in the container.
1019* **If `ssh` reports `Connection closed by UNKNOWN port 65535`**: run `ssh build.example.com docker exec devbox /usr/sbin/sshd -t` in the same terminal.
1020 * If it prints `Missing privilege separation directory: /run/sshd`, create that folder in the container.
1021 * If it prints `no hostkeys available` and the container has host keys, add `-u root` after `exec` in this command and in the entry.
1022
1023Then enter `devbox-container` in the **SSH host** field.
10481024
10491025##### Use variables from your shell in a `ProxyCommand`
10501026
from line 1028
10521028
10531029This requires Claude Desktop v2.37337.0 or later and an `env` command that accepts `-0`, which you can check by running `env -0` in a terminal on your computer.
10541030
1055<Note>
1056 If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables.
1057</Note>
1058
1059<a id="use-aws-credentials-in-a-proxycommand" />
1031> [!NOTE]
1032>
1033> If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables.
10601034
10611035##### Use AWS credentials in a `ProxyCommand`
10621036
from line 1038
10641038
10651039If the AWS CLI has no other source for a region or credentials, it fails with `You must specify a region` or `Unable to locate credentials`. To connect from Desktop, give the AWS CLI a profile that it reads from `~/.aws/config`:
10661040
1067<Steps>
1068 <Step title="Add a profile with a region and a source of credentials">
1069 This example adds a profile named `corp` that gets its credentials from a helper program:
1070
1071 ```ini ~/.aws/config theme={null}
1072 [profile corp]
1073 region = us-east-1
1074 credential_process = /full/path/to/your-credential-helper
1075 ```
1076
1077 * **`region`**: give the AWS Region of the machines you connect to
1078 * **`credential_process`**: give the full path of a program that prints credentials in the [JSON form that AWS documents](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Choose a program that needs no input from you, because the AWS CLI runs it at every connection, including reconnects while you're away.
1079 * **IAM Identity Center**: add the profile's [IAM Identity Center settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) in place of `credential_process`. Run `aws sso login --profile corp` in a terminal before you connect, and again when that sign-in lapses.
1080 </Step>
1081
1082 <Step title="Name the profile in the ProxyCommand">
1083 This example adds `--profile` to the [command that AWS documents for Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html):
1084
1085 ```text ~/.ssh/config theme={null}
1086 Host i-*
1087 ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"
1088 ```
1089 </Step>
1090
1091 <Step title="Connect again">
1092 Run `ssh` with the host in a terminal to confirm that the entry still connects there, then connect from Desktop.
1093 </Step>
1094</Steps>
1041**1. Add a profile with a region and a source of credentials**
1042
1043This example adds a profile named `corp` that gets its credentials from a helper program:
1044
1045```ini ~/.aws/config theme={null}
1046[profile corp]
1047region = us-east-1
1048credential_process = /full/path/to/your-credential-helper
1049```
1050
1051* **`region`**: give the AWS Region of the machines you connect to
1052* **`credential_process`**: give the full path of a program that prints credentials in the [JSON form that AWS documents](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html). Choose a program that needs no input from you, because the AWS CLI runs it at every connection, including reconnects while you're away.
1053* **IAM Identity Center**: add the profile's [IAM Identity Center settings](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) in place of `credential_process`. Run `aws sso login --profile corp` in a terminal before you connect, and again when that sign-in lapses.
1054
1055**2. Name the profile in the ProxyCommand**
1056
1057This example adds `--profile` to the [command that AWS documents for Session Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-getting-started-enable-ssh-connections.html):
1058
1059```text ~/.ssh/config theme={null}
1060Host i-*
1061 ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"
1062```
1063
1064**3. Connect again**
1065
1066Run `ssh` with the host in a terminal to confirm that the entry still connects there, then connect from Desktop.
10951067
10961068##### Raise the SSH connection timeout
10971069
from line 1146
11741146
11751147Claude Code runs as a process on the remote machine, under a background helper that Desktop installs there, so it doesn't need your SSH connection to keep running. The behavior in this section requires Claude Desktop v2.31226.0 or later.
11761148
1177<Warning>
1178 If you sign in to Desktop with a Claude account, don't count on a task to run overnight. Desktop renews that sign-in for the task only while Desktop is running and connected, so the task's sign-in can expire after you disconnect, and the task then stops. How much time is left when you disconnect varies, and it can be only a few minutes.
1179
1180 The work done so far stays on the remote machine, and you can continue with a message when you return.
1181
1182 If the task must run through the night:
1183
1184 * [Keep your computer awake](/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run) and online, with the lid open and Desktop running
1185 * Use a login that works without a prompt, such as a key that your SSH agent holds, for the remote machine and for any jump host on the way. Desktop can then reconnect on its own after a drop.
1186
1187 For a task that must run while your computer is asleep or off, start a [cloud session](#run-long-running-tasks-in-the-cloud) instead.
1188</Warning>
1149> [!WARNING]
1150>
1151> If you sign in to Desktop with a Claude account, don't count on a task to run overnight. Desktop renews that sign-in for the task only while Desktop is running and connected, so the task's sign-in can expire after you disconnect, and the task then stops. How much time is left when you disconnect varies, and it can be only a few minutes.
1152>
1153> The work done so far stays on the remote machine, and you can continue with a message when you return.
1154>
1155> If the task must run through the night:
1156>
1157> * [Keep your computer awake](/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run) and online, with the lid open and Desktop running
1158> * Use a login that works without a prompt, such as a key that your SSH agent holds, for the remote machine and for any jump host on the way. Desktop can then reconnect on its own after a drop.
1159>
1160> For a task that must run while your computer is asleep or off, start a [cloud session](#run-long-running-tasks-in-the-cloud) instead.
11891161
11901162* **After sleep or a network loss**: you get the running task back if the process [still runs](#limits-while-desktop-is-disconnected) and Desktop can log in without a prompt. If it can't, [send a message](#reconnect-after-sleep-or-a-network-loss).
11911163* **After a quit**: the task keeps running, but you lose it when the session opens again unless Desktop can rejoin its process. Check [when Desktop can rejoin](#reopen-a-session-after-you-quit-desktop) before you quit. If you lost the task, send a message to continue.
from line 1168
11961168* **Authentication error**: the [sign-in token or credential](#limits-while-desktop-is-disconnected) may have expired. With a Claude account, send a message to continue. With a third-party provider, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
11971169* **Waiting request**: [answer it](#handle-requests-that-arrive-while-you-are-away)
11981170* **None of these**: send a message to continue
1199
1200<a id="prepare-a-long-task" />
12011171
12021172##### Prepare a long task
12031173
from line 1178
12081178* **Test the remote machine**: start a short task, quit Desktop while the task is still running, and open the session again well after the task should be done. If the task isn't finished and the session shows no authentication error, check the remote machine for [what can end a task](#limits-while-desktop-is-disconnected).
12091179* **Keep commands out of Desktop's terminal**: if the remote machine [logs out idle terminals](#limits-while-desktop-is-disconnected), run your own commands from an SSH login outside Desktop
12101180
1211<a id="limits-while-desktop-is-disconnected" />
1212
12131181##### Limits while Desktop is disconnected
12141182
12151183A task that you leave running can end when its sign-in expires, when the remote machine ends it, or when the helper stops or is replaced:
from line 1196
12281196* **Workflows**: Desktop checks each new [workflow](/docs/en/workflows) before it starts, so while Desktop is disconnected a new one waits up to 10 minutes and then fails
12291197* **MCP servers**: MCP servers that Claude Code starts on the remote machine don't run through Desktop, so Claude can still call their tools. Servers from `claude_desktop_config.json` are among them only if Desktop doesn't use its [built-in SSH client](#worktree-edits-while-disconnected). Otherwise, and on [some Windows remote machines](#windows-remote-machines), Claude can't call their tools while Desktop is disconnected.
12301198
1231<span id="worktree-edits-while-disconnected" />
1232
1233<Accordion title="When edits in a worktree keep working">
1234 On a Linux or macOS remote machine, the check doesn't go through Desktop, so edits inside the worktree keep working while Desktop is disconnected. Before Claude Desktop v2.37337.0, this holds on a Linux remote machine only.
1235
1236 Edits still fail in some cases, including these:
1237
1238 * **Built-in SSH client**: Desktop uses it, for example in a Microsoft Store install, on a Windows computer without Microsoft's OpenSSH 9.4 or later, or by default on Windows with a third-party provider
1239 * **Repository location**: the repository is your home directory, a folder above it, or `~/.claude`
1240 * **macOS paths**: on a macOS remote machine, the repository is under `/Volumes`, or a folder name in the path of the repository or the worktree has a `~` or a non-ASCII character
1241 * **Folder restrictions**: your organization restricts which folders sessions may use
1242 * **Corporate launcher**: before Claude Desktop v2.37337.0, you sign in with a Claude account, and your organization starts Claude Code on the remote machine through a [corporate launcher](/docs/en/corporate-launcher)
1243
1244 A session without a worktree has no such check, unless your organization restricts which folders sessions may use.
1245</Accordion>
1246
1247<a id="handle-requests-that-arrive-while-you-are-away" />
1199> **When edits in a worktree keep working**
1200>
1201> On a Linux or macOS remote machine, the check doesn't go through Desktop, so edits inside the worktree keep working while Desktop is disconnected. Before Claude Desktop v2.37337.0, this holds on a Linux remote machine only.
1202>
1203> Edits still fail in some cases, including these:
1204>
1205> * **Built-in SSH client**: Desktop uses it, for example in a Microsoft Store install, on a Windows computer without Microsoft's OpenSSH 9.4 or later, or by default on Windows with a third-party provider
1206> * **Repository location**: the repository is your home directory, a folder above it, or `~/.claude`
1207> * **macOS paths**: on a macOS remote machine, the repository is under `/Volumes`, or a folder name in the path of the repository or the worktree has a `~` or a non-ASCII character
1208> * **Folder restrictions**: your organization restricts which folders sessions may use
1209> * **Corporate launcher**: before Claude Desktop v2.37337.0, you sign in with a Claude account, and your organization starts Claude Code on the remote machine through a [corporate launcher](/docs/en/corporate-launcher)
1210>
1211> A session without a worktree has no such check, unless your organization restricts which folders sessions may use.
12481212
12491213##### Handle requests that arrive while you are away
12501214
from line 1230
12661230
12671231Claude Code doesn't auto-approve [a few actions](/docs/en/permission-modes#actions-no-mode-auto-approves) in any permission mode, including Bypass permissions. Depending on the permission mode, Claude Code denies such an action or asks you, and the task then waits for your answer.
12681232
1269<a id="reconnect-after-sleep-or-a-network-loss" />
1270
12711233##### Reconnect after sleep or a network loss
12721234
12731235If Desktop hasn't reconnected when you come back, send a message in the session. Desktop reconnects on its own only where it can log in without a prompt, for example with a key that your SSH agent holds.
from line 1237
12751237* **Remembered password**: a password that you let Desktop remember also works without a prompt, but for a long absence prefer a key that your SSH agent holds. If sign-ins with that password break off or hang, Desktop can stop reconnecting and wait for you.
12761238* **Any other prompt**: if the remote machine prompts for anything else, such as a one-time code, you can get a notification on your computer. Click the notification, or send a message in the session, and Desktop shows the prompt.
12771239
1278<Accordion title="If a jump host asks for a sign-in, the outage is long, output is missing, or the process is gone">
1279 - **Jump host, pushes stop while you're away**: this can happen with Desktop on macOS or Linux when nobody answers a jump host's sign-in, for example a push to a phone. Desktop then stops reconnecting while nobody is at your computer. When you unlock or use the computer, you can get another push, because Desktop can try again. After three unanswered attempts it waits until you retry or send a message.
1280 - **Jump host, pushes keep coming**: where Desktop can't tell that nobody answers, as with Desktop on Windows, it keeps trying while it has a process to rejoin, whether or not that process still runs. You can get another push with each attempt. To end the attempts, quit Desktop, which [can cost you the running task](#reopen-a-session-after-you-quit-desktop).
1281 - **Long outage**: Desktop slows to about one attempt every five minutes. To reconnect sooner, retry in the session or send a message, which Desktop delivers once it is connected.
1282 - **Missing output**: while Desktop is disconnected, the helper keeps each session's most recent Claude Code output in a 16 MiB buffer and drops older output. After Desktop reconnects, the session can show `Loading recent output from <host>…`. If Desktop can't load all of the output, you see the row `Some output produced while you were disconnected may be missing here.` The row doesn't mean that the task stopped.
1283 - **Process gone**: the process ended while Desktop was disconnected, as when the remote machine restarts. Desktop can then start a new one from the conversation's saved history and tell Claude to continue the task. If the task stays stopped, send a message. With a third-party provider, update to Claude Desktop v2.42304.0 or later, because earlier versions never continue the task on their own.
1284</Accordion>
1285
1286<a id="reopen-a-session-after-you-quit-desktop" />
1240> **If a jump host asks for a sign-in, the outage is long, output is missing, or the process is gone**
1241>
1242> * **Jump host, pushes stop while you're away**: this can happen with Desktop on macOS or Linux when nobody answers a jump host's sign-in, for example a push to a phone. Desktop then stops reconnecting while nobody is at your computer. When you unlock or use the computer, you can get another push, because Desktop can try again. After three unanswered attempts it waits until you retry or send a message.
1243> * **Jump host, pushes keep coming**: where Desktop can't tell that nobody answers, as with Desktop on Windows, it keeps trying while it has a process to rejoin, whether or not that process still runs. You can get another push with each attempt. To end the attempts, quit Desktop, which [can cost you the running task](#reopen-a-session-after-you-quit-desktop).
1244> * **Long outage**: Desktop slows to about one attempt every five minutes. To reconnect sooner, retry in the session or send a message, which Desktop delivers once it is connected.
1245> * **Missing output**: while Desktop is disconnected, the helper keeps each session's most recent Claude Code output in a 16 MiB buffer and drops older output. After Desktop reconnects, the session can show `Loading recent output from <host>…`. If Desktop can't load all of the output, you see the row `Some output produced while you were disconnected may be missing here.` The row doesn't mean that the task stopped.
1246> * **Process gone**: the process ended while Desktop was disconnected, as when the remote machine restarts. Desktop can then start a new one from the conversation's saved history and tell Claude to continue the task. If the task stays stopped, send a message. With a third-party provider, update to Claude Desktop v2.42304.0 or later, because earlier versions never continue the task on their own.
12871247
12881248##### Reopen a session after you quit Desktop
12891249
from line 1257
12971257
12981258For third-party deployments, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
12991259
1300<Warning>
1301 While a conversation's Claude Code process is still running, don't run [`claude --resume`](/docs/en/cli-reference#cli-flags) for it on the remote machine. Claude Code doesn't stop you, and both processes then write to the same conversation. If you aren't sure, add `--fork-session`, which continues in a copy of the conversation, but both processes still work on the same files.
1302</Warning>
1260> [!WARNING]
1261>
1262> While a conversation's Claude Code process is still running, don't run [`claude --resume`](/docs/en/cli-reference#cli-flags) for it on the remote machine. Claude Code doesn't stop you, and both processes then write to the same conversation. If you aren't sure, add `--fork-session`, which continues in a copy of the conversation, but both processes still work on the same files.
13031263
13041264#### Choose where SSH session worktrees go
13051265
from line 1271
13111271
13121272Each project gets its own subfolder in the folder you set, so with `~/worktrees` a worktree's path is `~/worktrees/<project>-<id>/<worktree-name>`. If the folder you set is inside the project, Desktop ignores it for that project and uses the default. On a [Windows remote machine](#windows-remote-machines), Desktop always uses the default.
13131273
1314<a id="set-the-worktree-folder-on-an-existing-connection" />
1315
13161274##### Set the worktree folder on an existing connection
13171275
13181276Set **Worktree folder** in the settings of a connection you added earlier or one your organization manages. The field requires Claude Desktop v1.44121.0 or later. If your organization restricts which folders sessions may use, Desktop hides the field and keeps worktrees inside the project.
13191277
1320<Steps>
1321 <Step title="Find the connection">
1322 Open the [environment selector](#start-a-session) and find the connection under **SSH**.
1323 </Step>
1324
1325 <Step title="Open the connection's settings">
1326 Hover over the connection and click the gear icon. If the dialog that opens shows **Edit connection…** next to **Host**, select **Edit connection…**.
1327 </Step>
1328
1329 <Step title="Set the folder">
1330 In **Worktree folder**, enter a folder on the remote machine, such as `~/worktrees`, and select **Save changes**.
1331 </Step>
1332</Steps>
1278**1. Find the connection**
1279
1280Open the [environment selector](#start-a-session) and find the connection under **SSH**.
1281
1282**2. Open the connection's settings**
1283
1284Hover over the connection and click the gear icon. If the dialog that opens shows **Edit connection…** next to **Host**, select **Edit connection…**.
1285
1286**3. Set the folder**
1287
1288In **Worktree folder**, enter a folder on the remote machine, such as `~/worktrees`, and select **Save changes**.
13331289
13341290#### Files and processes on the remote machine
13351291
from line 1310
13541310
13551311To remove the helper and Claude Code for one user:
13561312
1357<Steps>
1358 <Step title="Quit Desktop">
1359 Quit Desktop on each computer that the user connects from. It installs both programs again the next time it connects, and it can reconnect on its own.
1360 </Step>
1361
1362 <Step title="End the processes">
1363 Logged in as that user on the remote machine, run `kill` with the ID of each Claude Code process that [`pgrep`](#files-and-processes-on-the-remote-machine) lists. Once those are gone from the list, run `kill` with the ID of each `server` process. If you end a `server` process first, a command that Claude Code is running can keep running.
1364
1365 Then list the user's remaining processes, for example with `ps -u "$(id -un)" -f`, and end any that you recognize as started by Claude Code. Programs that it left in the background can keep running after it ends, without being in the `pgrep` list.
1366 </Step>
1367
1368 <Step title="Delete the folder">
1369 Delete `~/.claude/remote/`. To remove Claude Code's own files in `~/.claude/` and `~/.claude.json`, see [Remove configuration files](/docs/en/setup#remove-configuration-files).
1370 </Step>
1371</Steps>
1313**1. Quit Desktop**
1314
1315Quit Desktop on each computer that the user connects from. It installs both programs again the next time it connects, and it can reconnect on its own.
1316
1317**2. End the processes**
1318
1319Logged in as that user on the remote machine, run `kill` with the ID of each Claude Code process that [`pgrep`](#files-and-processes-on-the-remote-machine) lists. Once those are gone from the list, run `kill` with the ID of each `server` process. If you end a `server` process first, a command that Claude Code is running can keep running.
1320
1321Then list the user's remaining processes, for example with `ps -u "$(id -un)" -f`, and end any that you recognize as started by Claude Code. Programs that it left in the background can keep running after it ends, without being in the `pgrep` list.
1322
1323**3. Delete the folder**
1324
1325Delete `~/.claude/remote/`. To remove Claude Code's own files in `~/.claude/` and `~/.claude.json`, see [Remove configuration files](/docs/en/setup#remove-configuration-files).
13721326
13731327##### End one session's process
13741328
from line 1364
14101364
14111365The lines of 8.0 to 8.2 have no address. To get one, set `LogLevel VERBOSE` in `sshd_config` and run `sshd -T | grep -i loglevel` as root. If it prints `loglevel VERBOSE`, reload the SSH server. Then look for a line with `Connection from 203.0.113.7 port 51234` before the test's line.
14121366
1413<a id="check-whether-the-ssh-server-itself-refuses-the-address" />
1414
14151367##### Check whether the SSH server itself refuses the address
14161368
14171369If connections are refused from an address that many computers with Desktop share, look in the SSH server's log for a line that ends like this one:
from line 1376
14241376
14251377To prevent the refusal, set `PerSourcePenaltyExemptList` in `sshd_config` to the addresses that people connect from, for example `PerSourcePenaltyExemptList 203.0.113.7`. The server then applies none of its penalties to those addresses, including those for failed logins. To check the file, run `sshd -T | grep -i persourcepenalt` as root. If it prints your list, reload the SSH server.
14261378
1427<a id="check-whether-fail2ban-counts-desktops-tests" />
1428
14291379##### Check whether fail2ban counts Desktop's tests
14301380
14311381If fail2ban 0.10.5 or later banned an address that Desktop connects from, find your jail's mode in `jail.conf`, `jail.local` or under `jail.d/`:
from line 1392
14421392```
14431393
14441394For each failure that fail2ban counts, the command prints the address on a line of its own, such as `203.0.113.7`. In that case, [prevent a ban](#prevent-a-ban-by-fail2ban). If it prints nothing, fail2ban counts none of those lines in that mode, so look for another cause of the ban.
1445
1446<a id="prevent-a-ban-by-fail2ban" />
14471395
14481396##### Prevent a ban by fail2ban
14491397
from line 1490
15421490}
15431491```
15441492
1545<Warning>
1546 If your organization delivers [server-managed settings](/docs/en/server-managed-settings), set `sshHostAllowlist` there. By default, Desktop reads the key only from the [highest-ranked managed source that delivers a policy key](/docs/en/managed-settings#how-claude-code-combines-managed-sources). If that source leaves the key unset, Desktop ignores a list in a lower-ranked MDM policy or managed settings file and treats the key as [unset](/docs/en/settings-reference#sshhostallowlist). Desktop shows no warning.
1547
1548 Also keep the same list on each user's machine, in the highest-ranked MDM policy or managed settings file there. Desktop fetches server-managed settings at launch and keeps no cached copy, so until a fetch succeeds the machine's list is the one that applies.
1549</Warning>
1493> [!WARNING]
1494>
1495> If your organization delivers [server-managed settings](/docs/en/server-managed-settings), set `sshHostAllowlist` there. By default, Desktop reads the key only from the [highest-ranked managed source that delivers a policy key](/docs/en/managed-settings#how-claude-code-combines-managed-sources). If that source leaves the key unset, Desktop ignores a list in a lower-ranked MDM policy or managed settings file and treats the key as [unset](/docs/en/settings-reference#sshhostallowlist). Desktop shows no warning.
1496>
1497> Also keep the same list on each user's machine, in the highest-ranked MDM policy or managed settings file there. Desktop fetches server-managed settings at launch and keeps no cached copy, so until a fetch succeeds the machine's list is the one that applies.
15501498
15511499Patterns are case-insensitive. `*` matches any host, and `*.example.com` matches `example.com` and any subdomain. Anything else is an exact match. The check runs against the hostname after `~/.ssh/config` resolution via `ssh -G`, so `Host` aliases and `ProxyCommand`/`ProxyJump` entries are permitted as long as the resolved `HostName` matches.
15521500
from line 1504
15561504
15571505To turn off local sessions and limit SSH sessions to hosts that you choose, deploy [`disableDesktopLocalSessions`](/docs/en/settings-reference#disabledesktoplocalsessions), [`sshConfigs`](#pre-configure-ssh-connections-for-your-team), and [`sshHostAllowlist`](#restrict-which-ssh-hosts-users-can-connect-to) together.
15581506
1559<Note>
1560 This setup is for users who sign in with a Claude account. With a [third-party provider](/docs/en/third-party-integrations), SSH sessions are off by default, and setting `sshHostAllowlist` can turn them on. Read [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions) before you deploy these keys.
1561</Note>
1507> [!NOTE]
1508>
1509> This setup is for users who sign in with a Claude account. With a [third-party provider](/docs/en/third-party-integrations), SSH sessions are off by default, and setting `sshHostAllowlist` can turn them on. Read [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions) before you deploy these keys.
15621510
15631511The following example turns off local sessions, adds one connection, and limits SSH sessions to that connection's host:
15641512
from line 1540
15921540
15931541To confirm that the settings apply, check a developer's computer:
15941542
1595<Steps>
1596 <Step title="Check the environment selector">
1597 Quit and reopen Desktop, then open the [environment selector](#start-a-session). The settings applied if it shows:
1598
1599 * The entry for that computer, in gray
1600 * **Shared Dev VM** under **SSH**. If it isn't listed there, click the single **SSH** row, or **More** at the end of the group.
1601
1602 If the entry for the computer is still available, check for these causes:
1603
1604 * **Desktop version**: update Desktop if it's earlier than v1.37937.0.
1605 * **Managed settings file**: make sure that the file is valid JSON.
1606 * **Managed source**: make sure that the computer reads the [managed source](/docs/en/managed-settings#how-claude-code-combines-managed-sources) that holds the keys.
1607 </Step>
1608
1609 <Step title="Add a host that isn't on the allowlist">
1610 [Add an SSH connection](#ssh-sessions) with a hostname that isn't on the allowlist, such as `other.example.com`. Desktop saves the connection but refuses to connect, and says that your organization's settings don't allow the connection.
1611 </Step>
1612</Steps>
1543**1. Check the environment selector**
1544
1545Quit and reopen Desktop, then open the [environment selector](#start-a-session). The settings applied if it shows:
1546
1547* The entry for that computer, in gray
1548* **Shared Dev VM** under **SSH**. If it isn't listed there, click the single **SSH** row, or **More** at the end of the group.
1549
1550If the entry for the computer is still available, check for these causes:
1551
1552* **Desktop version**: update Desktop if it's earlier than v1.37937.0.
1553* **Managed settings file**: make sure that the file is valid JSON.
1554* **Managed source**: make sure that the computer reads the [managed source](/docs/en/managed-settings#how-claude-code-combines-managed-sources) that holds the keys.
1555
1556**2. Add a host that isn't on the allowlist**
1557
1558[Add an SSH connection](#ssh-sessions) with a hostname that isn't on the allowlist, such as `other.example.com`. Desktop saves the connection but refuses to connect, and says that your organization's settings don't allow the connection.
16131559
16141560## Enterprise configuration
16151561
from line 1571
16251571
16261572In Enterprise organizations that have HIPAA enabled, the **Desktop** toggle is off by default and an [Owner](/docs/en/server-managed-settings#access-control) can turn it on. Applying the [HIPAA configuration](/docs/en/hipaa-setup) turns it off, even if it was on, so an Owner has to turn it on afterward. **Cloud sessions** and **Remote Control** are also off by default, and an Owner can't turn them on once the organization has the HIPAA configuration applied.
16271573
1628<Note>
1629 The OpenTelemetry form for Cowork under **Monitoring** in the admin console's [Data and privacy settings](https://claude.ai/admin-settings/data-privacy-controls) applies to Cowork sessions only. In a Cowork session on this machine, the desktop app passes that collector to Claude Code as `OTEL_*` environment variables, so the form takes effect even though Claude Code in that session [never fetches admin-console settings](#managed-settings).
1630
1631 To export telemetry from Code tab sessions, set `CLAUDE_CODE_ENABLE_TELEMETRY` and the `OTEL_*` variables in the `env` block of your Claude Code managed settings, as shown in [administrator configuration for monitoring](/docs/en/monitoring-usage#administrator-configuration). Local, cloud, and SSH sessions each read [managed settings from different sources](#managed-settings). For the hosts a cloud session can reach, see [network access](/docs/en/cloud-environments#network-access). For the `service.name` that Code tab sessions report, see [service information](/docs/en/monitoring-usage#service-information).
1632
1633 To find out which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](/docs/en/monitoring-usage#attribute-telemetry-to-desktop-ssh-sessions).
1634</Note>
1574> [!NOTE]
1575>
1576> The OpenTelemetry form for Cowork under **Monitoring** in the admin console's [Data and privacy settings](https://claude.ai/admin-settings/data-privacy-controls) applies to Cowork sessions only. In a Cowork session on this machine, the desktop app passes that collector to Claude Code as `OTEL_*` environment variables, so the form takes effect even though Claude Code in that session [never fetches admin-console settings](#managed-settings).
1577>
1578> To export telemetry from Code tab sessions, set `CLAUDE_CODE_ENABLE_TELEMETRY` and the `OTEL_*` variables in the `env` block of your Claude Code managed settings, as shown in [administrator configuration for monitoring](/docs/en/monitoring-usage#administrator-configuration). Local, cloud, and SSH sessions each read [managed settings from different sources](#managed-settings). For the hosts a cloud session can reach, see [network access](/docs/en/cloud-environments#network-access). For the `service.name` that Code tab sessions report, see [service information](/docs/en/monitoring-usage#service-information).
1579>
1580> To find out which remote machine an SSH session ran on, see [Attribute telemetry to Desktop SSH sessions](/docs/en/monitoring-usage#attribute-telemetry-to-desktop-ssh-sessions).
16351581
16361582### Managed settings
16371583
from line 1711
17651711
17661712Desktop continues the same session rather than a copy, so `claude --resume` in the terminal still finds it afterwards.
17671713
1768<Tip>
1769 When to use Desktop vs CLI: use Desktop when you want to manage parallel sessions in one window, arrange panes side by side, or review changes visually. Use the CLI when you need scripting, automation, or prefer a terminal workflow.
1770</Tip>
1714> [!TIP]
1715>
1716> When to use Desktop vs CLI: use Desktop when you want to manage parallel sessions in one window, arrange panes side by side, or review changes visually. Use the CLI when you need scripting, automation, or prefer a terminal workflow.
17711717
17721718### CLI flag equivalents
17731719
from line 1750
18041750
18051751The app also re-delivers stdio servers from `~/.claude.json` to the embedded CLI in local sessions. When the top level of `~/.claude.json` (user scope) and `.mcp.json` define the same stdio server name, the Code tab uses the `~/.claude.json` definition, departing from the CLI [scope hierarchy](/docs/en/mcp#scope-hierarchy-and-precedence).
18061752
1807<Note>
1808 The standalone CLI does not read `claude_desktop_config.json`. On macOS and WSL, run `claude mcp add-from-claude-desktop` to copy those servers into `~/.claude.json`. See [Import MCP servers from Claude Desktop](/docs/en/mcp#import-mcp-servers-from-claude-desktop) for the import flow and scope options.
1809</Note>
1753> [!NOTE]
1754>
1755> The standalone CLI does not read `claude_desktop_config.json`. On macOS and WSL, run `claude mcp add-from-claude-desktop` to copy those servers into `~/.claude.json`. See [Import MCP servers from Claude Desktop](/docs/en/mcp#import-mcp-servers-from-claude-desktop) for the import flow and scope options.
18101756
18111757### Feature comparison
18121758
from line 1867
19211867
19221868For any other message, check the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions).
19231869
1924<a id="get-desktops-logs-for-an-ssh-problem" />
1925
19261870### Get Desktop's logs for an SSH problem
19271871
19281872You get `ssh.log`, Desktop's record of its SSH connections, in a zip file of Desktop's logs that you save from the **Help** menu. To save it, open **Help > Troubleshooting** and select the item for your system:
19291873
No line in this hunk matches that.