How do I run exec on a remote docker host

[tyler71]

I can do something like this:

DOCKER_HOST=ssh://10.10.10.10 docker container run --rm busybox ls
bin
dev
[...]

I'd like to do something like this:

steps:
  - name: test
    image: busybox
    commands:
      - ls

This works:

woodpecker exec
[test:L0:0s] + ls
[test:L1:0s] test

This does not:

woodpecker exec --backend-docker-host ssh://10.10.10.10 --backend-engine docker
12:04AM FTL error running cli error="Error reading remote info: EOF"

Is using a remote Docker host possible with woodpecker exec?

[6543]

we use the same internal lib (moby) as docker cli to connect to the docker daemon, so supporting ssh://... looks like a feature docker cli explicit added... through i have not looked into the docker cli code jet, so just assumptions...

[qwerty287]

Yes it looks like the moby lib does not support this natively.

[mg1986jp]

woodpecker exec with --backend-docker-host ssh://... isn't supported. The exec command uses the Docker client SDK which handles SSH hosts differently than the plain docker CLI.

When you run docker -H ssh://10.10.10.10 ..., the Docker CLI sets up an SSH tunnel internally and forwards the Docker socket. But woodpecker exec creates a Docker client programmatically via the Go SDK, and the SSH dialer in the SDK expects the remote Docker daemon to be properly configured — the EOF error means the SSH connection succeeds but the Docker API handshake fails (likely because the remote Docker socket isn't at the default path, or the SSH user can't access it).

Workaround 1: SSH tunnel + TCP

Set up a local port forward to the remote Docker socket:

ssh -fNL /tmp/remote-docker.sock:/var/run/docker.sock user@10.10.10.10
DOCKER_HOST=unix:///tmp/remote-docker.sock woodpecker exec

Workaround 2: Expose Docker over TCP on the remote host

On the remote host, configure dockerd to listen on TCP (only do this on a trusted network):

# /etc/docker/daemon.json
{"hosts": ["unix:///var/run/docker.sock", "tcp://0.0.0.0:2376"]}

Then:

woodpecker exec --backend-docker-host tcp://10.10.10.10:2376 --backend-engine docker

Workaround 3: Use a Woodpecker agent instead of exec

If this is for actual CI (not just local testing), run a Woodpecker agent on the remote machine. exec is really meant for local dev/testing — for remote execution, the agent model is the intended path.