Desktop application

• Review and comment on diffs, then watch the resulting PR through CI
• Preview your running app in the Browser pane while Claude verifies its own changes, and open external sites alongside it
• Watch Claude run and test your iOS app in the iOS Simulator pane
• Arrange panes for the chat, diff, browser, terminal, and file editor side by side
• Ask a side question that uses the session’s context without derailing it
• Let Claude check on, message, or archive your other sessions
• Connect external tools like GitHub, Slack, and Linear
• Let Claude open apps and control your screen
• Run on your machine, in the cloud, or over SSH

​

Start a session

• Environment: use the environment selector, the first control in the row, to choose where Claude runs. See environment configuration.
  • If a new session has no environment selector under the prompt box, follow the earlier layout’s steps.
• Project folder: click the project folder control, next to the environment selector, to choose the folder Claude works in.
  • Cloud session: select repositories instead of a folder
  • Saved local or SSH environment: the environment already holds its folders, so the row shows no project folder control. To change the folders, edit the environment.
• Permission mode: use the mode selector to choose how much autonomy Claude has. You can change the permission mode during the session.
• Model: pick a model from the model picker toward the right end of the row. You can change the model during the session.

​

Work with code

​

Use the prompt box

​

Accept a suggested prompt

• Use the suggestion: press Tab or Right arrow to place it in the prompt box, edit it if you want, then press Enter to send it. Pressing Enter before you accept the suggestion doesn’t send it.
• Write your own prompt: start typing. The suggestion shows only while the prompt box is empty and has no attached files.

​

Add files and context to prompts

• @mention files: type @ followed by a filename to add a file to the conversation context.
  • In a cloud session: @ can list files only after you send your first message. If @ lists none, send your first message without the file, then @mention the file in your next message.
• Attach files: attach images, PDFs, and other files to your prompt from the + button next to the prompt box, or drag and drop files directly into the prompt. This is useful for sharing screenshots of bugs, design mockups, or reference documents.
  • In a WSL session: if the + menu shows Add image instead of Add files or photos, you can attach only images. To give Claude any other file from the session’s folder, @mention it.

​

Choose a permission mode

​

Auto mode availability

​

Preview your app

• Interact with your running app directly in the Browser pane
• Watch Claude verify its own changes automatically: it takes screenshots, inspects the DOM, clicks elements, fills forms, and fixes issues it finds
• Start or stop servers, or stop them all at once, from the Dev servers menu in the Browser pane’s header
• Choose whether the Browser keeps cookies after you quit the app with Keep cookies in the Browser pane’s ⋮ menu, so you don’t have to sign in again during development

​

Browse external sites

• Safety classifiers review Claude’s write actions on external pages, such as clicking and typing, in every permission mode. These are the same classifiers auto mode uses, and when they flag an action, you get a permission prompt regardless of mode.
• In permission modes other than Auto and Bypass permissions, a domain allowlist check also applies before Claude navigates to a new site.

​

Approve Claude’s actions on a site

​

Choose between the Browser and the Chrome extension

​

Restrict external browsing for your organization

​

Review changes with diff view

• macOS: press Cmd+Enter
• Windows: press Ctrl+Enter

​

Review your code

• Click Walk through in diff to open the diff view and step through the findings one at a time. A finding in the current diff appears at its line, where you can click Fix this one or dismiss it.
• Click Apply fixes to ask Claude to fix the findings that are still open.

​

Monitor pull request status

• Auto-fix: in a local session, Claude also addresses new review comments that someone other than you leaves. The comment’s author has to be the repository’s owner, an organization member, a collaborator, or a GitHub App.
• Merge when ready: turns on GitHub’s auto-merge for the PR. In a local session, Desktop requests a squash merge unless the base branch uses a merge queue.
  • In SSH and WSL sessions: Merge when ready is disabled, so turn on auto-merge for the pull request on GitHub
  • If the repository doesn’t allow auto-merge: Merge when ready doesn’t turn on, so enable auto-merge in your GitHub repository settings first
• Earlier layout: once the session has a pull request, click CI on its status bar.

​

Arrange your workspace

​

See session details

​

Hide or show the session details panel

​

Run commands in the terminal

​

Open and edit files

• Local sessions: you can edit files inside the session’s working directory, except some view-only ones such as .mcp.json and .claude/settings.json. To change one, open it in another app.
• Cloud, SSH, and WSL sessions: the file pane is view-only, so ask Claude to make edits.

​

Save edits in the file pane

​

Open files in other apps

• Attach as context: add the file to your next prompt
• Open in: open the file in an installed editor such as VS Code, Cursor, or Zed
• Show in Finder on macOS, Show in Explorer on Windows: open the containing folder
• Copy path: copy the absolute path to your clipboard

​

Switch view modes

​

Keyboard shortcuts

• Cmd+Option: press Alt
• Cmd: press Ctrl

​

Check usage

​

Let Claude use your computer

​

When computer use applies

• If you have a connector for a service, Claude uses the connector.
• If the task is a shell command, Claude uses Bash.
• If the task is browser work and you have Claude in Chrome set up, Claude uses that.
• If the task is running or testing an iOS app, Claude uses the iOS Simulator pane, which doesn’t use screen control.
• If none of those apply, Claude uses computer use.

​

Enable computer use

​

App permissions

• Denied apps: add apps here to reject them without prompting. Claude may still affect a denied app indirectly through actions in an allowed app, but it can’t interact with the denied app directly.
• Unhide apps when Claude finishes: when computer use isn’t running in the background, Claude hides your other windows while it works so it interacts with only the approved app. When Claude finishes, hidden windows are restored unless you turn this setting off.

​

Manage sessions

​

Work in parallel with sessions

​

Run a session in its own worktree

• With a saved environment: set Worktree when you create or edit the environment
• Earlier layout: select the worktree checkbox beside the branch name, above the prompt box

• Local sessions: set Worktree location in Settings > Claude Code
• SSH sessions: set Worktree folder on the SSH connection

​

Add folders to a session

• Before a local session starts: add the folders under Folders when you create a saved environment or edit one, then start the session from that saved environment.
• While a local or SSH session runs: click + next to the prompt box and select Add folder. Claude works in that folder itself, with no worktree.

​

Archive a session

​

Keep uncommitted changes when a session is archived

• If Desktop asks about the changes: select Archive anyway to discard them, or cancel and commit them
• If the only changes are untracked files: commit the ones you want to keep before a pull request that Claude opened in the session merges, because Desktop can then delete them without asking
• In any other case: the worktree stays on disk with its changes. For a local session, Desktop removes both about 30 days after the session is archived or you last open it, whichever is later. To keep the changes, open the session from the Archived tab and select Unarchive

​

Organize and find sessions

• Current layout: hover over a heading in the session list to show the Group and sort icon, then click it. To find archived sessions, select View all, the menu’s last row, then open the Archived tab.
• Earlier layout: the Filter icon shows without hovering. Click it to arrange the list with Group by or Sort by. To show archived sessions, select Status, then Archived.

​

Check and free up context

​

Get notified when a session finishes

​

Ask a side question without derailing the session

​

Watch background tasks

​

Work across sessions

• You get an approval card before Claude archives a session, except in Auto mode and Bypass permissions mode, where Claude can archive a session without one. To be asked, switch to Manual.
• Through this surface, Claude can’t send cross-session messages from a session nobody is watching, such as a scheduled-task run, and can’t deliver messages into one.
• Claude Code checks each message from this surface against the receiving session’s inbound controls, even when the receiving session doesn’t have cross-session messaging itself. If you set crossSessionInbound to refuse in the receiving session, Claude Code drops messages from this surface. Claude Code reports the refusal to the Claude desktop app. Before v2.1.234, Claude Code dropped every message from this surface to a receiving session without cross-session messaging.
• Claude Code quotes each incoming message and attributes it to the session that sent it, and Claude still follows the receiving session’s own permission settings when acting on one.

​

Run long-running tasks in the cloud

• Current layout: in the row under the prompt box, once you select a cloud environment.
• Earlier layout: above the prompt box. To add another repository, click + beside the selected one.

​

Continue in another surface

• Select Cloud to continue the session as a cloud session, with your conversation carried over as a summary. Before you confirm, the dialog states whether your files move too and whether this session is archived once the cloud one is ready. You can’t move a session that runs over SSH or in WSL this way.
• Select an installed editor or your file manager to open the session’s folder on disk there.

​

Control which sessions appear on your other devices

• You turn it on for that session: with the session’s Remote Control switch, or by typing /remote-control in its prompt box.
• It connects when it starts: new sessions connect automatically while Connect new sessions to Remote Control is on in Settings > Claude Code. If you’ve never changed that setting, Desktop follows remoteControlAtStartup in your user or managed settings, then your organization’s default.

• One session: turn off its Remote Control switch. In a session that connected when it started, typing /remote-control leaves Remote Control on and shows Remote Control is already on. This session connected automatically when it started. Click Turn off on that line to disconnect.
• New Desktop sessions on this computer: turn off Connect new sessions to Remote Control in Settings > Claude Code. If it already shows off, turn it on and then off so Desktop saves your choice. Once saved, it takes precedence over remoteControlAtStartup and the defaults.
• Any session on this computer, including the CLI: set disableRemoteControl to true in ~/.claude/settings.json to stop sessions from connecting. A session that was already connected when you saved the file stays connected until you turn Remote Control off for it.

​

Sessions from Dispatch

​

Extend Claude Code

​

Connect external tools

​

Use skills

​

Install plugins

​

Configure preview servers

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

​

Auto-verify changes

{
  "version": "0.0.1",
  "autoVerify": false,
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 3000
    }
  ]
}

​

Configuration fields

When to use program vs runtimeExecutable

Open the preview at a specific URL

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "port": 8443,
      "url": "https://localhost:8443"
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "my-app",
      "url": "https://app.localhost:3000"
    }
  ]
}

​

Port conflicts

• true: Claude finds and uses a free port automatically. Suitable for most dev servers.
• false: Claude fails with an error. Use this when your server must use a specific port, such as for OAuth callbacks or CORS allowlists.
• Not set (default): your server gets the next free port, as with true, except in the one case below. Before Claude Desktop v2.37337.0, Claude asks whether the server needs that exact port instead, then saves your answer in launch.json.

• You start the server through an npm, yarn, pnpm, or bun script.
• Your preferred port is hardcoded in that script, or Claude can’t inspect the script.
• You don’t pass the port in runtimeArgs.

​

Examples

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "web",
      "runtimeExecutable": "yarn",
      "runtimeArgs": ["dev"],
      "port": 3000
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "frontend",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "apps/web",
      "port": 3000,
      "autoPort": true
    },
    {
      "name": "api",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "start"],
      "cwd": "server",
      "port": 8080,
      "env": { "NODE_ENV": "development" },
      "autoPort": false
    }
  ]
}

{
  "version": "0.0.1",
  "configurations": [
    {
      "name": "server",
      "program": "server.js",
      "args": ["--verbose"],
      "port": 4000
    }
  ]
}

​

Environment configuration

• Local: runs on your machine with direct access to your files
• Cloud: runs on Anthropic-managed infrastructure by default. Sessions continue even if you close the app.
• 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, but with a Claude account it can stop when its sign-in expires.
• WSL (Windows): runs inside a WSL 2 distribution on your machine, using its Linux toolchain and native paths

​

Create a saved environment

​

Environments that Desktop creates for you

​

Use, edit, or remove a saved environment

• Start a session: select the entry.
• Edit or delete: hover over the entry and click the gear icon. To delete a local or SSH environment, click Delete environment in Edit environment.
• Archive cloud environments: see Archive an environment.

​

Local sessions

​

Set environment variables for local sessions

​

Set environment variables for dev servers

• macOS and Linux: export it in your shell profile
• Windows: add it to your user or system environment variables
• Any platform: save it in the local environment editor, if you can open it

​

Use the local environment editor

• Selector under the prompt box: hover over the entry for your computer, the first under Local. If a gear icon appears, click it. If not, the editor isn’t available, so set the variable for local sessions or dev servers another way.
• Selector above the prompt box: hover over Local and click the gear icon

​

Environment variables Desktop sets itself

• API_TIMEOUT_MS: a local session gets 900000, which is 15 minutes. For a longer timeout, install the Claude Code CLI and use it instead of Desktop. Set the variable in your shell and run claude in your terminal.
• ANTHROPIC_BASE_URL: a local session gets Anthropic’s API host when you’re signed in with a Claude account. To use a gateway, set up Desktop’s third-party inference configuration instead.

​

Turn off extended thinking

​

Fixed thinking budgets

​

Local sessions on managed devices

​

Cloud sessions

• Add an environment: select New environment at the bottom of the selector’s menu, then the Cloud tab of the New environment dialog
• Edit or archive one of your own environments: hover over it and click the gear icon

​

SSH sessions

​

Remote machine requirements for SSH sessions

• System: an x86_64 or arm64 processor. The machine also has to meet Claude Code’s system requirements. On Linux, Claude Code needs glibc 2.17 or later, or musl. To see which one the machine has, run ldd --version there. On a musl-based distribution such as Alpine Linux, also install the packages that Claude Code needs.
• SFTP: the SSH server has to offer the SFTP subsystem, which a Subsystem sftp line in its sshd_config turns on. To check, connect to the same host and port with sftp in a terminal on your computer. A working server shows the sftp> prompt.
• Sessions per connection: Desktop on macOS and Linux opens several sessions on one SSH connection. If the server’s sshd_config sets MaxSessions 1, raise it, for example to OpenSSH’s default of 10.
• Install folder: Desktop installs a helper program and Claude Code under ~/.claude/remote/ in your home directory. It runs them from there, so that folder can’t be on a file system mounted noexec. Allow about 1 GB of disk space in the home directory of each user who connects. For what that folder holds, see Files and processes on the remote machine.
• Shell: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and sh do
• Network: Claude Code runs on the remote machine and makes its network requests from there, so the machine needs the network access that Claude Code requires. If the machine can’t download Claude Code, Desktop downloads it on your computer and uploads it. Claude Code’s other requests still go out from the remote machine. On a Linux remote machine, if those requests need a proxy, set it for SSH sessions.

​

Set a proxy or a CA certificate for SSH sessions

{
  "env": {
    "HTTPS_PROXY": "http://proxy.example.com:8080",
    "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"
  }
}

Find a proxy or CA variable set elsewhere on the remote machine

​

Use your SSH configuration on macOS and Linux

• Client version: run ssh -V. The client has to be OpenSSH 7.6 or later.
• Entry: run ssh with the Host name, such as ssh devbox. If that fails, fix the entry first.

• SSH port: a value here overrides the entry’s Port
• SSH key (optional): Desktop offers the key file you pick in addition to the entry’s IdentityFile and the keys in your SSH agent

Reach a machine behind a jump host

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com

Reach a container on a remote machine

Host devbox-container
  User dev
  ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i

Use variables from your shell in a ProxyCommand

Use AWS credentials in a ProxyCommand

[profile corp]
region = us-east-1
credential_process = /full/path/to/your-credential-helper

Host i-*
  ProxyCommand sh -c "aws ssm start-session --profile corp --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

Raise the SSH connection timeout

Host devbox
  HostName devbox.internal.example.com
  User alice
  ProxyJump bastion.example.com
  ConnectTimeout 120

Fix a Match host block that only Desktop applies

ssh -G -o HostName=devbox.internal.example.com -l alice devbox

Match host *.internal.example.com !originalhost devbox

Forwarding settings that Desktop leaves off

• To reach a port on the remote machine: forward it yourself
• To use your own keys from the remote machine: set up a credential on the remote machine itself, for example for git push

​

Reach a port on the remote machine

ssh -N -L 3000:localhost:3000 devbox

​

Windows remote machines

• Terminal: the terminal doesn’t open in a session whose folder is a Windows path, such as C:/projects/app
• Sandbox: Claude Code runs there on native Windows, where it runs commands unsandboxed. See where the sandbox runs.
• 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.
• 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. Before Claude Desktop v2.37337.0, this holds on every Windows remote machine.
• Worktrees: worktrees go in <project-root>/.claude/worktrees/. If you choose another folder, Desktop ignores it.
• 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
• Forks: if the SSH server’s shell is cmd.exe or Windows PowerShell, you can fork a session only at its first message
• Running while disconnected: a task keeps 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.
• Leftover processes: after a session ends, check the machine for programs that Claude Code started, because they can keep running. The background helper that Desktop installs doesn’t stop on its own there.

​

Keep a task running while Desktop is disconnected

• After sleep or a network loss: you get the running task back if the process still runs and Desktop can log in without a prompt. If it can’t, send a message.
• 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 before you quit. If you lost the task, send a message to continue.

• Desktop can’t reconnect: the session says why, and a notification may say so too. Desktop may need you to log in.
• Authentication error: the sign-in token or credential 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.
• Waiting request: answer it
• None of these: send a message to continue

Prepare a long task

• 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.
• Don’t quit on Windows, or before v2.42304.0 with a third-party provider: after a quit there you lose the running task, so leave Desktop open during the task. In any other case, see what you get back before you quit.
• Reduce requests: choose a permission mode, rules, or hooks that make the task wait for you less often
• 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.
• 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.
• Keep commands out of Desktop’s terminal: if the remote machine logs out idle terminals, run your own commands from an SSH login outside Desktop

Limits while Desktop is disconnected

• 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. With a Claude account, keep Desktop running and connected so that it can renew the sign-in.
• 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.
• 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 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.
• 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
• 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.

• Worktrees: in a session that uses a worktree, 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. If you aren’t sure, start the session without a worktree.
• 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.
• Connectors: connectors and other tools that Desktop provides run through Desktop, so while it is disconnected each call fails after about 30 seconds
• Workflows: Desktop checks each new workflow before it starts, so while Desktop is disconnected a new one waits up to 10 minutes and then fails
• 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. Otherwise, and on some Windows remote machines, Claude can’t call their tools while Desktop is disconnected.

Handle requests that arrive while you are away

• Auto mode: choose Auto mode if it is available to you. After repeated blocks, you are asked again.
• Allow rules: in your user settings file on the remote machine, ~/.claude/settings.json, add allow rules for the commands the task needs. If your organization accepts permission rules from managed settings only, ask your administrator to add them to the managed settings that reach the remote machine. For allow rules in a project’s .claude/settings.json, see Project allow rules and workspace trust.
• A hook that answers: configure a PermissionRequest hook in ~/.claude/settings.json on the remote machine to allow or deny requests in your place
• A hook that alerts you: configure a Notification hook with the permission_prompt matcher in the same file to send yourself a message when a request is waiting
• A hook that tells you when Claude is done: configure a Stop hook 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.

Reconnect after sleep or a network loss

• 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.
• 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.

Reopen a session after you quit Desktop

• Desktop on Windows: you don’t get the running task back, because Desktop never rejoins after a quit. Start Desktop again only when you expect the task to be done, because the session can open as Desktop starts.
• Third-party provider, task from an earlier version: if you started the task in a Desktop version before v2.42304.0, you don’t get it back on macOS or Linux either. Start Desktop again only when you expect the task to be done.
• Any other task, with Desktop on macOS or Linux: start Desktop and open the session, and the task goes on if Desktop rejoins. It can’t always rejoin, for example after some Desktop updates, so update before a long task.

​

Choose where SSH session worktrees go

1. Worktree folder on the SSH connection
2. worktree.location in ~/.claude/settings.json on the remote machine
3. <project-root>/.claude/worktrees/, the default

Set the worktree folder on an existing connection

​

Files and processes on the remote machine

• Helper: one or more server processes for each computer that connects
• Claude Code: the processes that the helper starts for the user’s sessions, each from a file named after its version, such as 2.1.295-…

End one session’s process

See which user the processes run as

See who connected to the remote machine

​

Connections that close before login

Recognize a test in the SSH server’s log

Check whether the SSH server itself refuses the address

drop connection #0 from [203.0.113.7]:51234 on [192.0.2.10]:22 penalty: connections without attempting authentication

Check whether fail2ban counts Desktop’s tests

• A filter line that names a mode in brackets, such as filter = sshd[mode=aggressive]: use that mode.
• Only the stock filter line, with [mode=%(mode)s]: use the mode line, or normal if there is none.

fail2ban-regex -o ip lines.log "sshd[mode=aggressive]"

Prevent a ban by fail2ban

• mode: set it to normal wherever your jail sets it, in a mode line or in the brackets of a line such as filter = sshd[mode=aggressive]. You give up every count that only the other modes make, for example of clients that connect and leave without trying to log in.
• ignoreip: set it to the addresses that people connect from, for example ignoreip = 203.0.113.7. fail2ban then counts nothing from those addresses, failed logins included.

​

Use MCP servers set up on the remote machine

​

Open an SSH session from a link

claude://code/new?ssh_host=dev%40build.example.com&ssh_port=2222&ssh_folder=/srv/payments&q=Investigate%20the%20failed%20deploy

• A connection you already have: if the host, user, and port match one of your connections, Desktop asks whether to use it, and shows you the connection’s name and host, and the folder if the link names one.
• A new connection: otherwise Desktop opens the dialog for adding an SSH connection. When you add the connection, Desktop asks whether to connect before it saves anything, and shows you the host from the link, and the port and folder if the link names them.

• Before you confirm: check the host and folder.
• Before you send: check the prompt and the selected environment.

• You’re signed out: sign in, then open the link again.
• Another dialog is open: close it, then open the link again.
• The link isn’t valid: Desktop shows a message that says what to fix, and doesn’t fill in the prompt.
• Desktop is older than v2.110.0: earlier versions ignore the SSH parameters and open the new-session page with only the prompt.
• SSH sessions are turned off: if your administrator sets the allowlist to an empty array, Desktop refuses SSH links.

​

Pre-configure SSH connections for your team

• What users see: connections defined this way appear in each user’s environment selector automatically.
• What users can change: users can select a managed connection and set their own Worktree folder for it. They can’t edit its other fields or delete it in the app.

{
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "user@dev.example.com",
      "sshPort": 22,
      "sshIdentityFile": "~/.ssh/id_ed25519"
    }
  ]
}

​

Restrict which SSH hosts users can connect to

{
  "sshHostAllowlist": ["*.devboxes.example.com", "bastion.example.com"]
}

​

Turn off local sessions and distribute SSH connections

{
  "disableDesktopLocalSessions": true,
  "sshConfigs": [
    {
      "id": "shared-dev-vm",
      "name": "Shared Dev VM",
      "sshHost": "dev.example.com"
    }
  ],
  "sshHostAllowlist": ["dev.example.com"]
}

• The CLI: none of the keys stops a developer from running the Claude Code CLI on their own computer
• Cowork: none of the keys applies to Cowork sessions or Cowork scheduled tasks
• Cloud sessions: none of the keys changes whether cloud sessions are available. To turn them off, use the Cloud sessions setting under Admin console controls.

• Hostnames: make sure that a pattern in sshHostAllowlist matches the hostname of each sshConfigs entry, without user@, or developers can’t connect to it. For how Desktop matches a hostname, see Restrict which SSH hosts users can connect to.
• Version: disableDesktopLocalSessions requires Claude Desktop v1.37937.0 or later
• File permissions: make sure that each developer’s account on the computer can read the managed settings file. Desktop doesn’t apply the keys in a file that the account can’t read, and Claude Code starts without them too.

​

Enterprise configuration

​

Admin console controls

• Desktop: control whether users in your organization can access Claude Code in the desktop app
• Cloud sessions: enable or disable cloud sessions for your organization
• Remote Control: enable or disable Remote Control for your organization

​

Managed settings

• Local sessions on this machine: a managed settings file deployed to disk applies. Managed settings pushed remotely through the admin console also reach these sessions on Anthropic’s API when the session authenticates with an eligible login, following the same settings precedence as the terminal CLI.
• Cloud sessions: receive server-managed settings; device-deployed files don’t reach them, because they run on Anthropic-managed VMs. Sessions routed to a self-hosted environment also read the managed settings file in the runner image. How Claude Code combines managed sources says when that file applies.
• SSH sessions: the session reads the managed settings file from the remote host. Desktop itself reads sshConfigs, sshHostAllowlist, disableSshSavedPasswords, and disableDesktopLocalSessions on the local machine. If you deliver more than one managed source, it reads them from one by default.
• Cowork sessions: in a Cowork session on this machine, Claude Code never fetches admin-console settings, even when the user signs in with a Team or Enterprise account, and reads policy deployed to the machine unless your Claude Desktop configuration sets requireCoworkFullVmSandbox. Remote Cowork sessions receive neither. See where and when a policy applies for which device files reach Cowork, and MCP permission rules for how Bash and WebFetch rules apply to Cowork’s tools.

​

Device management policies

• macOS: configure via com.anthropic.claudefordesktop preference domain using tools like Jamf or Kandji
• Windows: configure via registry at SOFTWARE\Policies\Claude
• Linux: configure via a root-owned file at /etc/claude-desktop/managed-settings.json, which holds the policy keys as a JSON object. Desktop refuses the file if anyone but root can write to it or to its folder. It’s a different file from Claude Code’s managed settings file.

​

Network access requirements

anthropic.com
*.anthropic.com
claude.ai
*.claude.ai
claude.com
*.claude.com
claude.app
*.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

anthropic.com
api.anthropic.com
a-api.anthropic.com
a-cdn.anthropic.com
s-cdn.anthropic.com
assets-proxy.anthropic.com
claude.ai
a.claude.ai
assets.claude.ai
downloads.claude.ai
*.livepreview.claude.ai
claude.com
platform.claude.com
*.livepreview.claude.app
*.claudeusercontent.com
*.claudemcpcontent.com

​

Authentication and SSO

​

Data handling

​

Deployment

• macOS: distribute via MDM such as Jamf or Kandji using the .dmg installer
• Windows: deploy via the MSIX package. See Deploy Claude Desktop for Windows for enterprise deployment options including silent installation

​

Coming from the CLI?

claude --desktop --resume <session-id>

1. Close the session in the terminal.
2. In the Desktop prompt box, type /resume. Desktop lists the sessions you started from the CLI on this computer. Search by title, folder, or branch, and preview where each one left off.
3. Select the session. It continues in the app with its full conversation and context.

​

CLI flag equivalents

​

Shared configuration

• CLAUDE.md and CLAUDE.local.md files in your project are used by both
• MCP servers configured in ~/.claude.json or .mcp.json work in both
• Hooks and skills defined in settings apply to both
• Settings in ~/.claude.json and ~/.claude/settings.json are shared. Permission rules, allowed tools, and other settings in settings.json apply to Desktop sessions.
• Models: the same models are available in both. In Desktop, select the model from the model picker in the row under the prompt box. You can change the model mid-session from the same picker.

​

MCP servers from the Claude Desktop chat app

​

Feature comparison

​

What’s not available in Desktop

• Third-party providers: Desktop connects to Anthropic’s API by default. To route Desktop through a gateway, or to run the Code tab on Amazon Bedrock, Google Cloud’s Agent Platform, Microsoft Foundry, or a self-hosted LLM gateway, follow the links in the Third-party providers row.
• Linux (beta): Computer Use isn’t yet available in the Linux desktop app. See Claude Desktop on Linux.
• Inline code suggestions: Desktop doesn’t offer autocomplete-style code completions. It works through conversational prompts and explicit code changes, and can suggest your next prompt after Claude replies.
• Agent teams: coordinated teams, where Claude as the team lead assigns tasks to teammates from a shared task list, are available in the CLI, not in Desktop. For multi-agent work inside one session, use dynamic workflows, which run in Desktop; Claude can also message and manage your other sessions directly.
• Terminal-dialog commands: built-in commands that open an interactive panel in the terminal behave differently in the Code tab. Edit settings files directly to manage permission rules and configuration, or run the commands from the standalone CLI.
  • Commands with no argument form, such as /permissions, reply with isn't available in this environment.
  • /config opens Settings → Claude Code. Text after the command is ignored, so /config theme=dark doesn’t set the theme.

​

Troubleshooting

​

Check your version

• macOS: click Claude in the menu bar, then About Claude
• Windows: click Help, then About Claude

​

Claude Code version in the Code tab

​

Check which layout you have

• Desktop older than v2.37337.0: update to get the current layout. Select Claude > Check for Updates… on macOS or Help > Check for Updates… on Windows.
• Third-party provider: you keep the earlier layout, so there is nothing to do.

​

403 or authentication errors in the Code tab

1. Sign out and back in from the app menu. This is the most common fix.
2. Verify you have an active paid subscription: Pro, Max, Team, or Enterprise.
3. If the CLI works but Desktop does not, quit the desktop app completely, not just close the window, then reopen and sign in again.
4. Check your internet connection and proxy settings.

​

Blank or stuck screen on launch

1. Restart the app.
2. Check for pending updates. On macOS and Windows the app auto-updates on launch; on Linux, update through apt as described in Claude Desktop on Linux.
3. On a managed network, confirm your firewall allows the CDN hosts in network access requirements.
4. On Windows, check Event Viewer for crash logs under Windows Logs → Application.

​

”Failed to load session”

​

Session not finding installed tools

​

Git and Git LFS errors

​

MCP servers not working on Windows

​

SSH connection fails after you log in

​

Get Desktop’s logs for an SSH problem

• macOS: Show Logs in Finder
• Windows: Show Logs in File Explorer
• Linux: Show Logs in File Manager

​

App won’t quit

• macOS: press Cmd+Q. If the app doesn’t respond, use Force Quit with Cmd+Option+Esc, select Claude, and click Force Quit.
• Windows: use Task Manager with Ctrl+Shift+Esc to end the Claude process.

​

Windows-specific issues

• PATH not updated after install: open a new terminal window. PATH updates only apply to new terminal sessions.
• Concurrent installation error: if you see an error about another installation in progress but there isn’t one, try running the installer as Administrator.

​

”Branch doesn’t exist yet” when opening in CLI

git fetch origin <branch-name>
git checkout <branch-name>

​

Still stuck?

• Open Help → Get Support in the desktop app, or visit the Claude support center directly
• For problems that also reproduce in the standalone claude CLI, search or file a bug on GitHub Issues