Getting Started¶

This guide will help you get started with Docker Socket Proxy.

Prerequisites¶

Docker installed and running
Basic understanding of Docker and its API
Administrative privileges (for creating and managing sockets)

Installation¶

Grab the latest release from GitHub and move it to a directory in your PATH:

curl -sSL https://github.com/js-murph/docker-socket-proxy/releases/latest/download/docker-socket-proxy.tgz
tar -xzf docker-socket-proxy.tgz
mv docker-socket-proxy /usr/local/bin/docker-socket-proxy

Running the Daemon¶

The Docker Socket Proxy daemon is the core service that manages proxy sockets. Start it with:

docker-socket-proxy daemon

This will:

Create the socket directory at /var/run/docker-proxy/
Start the management socket at /var/run/docker-proxy/management.sock
Begin listening for socket creation/deletion requests

For production use, you may want to run the daemon as a systemd service. An example service file is provided in the repository at examples/docker-socket-proxy.service.

Creating Your First Proxy Socket¶

Create a configuration file (e.g., config.yaml):

config:
  propagate_socket: "/var/run/docker.sock"

rules:
  - match:
      path: "/v1.*/volumes"
      method: "GET"
    actions:
      - action: "deny"
        reason: "Listing volumes is restricted"
  - match:
      path: "/v1.*/containers/create"
      method: "POST"
    actions:
      - action: "upsert"
        update:
          Env:
            - "FUN=yes"
      - action: "replace"
        contains:
          Env:
            - "DEBUG=true"
        update:
          Env:
            - "DEBUG=false"
      - action: "delete"
        contains:
          Env:
            - "PANTS=.*"

Create the proxy socket:

docker-socket-proxy socket create -c config.yaml

The command will output the path to your new proxy socket, typically something like:

Socket created: /var/run/docker-proxy/socket-12345.sock

Using the Proxy Socket¶

You can now use this socket with Docker CLI or any other Docker client:

docker -H unix:///var/run/docker-proxy/socket-12345.sock ps

Or with Docker Compose by setting the DOCKER_HOST environment variable:

DOCKER_HOST=unix:///var/run/docker-proxy/socket-12345.sock docker-compose up

Managing Proxy Sockets¶

List all available proxy sockets:

docker-socket-proxy socket list

View the configuration of a specific socket:

docker-socket-proxy socket describe socket-12345.sock

Delete a socket when you no longer need it:

docker-socket-proxy socket delete socket-12345.sock

Next Steps¶

Now that you have a basic proxy socket running, you can:

Learn more about configuration options
Explore advanced rule configurations
Check the CLI reference for all available commands