[][src]Crate tcpwarp

A userspace tunnel between two hosts mapping ports on client machine to addresses reachable from server machine

tcp-warp server
tcp-warp client -c 8080:towel.blinkenlights.nl:23
nc 8080


  1. A userspace tunnel to connect ports on client network with connections available on server side.
  2. Uses only single port.
  3. Client push of addresses to connect from server.


With cargo:

cargo install tcp-warp-cli


To create a tunnel we need to start a server listening on some port and then connect to it with a client.

Docker usage for server part

docker run --rm -d -p 18000:18000 tcpwarp/tcpwarp

or with custom listen port (ex: 18234):

docker run --rm -d -p 18234:18234 tcpwarp/tcpwarp tcp-warp server --listen=

Simple local running port remapper

  1. Start server:

    tcp-warp server
  2. Start client:

    tcp-warp client -c 8080:towel.blinkenlights.nl:23
  3. Enjoy the show:

    nc 8080
  4. This example uses default listen and connect interfaces. In a real life scenario you need at least provide -t / --tunnel parameter to client:

    tcp-warp client -t host:port ...

Both client and server have address on which they listen for incoming connections and client additionally have parameter to specify connection address.

Next we look at more specific example.

Use case: running Docker on machine without Docker daemon installed with Docker daemon behind SSH


  • client: client machine runs on Windows, has Windows version of tcp-warp and Docker CLI installed. Client cannot run Docker daemon.
  • public: master node accessible with SSH from which Docker daemon node can be accessed.
  • docker: docker daemon node accessible with SSH.


Run Docker over tcp transport, allowing client to build and run containers. Environment should be available for each developer independent of other.


Run on docker machine Docker-in-Docker container (dind) using tcp host protocol. Use DOCKER_HOST environment variable on client to connect to dind. dind is bindet to host port on docker host and forwarded via public with SSH port-forwarding.

The sequence of commands can be following:

Initial sequence (installation)

  1. Go to docker node and start required containers:

    user@client $ ssh user1@public
    user1@public $ ssh user2@docker
    user2@docker $ docker run --rm --privileged -p 2375:2375 -p 18000:18000 -d --name some-docker docker:dind dockerd --host=tcp://
    user2@docker $ DOCKER_HOST=tcp:// docker run --rm -p 18000:18000 -d --name some-docker-tcp-warp tcpwarp/tcpwarp
  2. Disconnect from docker and public nodes.

Normal sequence (usage)

  1. Connect to public node with ssh and forward port for tcp-warp:

    ssh -L 18000:docker:18000 user1@public
  2. Connect to Docker daemon with tcp-warp client on client machine:

    tcp-warp client -c 10001:
 here is the address of host node in dind.

  3. Export DOCKER_HOST environment variable on client machine:

    export DOCKER_HOST=tcp://
  4. Run docker commands from client:

    docker ps
    docker run hello-world
    docker run -it alpine ash

Additional services

We can start additional services and relaunch tcp-warp client with additional -c for these services.

Simple example with whoami service:

  1. Create network to use for hostname resolution. Start whoami service with all above steps done. Connect tcp-warp container to new network:

    docker network create our-network
    docker run --rm -d --net our-network --name whoami containous/whoami
    docker network connect our-network some-docker-tcp-warp
  2. Stop tcp-warp client. Start it with additional port mapping for whoami service:

    tcp-warp client -c 10001: -c 8080:whoami:80
  3. Test whoami service:

    $ curl http://localhost:8080/
    Hostname: 9fe704cf0e87
    GET / HTTP/1.1
    Host: localhost:8080
    User-Agent: curl/7.64.1





Command types.