Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261015T000702Z

2 pages moved out of 222 read.

Pages moved 2 significant first

Pages read 222 in this capture

Captured 15 Oct 2026 00:07 UTC

Corpus hash 7ecd0b41fc0c corpus-hash

What this read moved

1-2 of 2

desktop Changed · +164 / -2 lines

#### Set a proxy or a CA certificate for SSH sessions ##### Find a proxy or CA variable set elsewhere on the remote machine ##### Reach a container on a remote machine ##### Use AWS credentials in a `ProxyCommand` ##### Fix a `Match host` block that only Desktop applies ##### See which user the processes run as ### Get Desktop's logs for an SSH problem

from line 753

753753* **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.

754754* **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](#files-and-processes-on-the-remote-machine).

755755* **Shell**: the shell set for your account on the remote machine has to run commands sent over SSH, as Bash, Zsh, and `sh` do

756* **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](/docs/en/network-config#network-access-requirements). 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.

757757

758#### Set a proxy or a CA certificate for SSH sessions

759

760If a Linux remote machine reaches the internet through a proxy or needs a CA certificate, add the [proxy and CA variables](/docs/en/network-config) under `env` in `~/.claude/settings.json` there. Add them even if you already export them in `~/.profile`, `~/.bash_profile`, `~/.zprofile`, or `~/.zshrc` on that machine.

761

762An 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.

763

764<Steps>

765 <Step title="Add the variables">

766 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:

767

768 ```json ~/.claude/settings.json theme={null}

769 {

770 "env": {

771 "HTTPS_PROXY": "http://proxy.example.com:8080",

772 "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/example-ca.pem"

773 }

774 }

775 ```

776 </Step>

777

778 <Step title="Send your message again">

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

780 </Step>

781</Steps>

782

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

784

785Check 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):

786

787<Steps>

788 <Step title="List the variables that the remote machine sets">

789 In a terminal on your computer, run `ssh devbox env`, with your own host.

790 </Step>

791

792 <Step title="Change the variable where it is set">

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

794 </Step>

795

796 <Step title="Give sessions the new value">

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

798 </Step>

799</Steps>

800

758801#### Use your SSH configuration on macOS and Linux

759802

760803On macOS and Linux, Desktop connects by running the OpenSSH client on your computer, so it uses your `~/.ssh/config`. Connecting through the OpenSSH client requires Claude Desktop v1.37937.0 or later. Enter a `Host` name from that file in the **SSH host** field to use settings from its entry, such as `HostName`, `User`, `IdentityFile`, `CertificateFile`, `ProxyJump`, and `ProxyCommand`.

from line 825

782825

783826Enter `devbox` in the **SSH host** field.

784827

828##### Reach a container on a remote machine

829

830To 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.

831

832<Steps>

833 <Step title="Add the entry">

834 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:

835

836 ```text ~/.ssh/config theme={null}

837 Host devbox-container

838 User dev

839 ProxyCommand ssh build.example.com docker exec -i devbox /usr/sbin/sshd -i

840 ```

841 </Step>

842

843 <Step title="Prepare the container">

844 * Install the OpenSSH server, with a host key that stays the same when you rebuild the image or recreate the container

845 * Give the account named in `User` a way to log in, such as an `authorized_keys` file

846 * Check that the container meets the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions)

847 </Step>

848

849 <Step title="Check the allowlist">

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

851 </Step>

852

853 <Step title="Test the entry, then connect">

854 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:

855

856 * **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

857 * **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.

858 * **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.

859 * If it prints `Missing privilege separation directory: /run/sshd`, create that folder in the container.

860 * If it prints `no hostkeys available` and the container has host keys, add `-u root` after `exec` in this command and in the entry.

861

862 Then enter `devbox-container` in the **SSH host** field.

863 </Step>

864</Steps>

865

785866##### Use variables from your shell in a `ProxyCommand`

786867

787868To use an environment variable of your own in a `ProxyCommand` or `Match exec` command, export it in a shell startup file, such as `~/.zshrc`, then quit and reopen Desktop. When Desktop starts, it reads what your login shell exports, and it keeps those values until you quit.

from line 869

788869

789870This 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.

790871

872<Note>

873 If your shell sets temporary AWS credentials, [give the AWS CLI a profile](#use-aws-credentials-in-a-proxycommand) instead of exporting `AWS_*` variables.

874</Note>

875

876<a id="use-aws-credentials-in-a-proxycommand" />

877

878##### Use AWS credentials in a `ProxyCommand`

879

880If you set temporary AWS credentials in a shell startup file, a `ProxyCommand` that runs the AWS CLI can connect in a terminal and fail in Desktop. When your shell exports `AWS_SESSION_TOKEN`, `AWS_SECURITY_TOKEN`, or `AWS_CREDENTIAL_EXPIRATION`, `ssh` and your `ProxyCommand` in Desktop don't get the shell's AWS credentials, `AWS_REGION`, or `AWS_PROFILE`.

881

882If 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`:

883

884<Steps>

885 <Step title="Add a profile with a region and a source of credentials">

886 This example adds a profile named `corp` that gets its credentials from a helper program:

887

888 ```ini ~/.aws/config theme={null}

889 [profile corp]

890 region = us-east-1

891 credential_process = /full/path/to/your-credential-helper

892 ```

893

894 * **`region`**: give the AWS Region of the machines you connect to

895 * **`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.

896 * **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.

897 </Step>

898

899 <Step title="Name the profile in the ProxyCommand">

900 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):

901

902 ```text ~/.ssh/config theme={null}

903 Host i-*

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

905 ```

906 </Step>

907

908 <Step title="Connect again">

909 Run `ssh` with the host in a terminal to confirm that the entry still connects there, then connect from Desktop.

910 </Step>

911</Steps>

912

791913##### Raise the SSH connection timeout

792914

793915If your SSH configuration sets no `ConnectTimeout` for the host, Desktop gives `ssh` 30 seconds to connect. Through a jump host or a `ProxyCommand`, that time includes the time the route takes to connect. If your route needs longer, add a higher value to the entry:

from line 924

802924

803925`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.

804926

927If the remote machine itself waits for an approval on your phone, approve within 45 seconds, whatever `ConnectTimeout` you set. You can't raise this limit, because Desktop sets `ServerAliveInterval` and `ServerAliveCountMax` itself, and `ssh` then closes a login in which the remote machine sends nothing for that long. If a jump host or a `ProxyCommand` waits for you instead, raise `ConnectTimeout` in the remote machine's entry to cover that time.

928

929##### Fix a `Match host` block that only Desktop applies

930

931If Desktop uses a setting that `ssh devbox` in a terminal doesn't, look for a `Match host` block above the entry's `HostName` line. In a terminal, `ssh` reads a block there before the `HostName` line, so it compares the block with `devbox`. Desktop gives `ssh` the `HostName` value on the command line, so `ssh` compares the block with that value.

932

933To check, run `ssh -G` in a terminal on your computer with the entry's `HostName` and `User` values on the command line, as Desktop does:

934

935```bash theme={null}

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

937```

938

939Compare the output with that of `ssh -G devbox`. If the block's settings, such as `proxycommand`, show only in the first output, the block takes effect only in Desktop. To have Desktop skip it too, add `!originalhost devbox` to its `Match` line:

940

941```text ~/.ssh/config theme={null}

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

943```

944

945To confirm, run the first command again. The block's settings no longer show in its output.

946

805947##### Forwarding settings that Desktop leaves off

806948

807949On its connection to the remote machine, Desktop leaves `ForwardAgent`, `ForwardX11`, `LocalForward`, `RemoteForward`, `DynamicForward`, and `Tunnel` off, even where your SSH configuration turns them on. In the [terminal](#run-commands-in-the-terminal) or a `!` command, expect your forwarding settings to apply [only sometimes](#limits-while-desktop-is-disconnected), because Desktop can start a separate `ssh` there that follows them.

from line 1160

10181160 </Step>

10191161

10201162 <Step title="End the processes">

1021 Logged in as that user on the remote machine, run `kill` with each process ID that [`pgrep`](#files-and-processes-on-the-remote-machine) lists.

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

1164

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

10221166 </Step>

10231167

10241168 <Step title="Delete the folder">

from line 1176

10321176

10331177Before you archive a session that has a worktree, see [Work in parallel with sessions](#work-in-parallel-with-sessions).

10341178

1179##### See which user the processes run as

1180

1181The helper and Claude Code run as the user that Desktop logs in as over SSH. Installing and starting them takes no `sudo`. To check the user, run `ps -o user= -p` on the remote machine with a process ID that [`pgrep`](#files-and-processes-on-the-remote-machine) lists.

1182

1183Programs that Claude Code starts, such as shell commands and MCP servers, start as that user too. Review that user's rights on the remote machine, its `sudo` rules included, as you would for a person who runs commands there.

1184

10351185##### See who connected to the remote machine

10361186

10371187To find out who connected to a remote machine, read the SSH server's log on that machine, where a login from Desktop looks like one from a terminal. With Desktop on macOS or Linux, expect an entry each time Desktop connects, not one for each session.

from line 1633

14831633| `Claude Code won't start on <host>` | `[CLI_UNRESPONSIVE]` | Wait a minute, then try again. If it keeps failing, run the command that the message names on the remote machine to see whether Claude Code answers there. |

14841634

14851635For any other message, check the [remote machine requirements](#remote-machine-requirements-for-ssh-sessions).

1636

1637### Get Desktop's logs for an SSH problem

1638

1639You 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:

1640

1641* **macOS**: **Show Logs in Finder**

1642* **Windows**: **Show Logs in File Explorer**

1643* **Linux**: **Show Logs in File Manager**

1644

1645Look through the files before you send them, because they can include names and other details from your environment. `<host>` and `<user>` stand for names that Desktop replaced. Desktop doesn't replace every name, and an SSH host or user name can still appear as written. If you send the zip file to someone, tell them which host failed and when, because the logs may not name it.

1646

1647The zip file doesn't hold the log of the helper program that Desktop installs on the remote machine. To get that log as well, copy `remote-server.log` from the helper's folder under [`~/.claude/remote/run/`](#files-and-processes-on-the-remote-machine) in the home directory of the user who connected. Look through that file too before you send it.

14861648

14871649### App won't quit

14881650

claude-tag Changed · +1 / -1 lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

Nothing in the body moved in this read. What changed is above.