[BUG] Docker not found on remote host

[kwakubiney]

Describe the bug

When using docker pussh to upload an image to a remote macOS machine, the CLI returns an error:
ERROR: 'docker' command not found on remote host. Please ensure Docker is installed.
This happens even though Docker is installed and works correctly on the remote machine.

---

How to reproduce

1. On your local machine, run:

   docker pussh someimage:latest user@remote-ip
   

2. Observe the output:

• Connecting to user@remote-ip...
ERROR: 'docker' command not found on remote host. Please ensure Docker is installed.
! Cleaning up after error...

Unregistry versions

pussh version: 0.1.3

Local machine

OS: macOS 15.3.1
Bash: GNU bash, version 3.2.57(1)-release

biney@Kwakus-MacBook-Pro ~ % docker --version
Docker version 27.5.1, build 9f9e405

Client:
 Version:    27.5.1
 Context:    orbstack
 Debug Mode: false
 Plugins:
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.20.1
    Path:     /Users/biney/.docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.32.4
    Path:     /Users/biney/.docker/cli-plugins/docker-compose
  pussh: Upload image to remote Docker daemon via SSH without external registry (https://github.com/psviderski)
    Version:  0.1.3
    Path:     /Users/biney/.docker/cli-plugins/docker-pussh

Server:
 Containers: 14
  Running: 1
  Paused: 0
  Stopped: 13
 Images: 11
 Server Version: 27.5.1
 Storage Driver: overlay2
  Backing Filesystem: btrfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false
 Logging Driver: json-file
 Cgroup Driver: cgroupfs
 Cgroup Version: 2
 Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
 Swarm: inactive
 Runtimes: io.containerd.runc.v2 runc
 Default Runtime: runc
 Init Binary: docker-init
 containerd version: c507a0257ea6462fbd6f5ba4f5c74facb04021f4
 runc version: 59923ef18c98053ddb1acf23ecba10344056c28e
 init version: de40ad0
 Security Options:
  seccomp
   Profile: builtin
  cgroupns
 Kernel Version: 6.12.15-orbstack-00304-gd0ddcf70447d
 Operating System: OrbStack
 OSType: linux
 Architecture: aarch64
 CPUs: 8
 Total Memory: 7.81GiB
 Name: orbstack
 ID: 45f0ac61-53d7-4b3d-b8f6-cb9f367a5425
 Docker Root Dir: /var/lib/docker
 Debug Mode: false
 Experimental: false
 Insecure Registries:
  127.0.0.0/8
 Live Restore Enabled: false
 Product License: Community Engine
 Default Address Pools:
   Base: 192.168.97.0/24, Size: 24
   Base: 192.168.107.0/24, Size: 24
   Base: 192.168.117.0/24, Size: 24
   Base: 192.168.147.0/24, Size: 24
   Base: 192.168.148.0/24, Size: 24
   Base: 192.168.155.0/24, Size: 24
   Base: 192.168.156.0/24, Size: 24
   Base: 192.168.158.0/24, Size: 24
   Base: 192.168.163.0/24, Size: 24
   Base: 192.168.164.0/24, Size: 24
   Base: 192.168.165.0/24, Size: 24
   Base: 192.168.166.0/24, Size: 24
   Base: 192.168.167.0/24, Size: 24
   Base: 192.168.171.0/24, Size: 24
   Base: 192.168.172.0/24, Size: 24
   Base: 192.168.181.0/24, Size: 24
   Base: 192.168.183.0/24, Size: 24
   Base: 192.168.186.0/24, Size: 24
   Base: 192.168.207.0/24, Size: 24
   Base: 192.168.214.0/24, Size: 24
   Base: 192.168.215.0/24, Size: 24
   Base: 192.168.216.0/24, Size: 24
   Base: 192.168.223.0/24, Size: 24
   Base: 192.168.227.0/24, Size: 24
   Base: 192.168.228.0/24, Size: 24
   Base: 192.168.229.0/24, Size: 24
   Base: 192.168.237.0/24, Size: 24
   Base: 192.168.239.0/24, Size: 24
   Base: 192.168.242.0/24, Size: 24
   Base: 192.168.247.0/24, Size: 24

Remote machine

OS: macOS
Bash: GNU bash, version 3.2.57(1)-release

docker --version
Docker version 28.2.2, build e6534b4

docker info
Client:
Version:    28.2.2
Context:    orbstack
Debug Mode: false
Plugins:
  ai: Ask Gordon - Docker Agent (Docker Inc.)
    Version:  v0.7.3
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-ai
  buildx: Docker Buildx (Docker Inc.)
    Version:  v0.24.0
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-buildx
  compose: Docker Compose (Docker Inc.)
    Version:  v2.36.2
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-compose
  debug: Get a shell into any image or container (Docker Inc.)
    Version:  0.0.38
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-debug
  desktop: Docker Desktop commands (Beta) (Docker Inc.)
    Version:  v0.1.4
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-desktop
  dev: Docker Dev Environments (Docker Inc.)
    Version:  v0.1.2
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-dev
  extension: Manages Docker extensions (Docker Inc.)
    Version:  v0.2.27
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-extension
  feedback: Provide feedback, right in your terminal! (Docker Inc.)
    Version:  v1.0.5
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-feedback
  init: Creates Docker-related starter files for your project (Docker Inc.)
    Version:  v1.4.0
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-init
  sbom: View the packaged-based Software Bill Of Materials (SBOM) for an image (Anchore Inc.)
    Version:  0.6.0
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-sbom
  scout: Docker Scout (Docker Inc.)
    Version:  v1.16.1
    Path:     /Users/cedricahenkorah/.docker/cli-plugins/docker-scout
 
Server:                                                                                                                                                                                      Containers: 46
  Running: 8
  Paused: 0
  Stopped: 38
Images: 108
Server Version: 28.2.2
Storage Driver: overlay2
  Backing Filesystem: btrfs
  Supports d_type: true
  Using metacopy: false
  Native Overlay Diff: true
  userxattr: false                                                                                                                                                                           Logging Driver: json-file
Cgroup Driver: cgroupfs
Cgroup Version: 2
Plugins:
  Volume: local
  Network: bridge host ipvlan macvlan null overlay
  Log: awslogs fluentd gcplogs gelf journald json-file local splunk syslog
CDI spec directories:
  /etc/cdi
  /var/run/cdi
Swarm: inactive
Runtimes: io.containerd.runc.v2 runc
Default Runtime: runc
Init Binary: docker-init
containerd version: cb1076646aa3740577fafbf3d914198b7fe8e3f7
runc version: 4ca628d1d4c974f92d24daccb901aa078aad748e
init version: de40ad0
Security Options:
  seccomp
   Profile: builtin
  cgroupns
Kernel Version: 6.14.10-orbstack-00291-g1b252bd3edea
Operating System: OrbStack
OSType: linux
Architecture: aarch64
CPUs: 8
Total Memory: 7.809GiB
Name: orbstack
ID: e6077bfe-d16c-4306-b982-bc71b567981c
Docker Root Dir: /var/lib/docker
Debug Mode: false                                                                                                                                                                           Experimental: false
Insecure Registries:
  ::1/128
  127.0.0.0/8
Live Restore Enabled: false
Product License: Community Engine
Default Address Pools:
   Base: 192.168.97.0/24, Size: 24
   Base: 192.168.107.0/24, Size: 24
   Base: 192.168.117.0/24, Size: 24
   Base: 192.168.147.0/24, Size: 24
   Base: 192.168.148.0/24, Size: 24
   Base: 192.168.155.0/24, Size: 24
   Base: 192.168.156.0/24, Size: 24
   Base: 192.168.158.0/24, Size: 24
   Base: 192.168.163.0/24, Size: 24
   Base: 192.168.164.0/24, Size: 24
   Base: 192.168.165.0/24, Size: 24
   Base: 192.168.166.0/24, Size: 24
   Base: 192.168.167.0/24, Size: 24
   Base: 192.168.171.0/24, Size: 24
   Base: 192.168.172.0/24, Size: 24
   Base: 192.168.181.0/24, Size: 24
   Base: 192.168.183.0/24, Size: 24
   Base: 192.168.186.0/24, Size: 24
   Base: 192.168.207.0/24, Size: 24
   Base: 192.168.214.0/24, Size: 24
   Base: 192.168.215.0/24, Size: 24
   Base: 192.168.216.0/24, Size: 24
   Base: 192.168.223.0/24, Size: 24
   Base: 192.168.227.0/24, Size: 24
   Base: 192.168.228.0/24, Size: 24
   Base: 192.168.229.0/24, Size: 24
   Base: 192.168.237.0/24, Size: 24
   Base: 192.168.239.0/24, Size: 24
   Base: 192.168.242.0/24, Size: 24
   Base: 192.168.247.0/24, Size: 24
 
WARNING: DOCKER_INSECURE_NO_IPTABLES_RAW is set

[tonyo]

Am I reading it correctly that both local and remote machines are macos?

Wonder if there's some unexpected shell aliasing happening, or something wrong with the environment or $PATH specifically.

Does this work for you? ssh user@remote-ip docker version

Sharing these would also help:

UNREGISTRY_DEBUG=1 docker pussh someimage:latest user@remote-ip

ssh user@remote-ip echo '$PATH'

[kwakubiney]

Yes, both running macOS.

$ ssh user@remote-host echo '$PATH'
/usr/bin:/bin:/usr/sbin:/sbin  

$ ssh user@remote-host echo "docker version"
zsh:1: command not found: docker
When using a tool that pushes Docker images over SSH:

UNREGISTRY_DEBUG=1 docker pussh someimage:latest user@remote-host

The debug output showed:

...
• Connecting to user@remote-host...
ssh -o ControlMaster=auto -o ControlPath=/tmp/docker-pussh-XXXXXX.sock -o ControlPersist=1m -o ConnectTimeout=15 -f -N user@remote-host
...
ssh user@remote-host 'command -v docker'
ERROR: 'docker' command not found on remote host. Please ensure Docker is installed.

Turns out, ~/.zshrc (or similar shell init files) aren’t sourced for non-interactive SSH commands — so PATH was missing /usr/local/bin, where Docker lives.`

This helper fixed it for me:

ssh_with_env() {
    # Source common profile files to ensure PATH is properly set
    local cmd="source /etc/profile 2>/dev/null || true; \
               source ~/.profile 2>/dev/null || true; \
               source ~/.bash_profile 2>/dev/null || true; \
               source ~/.bashrc 2>/dev/null || true; \
               $*"
    ssh "${SSH_ARGS[@]}" "$cmd"
}

check_remote_docker() {
    # Check if docker command is available.
    if ! ssh_with_env "command -v docker" >/dev/null 2>&1; then
        echo "ERROR: 'docker' command not found on remote host. Please ensure Docker is installed."
        exit 1
    fi
    # Check if we need sudo to run docker commands.
    if ! ssh_with_env "docker version" >/dev/null 2>&1; then
        if ssh_with_env "[ \$(id -u) -ne 0 ] && sudo docker version" >/dev/null; then
            REMOTE_SUDO="sudo"
        else
            echo "ERROR: Failed to run docker commands on remote host. Please ensure:
  - Docker is installed and running on the remote host
  - SSH user has permissions to run docker commands (user is root or in 'docker' group)
  - If sudo is required, ensure the user can run 'sudo docker' without a password prompt"
            exit 1
        fi
    fi
}

[kwakubiney]

What do you think about this? @tonyo
Is this something you want to fix in the main product?

[tonyo]

Aha, docker not being in the default SSH-managed PATH is indeed a problem right now.

I would prefer to avoid sourcing .profile, .bashrc or any other files on SSH connections; those might introduce unintended side effects like unsolicited output (banners, statuses), initializing sequences for vitual envs, updating packages, etc.

A balanced solution would be to introduce a better detection for Docker executable, i.e. if it's not in the current (default) PATH, also check additional locations like /usr/local/bin/ and maybe a couple others.
If you want to get this sort of fix in the main branch soon, happy to review and accept a PR 👍

[psviderski]

Alternatively, you can add /usr/local/bin or the bin directory where the docker binary is installed to /etc/paths on your target macOS system. Mine contains the following and I have never modified it manually:

/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin

It's interesting why yours doesn't contain /usr/local/bin 🤔

[kwakubiney]

Sure, I'll draft a PR @tonyo

I don't have access to the remote Mac now, but my best bet is it does have /usr/local/bin in the /etc/paths, but not when running commands via SSH. Will experiment later @psviderski

user@local-machine ~ % ssh remoteuser@<REMOTE_IP> "cat /etc/paths"
/usr/local/bin
/System/Cryptexes/App/usr/bin
/usr/bin
/bin
/usr/sbin
/sbin
Connection to <REMOTE_IP> closed.
user@local-machine ~ % ssh remoteuser@<REMOTE_IP> "ls -l /usr/local/bin"
total 0
lrwxr-xr-x  1 root  wheel  68 Mar  4 23:31 code -> /Applications/Visual Studio Code.app/Contents/Resources/app/bin/code
lrwxr-xr-x  1 root  wheel  56 May  9 08:26 cursor -> /Applications/Cursor.app/Contents/Resources/app/bin/code
lrwxr-xr-x  1 root  wheel  53 Mar 19 10:55 docker -> /Applications/OrbStack.app/Contents/MacOS/xbin/docker
lrwxr-xr-x  1 root  wheel  61 Mar 19 10:55 docker-compose -> /Applications/OrbStack.app/Contents/MacOS/xbin/docker-compose
lrwxr-xr-x  1 root  wheel  73 Mar 19 10:24 docker-credential-desktop -> /Applications/Docker.app/Contents/Resources/bin/docker-credential-desktop
lrwxr-xr-x  1 root  wheel  76 Mar 19 10:55 docker-credential-osxkeychain -> /Applications/OrbStack.app/Contents/MacOS/xbin/docker-credential-osxkeychain
lrwxr-xr-x  1 root  wheel  56 Mar 19 10:24 hub-tool -> /Applications/Docker.app/Contents/Resources/bin/hub-tool
lrwxr-xr-x  1 root  wheel  54 Mar 19 10:55 kubectl -> /Applications/OrbStack.app/Contents/MacOS/xbin/kubectl
lrwxr-xr-x  1 root  wheel  55 Mar 19 10:24 kubectl.docker -> /Applications/Docker.app/Contents/Resources/bin/kubectl
lrwxr-xr-x  1 root  wheel  49 Mar 19 10:55 orb -> /Applications/OrbStack.app/Contents/MacOS/bin/orb
lrwxr-xr-x  1 root  wheel  52 Mar 19 10:55 orbctl -> /Applications/OrbStack.app/Contents/MacOS/bin/orbctl
user@local-machine ~ % ssh remoteuser@<REMOTE_IP> "docker --help"
zsh:1: command not found: docker
user@local-machine ~ % 

Seems it is a $PATH issue.

[kwakubiney]

On second thought, it seems what I am doing won't work either way. The remote host is running MacOS.
And the containerd socket is not exposed on MacOS so it crashes.