Desktop application changeddesktop
Nearest release: v2.1.299, published 4 hours 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 13 Oct 2026 20:19 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 13 Oct 2026 20:37 UTC.
Upstream edited
Recorded here
Lines+163added
Lines−5removed
From line
40
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits79to this page, all time
#### Windows remote machines #### Keep a task running while Desktop is disconnected ##### Prepare a long task ##### Limits while Desktop is disconnected ##### Handle requests that arrive while you are away ##### Reconnect after sleep or a network loss ##### Reopen a session after you quit Desktop
The whole hunk
from line 40, old and new numbered
/
from line 40
4040
4141Before you send your first message, configure four things in the prompt area:
4242
43* **Environment**: choose where Claude runs. Select **Local** for your machine, **Cloud** for a [cloud session](#cloud-sessions) that continues after you close the app, an [**SSH connection**](#ssh-sessions) for a remote machine you manage, or on Windows a [**WSL distribution**](/docs/en/desktop-wsl). See [environment configuration](#environment-configuration).
43* **Environment**: choose where Claude runs. Select **Local** for your machine, **Cloud** for a [cloud session](#cloud-sessions) that continues after you close the app, an [**SSH connection**](#ssh-sessions) for a remote machine you manage, or on Windows a [**WSL distribution**](/docs/en/desktop-wsl). A task in an SSH session can [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. See [environment configuration](#environment-configuration).
4444* **Project folder**: select the folder or repository Claude works in. For cloud sessions, you can add [multiple repositories](#run-long-running-tasks-in-the-cloud).
4545* **Model**: pick a [model](/docs/en/model-config#available-models) from the dropdown next to the send button. You can change this during the session.
4646* **Permission mode**: choose how much autonomy Claude has from the [mode selector](#choose-a-permission-mode). You can change this during the session.
from line 200
200200
201201### Run commands in the terminal
202202
203The integrated terminal lets you run commands alongside your session without switching to another app. Click **Terminal** in the session's title bar or press **Ctrl+\`** on macOS or Windows. The terminal opens in your session's working directory and shares the same environment as Claude, so commands like `npm test` or `git status` see the same files Claude is editing. To open a second terminal tab, click **+** in the terminal pane header or right-click a folder in the chat to choose **Open in terminal**. The terminal is available in local and [SSH](#ssh-sessions) sessions.
203The integrated terminal lets you run commands alongside your session without switching to another app. Click **Terminal** in the session's title bar or press **Ctrl+\`** on macOS or Windows. The terminal opens in your session's working directory and shares the same environment as Claude, so commands like `npm test` or `git status` see the same files Claude is editing. To open a second terminal tab, click **+** in the terminal pane header or right-click a folder in the chat to choose **Open in terminal**.
204204
205The terminal is available in local and [SSH](#ssh-sessions) sessions, with a limit on [Windows remote machines](#windows-remote-machines).
206
205207### Open and edit files
206208
207209Click a file path in the chat or diff viewer to open it in the file pane. HTML, PDF, image, and video paths open in the [Browser pane](#preview-your-app) instead. Make spot edits and click **Save** to write them back. If the file changed on disk since you opened it, the pane warns you and lets you override or discard. Click **Discard** to revert your edits, or click the path in the pane header to copy the absolute path.
from line 404
402404
403405See [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.
404406
407<Note>
408 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.
409</Note>
410
405411### Continue in another surface
406412
407413To continue a session somewhere else, open the session menu from the caret beside the session title or from the session's row in the sidebar, then select **Open in**:
from line 682
676682
677683* **Local**: runs on your machine with direct access to your files
678684* **Cloud**: runs on Anthropic-managed infrastructure by default. Sessions continue even if you close the app.
679* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers
685* **SSH**: runs on a remote machine you connect to over SSH, such as your own servers, cloud VMs, or dev containers. A running task can [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.
680686* **WSL** (Windows): runs inside a [WSL 2 distribution](/docs/en/desktop-wsl) on your machine, using its Linux toolchain and native paths
681687
682688### Local sessions
from line 728
722728
723729Once added, the connection appears under **SSH** in the environment dropdown. Select it to start a session on that machine. Claude runs on the remote machine with access to its files and tools.
724730
725The remote machine must run Linux or macOS. 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.
731The 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.
726732
727733#### Remote machine requirements for SSH sessions
728734
from line 782
776782
777783`ssh` uses the first value it finds for a host, so keep the entry above any `Host *` entry that sets `ConnectTimeout`. To confirm, run `ssh -G devbox` in a terminal on your computer. Its output includes `connecttimeout 120`. After you change the value, quit and reopen Desktop.
778784
785#### Windows remote machines
786
787A Windows remote machine requires Claude Desktop v2.31226.0 or later.
788
789Use Microsoft's OpenSSH Server. The machine can be x64 or ARM64. The shell that the SSH server starts can be `cmd.exe`, Windows PowerShell 5.1, or Git Bash.
790
791Windows remote machines get less testing than Linux ones. Try your own work there before you rely on it.
792
793Expect these limits, among others, on a Windows remote machine:
794
795* **Terminal**: the [terminal](#run-commands-in-the-terminal) doesn't open in a session whose folder is a Windows path, such as `C:/projects/app`
796* **Sandbox**: Claude Code runs there on native Windows, where it runs commands unsandboxed. See [where the sandbox runs](/docs/en/sandboxing).
797* **Plugins**: Desktop doesn't copy a plugin that holds a file or folder name Windows can't store, such as a name with `:`. The session lists the plugins that Desktop left out.
798* **MCP servers**: on some Windows remote machines, Claude's calls to MCP servers from `claude_desktop_config.json` go through Desktop, so Claude can't call their tools [while Desktop is disconnected](#limits-while-desktop-is-disconnected). Before Claude Desktop v2.37337.0, this holds on every Windows remote machine.
799* **Worktrees**: worktrees go in `<project-root>/.claude/worktrees/`. If you [choose another folder](#choose-where-ssh-session-worktrees-go), Desktop ignores it.
800* **Earlier messages**: if the SSH server's shell is `cmd.exe` or Windows PowerShell, you may have to connect before you see a session's earlier messages
801* **Forks**: if the SSH server's shell is `cmd.exe` or Windows PowerShell, you can fork a session only at its first message
802* **Running while disconnected**: a task [keeps running while Desktop is disconnected](#keep-a-task-running-while-desktop-is-disconnected) only if the SSH server lets a program outlive the connection that started it. To find out, [test the remote machine](#prepare-a-long-task).
803* **Leftover processes**: after a session ends, check the machine for programs that Claude Code started, because they can keep running. The [background helper](#keep-a-task-running-while-desktop-is-disconnected) that Desktop installs doesn't stop on its own there.
804
805#### Keep a task running while Desktop is disconnected
806
807If your computer sleeps, you lose your network, or you quit Desktop, the task goes on until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected). Closing the lid counts as sleep. A restart of Desktop or of your computer, including for an update, counts as a quit.
808
809Claude 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.
810
811<Warning>
812 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.
813
814 The work done so far stays on the remote machine, and you can continue with a message when you return.
815
816 If the task must run through the night:
817
818 * [Keep your computer awake](/docs/en/desktop-scheduled-tasks#how-scheduled-tasks-run) and online, with the lid open and Desktop running
819 * 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.
820
821 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.
822</Warning>
823
824* **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).
825* **After a quit, with Desktop on macOS or Linux and a Claude account**: you get the running task back if Desktop can [rejoin the process](#reopen-a-session-after-you-quit-desktop). If it can't, the task stops. If it stays stopped, send a message.
826* **After a quit, with Desktop on Windows or a [third-party provider](/docs/en/third-party-integrations)**: you lose the running task, because Desktop ends the process when the session opens. Send a message to continue.
827
828When you come back and the task isn't done, check for word that Desktop can't reconnect, an authentication error, or a waiting request:
829
830* **Desktop can't reconnect**: the session says why, and a notification may say so too. Desktop may [need you to log in](#reconnect-after-sleep-or-a-network-loss).
831* **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).
832* **Waiting request**: [answer it](#handle-requests-that-arrive-while-you-are-away)
833* **None of these**: send a message to continue
834
835<a id="prepare-a-long-task" />
836
837##### Prepare a long task
838
839* **Update first**: update Desktop before you start a long task. On macOS and Windows, Desktop can restart on its own to install an update that it has downloaded. That restart waits while Claude is working on an SSH task. On macOS with a Claude account, by default the restart can go ahead anyway once the update has waited 72 hours.
840* **Don't quit Desktop**: if Desktop runs on Windows or uses a third-party provider, leave it open while the long task runs. After a quit, it [ends the running task](#reopen-a-session-after-you-quit-desktop) when the session opens. Leaving it open doesn't protect a request that [waits for you](#handle-requests-that-arrive-while-you-are-away).
841* **Reduce requests**: choose a permission mode, rules, or hooks that [make the task wait for you less often](#handle-requests-that-arrive-while-you-are-away)
842* **Check the jump host**: if your jump host asks for a sign-in, for example a push to a phone, switch to a login that works without a prompt. Otherwise Desktop can send another push each time it tries to reconnect.
843* **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).
844* **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
845
846<a id="limits-while-desktop-is-disconnected" />
847
848##### Limits while Desktop is disconnected
849
850A 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:
851
852* **Sign-in token or credential**: with a Claude account, the task stops with an authentication error when the token expires. With a third-party provider, the same holds for a credential that expires, such as one from single sign-on or a credential helper. See [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions). With a Claude account, [keep Desktop running and connected](#keep-a-task-running-while-desktop-is-disconnected) so that it can renew the sign-in.
853* **The remote machine**: if the remote machine restarts, or ends your processes when your SSH connection closes, the running task ends. Nothing starts it again while Desktop is disconnected. Linux machines where systemd-logind's `KillUserProcesses` is `yes` and applies to your user end your processes this way. To keep a task running there, ask the administrator to exempt your user, for example with `KillExcludeUsers`.
854* **Idle terminals**: some Linux remote machines log out a terminal that nobody types in for a set time (systemd-logind's `StopIdleSessionSec`). With Desktop on macOS or Linux, a session's [terminal](#run-commands-in-the-terminal) and `!` commands share Desktop's SSH connection by default. That logout then ends the connection while Desktop is connected, and the running task can end with it. Closing the terminal pane doesn't prevent it, so [keep commands out of that terminal](#prepare-a-long-task).
855* **Desktop updates**: if an update brings a new helper, Desktop replaces the helper on the remote machine at a later connection, which can end a task that still runs
856* **Long absences**: on a Linux or macOS remote machine, if Desktop doesn't connect for 30 days, the helper stops and ends every Claude Code process that runs under it. Connect before then.
857
858File edits and some tools can fail while Desktop is disconnected. If the task needs them, keep Desktop connected:
859
860* **Worktrees**: in a session that uses a [worktree](#work-in-parallel-with-sessions), Desktop checks each file edit before Claude makes it. While Desktop is disconnected, each edit waits about 30 seconds and then fails. Shell commands still run. On a Linux or macOS remote machine, [edits can keep working](#worktree-edits-while-disconnected). If you aren't sure, start the session without a worktree.
861* **Folder restrictions**: if your organization restricts which folders sessions may use, Desktop checks each file read, search, and edit, with or without a worktree. While Desktop is disconnected, each one waits up to 10 minutes and then fails.
862* **Connectors**: [connectors](#connect-external-tools) and other tools that Desktop provides run through Desktop, so while it is disconnected each call fails after about 30 seconds
863* **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
864* **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.
865
866<span id="worktree-edits-while-disconnected" />
867
868<Accordion title="When edits in a worktree keep working">
869 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.
870
871 Edits still fail in some cases, including these:
872
873 * **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
874 * **Repository location**: the repository is your home directory, a folder above it, or `~/.claude`
875 * **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
876 * **Folder restrictions**: your organization restricts which folders sessions may use
877 * **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)
878
879 A session without a worktree has no such check, unless your organization restricts which folders sessions may use.
880</Accordion>
881
882<a id="handle-requests-that-arrive-while-you-are-away" />
883
884##### Handle requests that arrive while you are away
885
886If Claude needs your approval or asks you a question while Desktop is disconnected, Claude waits on the remote machine. The wait has no time limit of its own. When Desktop rejoins the process, it shows you the request. If Desktop starts a new process instead, you lose the request.
887
888While a task waits for you, Desktop can restart on its own, for example to install an update. If Desktop runs on Windows or uses a third-party provider, you lose the request after that restart.
889
890If you lose a request, send a message to continue.
891
892To reduce how often a task stops to wait for you, and to hear from it while you are away, set up any of these before you leave:
893
894* **Auto mode**: choose [Auto mode](#choose-a-permission-mode) if [it is available to you](#auto-mode-availability). After repeated blocks, you are [asked again](/docs/en/permission-modes#when-auto-mode-falls-back).
895* **Allow rules**: in your user settings file on the remote machine, `~/.claude/settings.json`, add [allow rules](/docs/en/permissions#manage-permissions) for the commands the task needs. If your organization [accepts permission rules from managed settings only](/docs/en/settings-reference#allowmanagedpermissionrulesonly), ask your administrator to add them to the [managed settings](#managed-settings) that reach the remote machine. For allow rules in a project's `.claude/settings.json`, see [Project allow rules and workspace trust](/docs/en/permissions#project-allow-rules-and-workspace-trust).
896* **A hook that answers**: configure a [`PermissionRequest` hook](/docs/en/hooks#permissionrequest) in `~/.claude/settings.json` on the remote machine to allow or deny requests in your place
897* **A hook that alerts you**: configure a [`Notification` hook](/docs/en/hooks#notification) with the `permission_prompt` matcher in the same file to send yourself a message when a request is waiting
898* **A hook that tells you when Claude is done**: configure a [`Stop` hook](/docs/en/hooks#stop) in the same file to send yourself a message when Claude has finished responding. It doesn't run when an API error ends the turn. For that case, configure a [`StopFailure` hook](/docs/en/hooks#stopfailure).
899
900If your organization [runs managed hooks only](/docs/en/settings-reference#allowmanagedhooksonly), ask your administrator to add the hook to the [managed settings](#managed-settings) that reach the remote machine.
901
902Claude 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.
903
904<a id="reconnect-after-sleep-or-a-network-loss" />
905
906##### Reconnect after sleep or a network loss
907
908If 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.
909
910* **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.
911* **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.
912
913<Accordion title="If a jump host asks for a sign-in, the outage is long, output is missing, or the process is gone">
914 - **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.
915 - **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).
916 - **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.
917 - **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.
918 - **Process gone**: if the process is gone when Desktop reconnects, Desktop can start a new one from the conversation's saved history and tell Claude to continue the task. Desktop doesn't continue the task on its own if the process keeps ending, or if Desktop uses a third-party provider. Send a message to continue.
919</Accordion>
920
921<a id="reopen-a-session-after-you-quit-desktop" />
922
923##### Reopen a session after you quit Desktop
924
925After you quit Desktop, the task keeps running on the remote machine until it finishes, needs you, or reaches one of the [limits](#limits-while-desktop-is-disconnected).
926
927* **Desktop on macOS or Linux, with a Claude account**: start Desktop and open the session. You get the running task back when Desktop can rejoin the process. It can't always rejoin, for example after some Desktop updates or after your organization changes its managed settings.
928* **On macOS or Linux, when Desktop can't rejoin**: Desktop ends the process and starts a new one from the conversation's saved history. Your running task stops, and you lose any approval or question that was waiting for you. After an update, Desktop can then tell Claude to continue. If the task stays stopped, send a message.
929* **Desktop on Windows, or with a third-party provider on any platform**: start Desktop again only when you expect the task to be done. You don't get the running task back, because Desktop never rejoins after a quit. It ends the process when the session opens, which can happen as Desktop starts. Send a message to continue.
930
931For third-party deployments, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
932
933<Warning>
934 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.
935</Warning>
936
779937#### Choose where SSH session worktrees go
780938
781939Unless your organization restricts which folders sessions may use, new SSH sessions create their [worktrees](#work-in-parallel-with-sessions) in the first of these that is set:
from line 942
7849422. [`worktree.location`](/docs/en/settings-reference#worktree-location) in `~/.claude/settings.json` on the remote machine
7859433. `<project-root>/.claude/worktrees/`, the default
786944
787Each 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.
945Each 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.
788946
789947To set **Worktree folder** on a connection you added earlier or one your organization manages, hover over it in the environment dropdown and click the gear icon.
790948
No line in this hunk matches that.