Trifork Blog

Docker From A Distance – The Remote API

December 24th, 2013 by

Docker-logoMany people use docker from the command line to build images, run containers and manage Docker on their machine. However, you can also run the same Docker commands via its remote REST API. In this blog I will guide you through Docker’s remote API using curl while pointing out a few details and tools that you might not know about. We will remotely search and pull an elasticsearch image, run a container and clean up after ourselves.

Docker’s Remote API

I assume you know how to build and run a Docker container via the command line. If not, check out Quinten’s blog post on how to create tomcat instances with Docker. When installing Docker the daemon is configured to listen on a UNIX socket. It’s fun to realize that we can access the REST API via the socket without any additional configuration. To list all images run the following command:

$ echo -e "GET /images/json HTTP/1.0\r\n" | nc -U /var/run/docker.sock
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 858
Connection: close
Date: Fri, 20 Dec 2013 16:02:41 GMT


You have to use netcat because you cannot echo to a socket from bash. For more information on communication with UNIX sockets in this way, see this Gist which has more code samples and useful links.

Listening on a port

To get Docker to listen on a port first stop docker.

$ sudo service docker stop

Now edit Docker’s upstart file at /etc/init/docker.conf so it looks like this:

description     "Docker daemon"

start on filesystem and started lxc-net
stop on runlevel [!2345]


    /usr/bin/docker -H tcp:// -d
end script

Now run

$ sudo service docker start

and Docker is listening on port 4243. However, note that this is insecure. Check out James Carr’s blog post on securing Docker’s remote API.

Example – Pulling, starting and stopping Elasticsearch

Let’s access the API with curl to see what is going on. We will run the following steps:

  • Search for an elasticsearch image in the Docker index
  • Pull an image from the Docker registry
  • Create the container
  • Start the container
  • Stop the container
  • Remove the container

Curious to know more about the Docker terminology like index and registry? Check this blog by Troy Howard.


Let’s search for some elasticsearch images using the following call:

$ curl -s -XGET http://localhost:4243/images/search?term=elasticsearch | jq '.[] | .name'

Here I filter the results through jq, a great tool for processing JSON on the command line. It’s like sed for JSON.

Pull an image

Now let’s pull the vieux/elasticsearch image:

$ curl -XPOST http://localhost:4243/images/create?fromImage=vieux/elasticsearch
"progress":"[==================================================\u003e] 10.24 kB/10.24 kB 0","id":"daf68f48da59"}
{"status":"Download complete","progressDetail":{},"id":"daf68f48da59"}
{"status":"Download complete","progressDetail":{},"id":"daf68f48da59"}

Create a container

When running a container via the command line you would use the docker ‘run’ command. This is a composite command, consisting of the commands ‘create’ and ‘start’.
The remote API does not support the ‘run’ command. You have to execute ‘create’ and ‘start’ separately. To create a container run:

$ curl -X POST -H "Content-Type: application/json" http://localhost:4243/containers/create -d '{
     "Privileged": false,

Start a container

To start the container we reuse the ID we got from the ‘create’ command.

$ curl -XPOST http://localhost:4243/containers/398378dfa8a5409c4ad011e96788e085d2f13bb6dff07c5394a955609fcf7327/start

and we can see that elasticsearch is running!

$ curl -X GET http://localhost:9200
  "ok" : true,
  "status" : 200,
  "name" : "Banner, Robert Bruce",
  "version" : {
    "number" : "0.90.5",
    "build_hash" : "c8714e8e0620b62638f660f6144831792b9dedee",
    "build_timestamp" : "2013-09-17T12:50:20Z",
    "build_snapshot" : false,
    "lucene_version" : "4.4"
  "tagline" : "You Know, for Search"
$ docker ps
CONTAINER ID        IMAGE                        COMMAND                CREATED             STATUS              PORTS               NAMES
398378dfa8a5        vieux/elasticsearch:0.90.1   /bin/sh -c elasticse   34 minutes ago      Up 6 seconds        9200/tcp            sharp_pasteur       

Stop a container

And now let’s stop the container:

$ curl -X POST http://localhost:4243/containers/398378dfa8a5409c4ad011e96788e085d2f13bb6dff07c5394a955609fcf7327/stop
$ docker ps
CONTAINER ID        IMAGE               COMMAND             CREATED             STATUS              PORTS               NAMES

Remove the container

Let’s clean up and remove the container:

$ docker ps -a | grep vieux
398378dfa8a5        vieux/elasticsearch:0.90.1    /bin/sh -c elasticse   About an hour ago   Exit 137                                sharp_pasteur             
$ curl -X DELETE http://localhost:4243/containers/398378dfa8a5409c4ad011e96788e085d2f13bb6dff07c5394a955609fcf7327
$ docker ps -a | grep vieux

The Docker phenomenon

Hope this post gave you a useful intro to Docker’s remote API. If you want to a more detailed description of the remote API check out the official Docker remote API documentation. Docker is becoming very popular. The community shares Dockerfiles, meetups pop up all over the planet and people keep pet whales and call them Moby Dock. Okay, maybe I am fibbing on that one. Point is, people like Docker because you can now do things that were impossible or very hard before. You could use a VMs instead but they can be cubersome and slow. Now you can encapsulate an entire application, including its code, configuration and environment and recreate and share it. Docker is actively developed and not production ready, but people see its potential and push its boundaries.


Because of the potential we see in Docker we are interested in your feedback. How are _you_ using Docker? What is your favourite use case? What are some downsides of Docker? If you had magic powers and you could….well if you had magic powers you wouldn’t use Docker you would just use your magic 😉 No but really, which feature would you like to see added to Docker and why? What do you think of our posts on Docker? Interesting, meh, or something else? Do you like to see more code, no code or good practices? Please let us know. We are looking forward hearing from you.

In closing I wish you happy holidays and a great new year!

P.S. Don’t forget to return your Docker configuration back to its original state.

7 Responses

  1. December 24, 2013 at 15:18 by alessandro

    Great post! Where I work we’re looking exactly into this, for leveraging orchestration based on containers (imaging auto-scaling load-balancers by spawning more containers and adding them to a pool). There’s also a nice and clean interface to networked dockers:

  2. December 24, 2013 at 17:16 by Frank Scholten

    Hi Alessandro, how is everything? Thanks for your comment! Shipyard looks impressive. The auto scaling scenario is interesting to look into indeeed.

  3. June 16, 2014 at 03:11 by Luis

    I wouldn’t recommend to edit the /etc/init/docker.conf file, instead, you can edit /etc/defaults/docker and add the line:

    DOCKER_OPTS=”-H tcp:// -H unix:///var/run/docker.sock -d”

  4. June 20, 2014 at 14:41 by David

    Docker Registry API is a REST API for the Docker Registry, which eases the storage of images and repositories. The API does not have access to user accounts or its authorization. Read part four of the Docker Tutorial Series to learn more about registry types.

  5. August 5, 2014 at 18:01 by brianf

    Thanks for this. Super clear example. Exactly what I was looking for.

  6. March 12, 2015 at 12:10 by james

    How can I link host port to container port via remote api?

  7. May 6, 2015 at 11:56 by Midhun Kandoth

    Hi, this was really a usefull post. But then can any system in that nwtwork access this docker through the rest API ? Is there any authentication mechanism for this?.If not it will be a vulnarebiilty right ?