You can run extra processes in the same container as your app. These processes are called sidecars.

When you provide a sidecar for your app, Cloud Foundry packages the code and config it needs to run the sidecar process and the app process in the same droplet, and deploys this droplet in a single container.

Note: Each process within the container has its own health check. Sidecar processes can only use PID-based health checks.

Why use Sidecars?

Sidecars are often used for processes that depend on each other, or that must run in the same container. For example, sidecars can be useful for processes that:

  • Communicate over a Unix socket or through localhost
  • Share the same filesystem
  • Need to be scaled and placed together
  • Must have fast interprocess communication


Co-locating processes in this way also introduces additional risks and limitations:

  • Co-dependent crashing - if an app has one or more sidecars they are entirely co-dependent. If one process crashes, CF will kill the other and recreate it.
  • Scaling - all of the container’s resources are shared, and therefore co-located processes are scaled together with the main process.
  • Start/Stop order undefined - you cannot control the order in which CF starts and stops app processes and their sidecars.
  • Health checks for sidecars - sidecars are limited to PID-based health checks.


Sidecar processes can be defined in your app manifest via the sidecars block. The example below shows an app with multiple sidecar processes.

- name: my-app
   - name: authenticator
     process_types: [ 'web', 'worker' ]
     command: bundle exec run-authenticator
   - name: performance monitor
     process_types: [ 'web' ]
     command: bundle exec run-performance-monitor

Sidecars Pushed with Custom Buildpacks

Alternatively, a custom buildpack can specify sidecar processes by including a launch.yml file at its root. This file provides the details of the sidecar process.

Note: At the time of writing, pushing sidecars with custom buildpacks is a Beta feature.

If you are interested in learning more about custom sidecar buildpacks and the launch.yml file, take a look at the Cloud Foundry documentation.

Try it

Let’s try pushing an app with a sidecar process.

We’ll be pushing a simple Ruby app named sidecar-dependent-app with a /config endpoint. Hitting this endpoint will cause the app to call the sidecar and then print out the response. The sidecar is a Go process (named config-server-sidecar) that provides apps with config over its /config endpoint. It only accepts connections over localhost on the CONFIG_SERVER_PORT. Therefore, the processes must be co-located so that they share the same network space.

The sidecar process is configured in the app manifest:

- name: sidecar-dependent-app
  command: bundle exec rackup -p $PORT
  disk_quota: 256M
  instances: 1
  memory: 128M
  - name: config-server
    - web
    command: './config-server'

The sidecar is included in the codebase as a binary. The CONFIG_SERVER_PORT environment variable is provided so that the sidecar knows which port to listen on and the app knows which port to connect to. The sidecar is also assigned to the app’s main web process, and given a name and start command.

We can deploy our app with:

cf push --random-route

View the Processes Running in the Container

Now that our app is up and running, we can SSH into the container to view the running processes with cf ssh

cf ssh sidecar-dependent-app
ps aux

You should see output similar to this:

vcap@f00949bd-6601-4731-6f7e-e859:~$ ps aux
root      1 0.0  0.0     1120     0     ?     S      22:17 0:00  /tmp/garden-init
vcap      7 0.0  0.0     106716   4508  ?     S      22:17 0:00  ./config-server
vcap     13 0.0  0.1     519688   35412 ?     S      22:17 0:00  /home/vcap/deps/0/vendor_bundle/ruby/2.4.0/bin/rackup -p 8080
vcap     24 0.0  0.0     116344   10792 ?     S      22:17 0:00  /tmp/lifecycle/diego-sshd --allowedKeyExchanges= --address= --allowUnauthenticatedClients=false --inhe
root     82 0.0  0.0     108012   4548  ?     S      22:17 0:00  /etc/cf-assets/healthcheck/healthcheck -port=8080 -timeout=1000ms -liveness-interval=30s
vcap    215 0.3  0.0     70376    3756  pts/0 S      23:12 0:00  /bin/bash
vcap    227 0.0  0.0     86268    3116  pts/0 R      23:12 0:00  ps aux

The output shows both the sidecar config-server process and the main app rackup process.

View the Web URL

In a browser we can navigate to the /config endpoint of the sidecar-dependent-app. Retrieve the route for your app using cf app and open the /config endpoint in your browser. For example:

You should see the Scope and Password information displayed inside a JSON object. This is the config that the app has retrieved from the config-server sidecar.

Sidecar Logs

Start streaming the logs for the app in a terminal window.

cf logs sidecar-dependent-app

Now refresh your browser window a few times. You should see the log stream in your terminal starts to display the logs for both the app and sidecar processes. Keep streaming the logs for the time being.

Killing the sidecar process

We can go one step further and open another terminal window to SSH into the app container and kill the config-server process.

cf ssh sidecar-dependent-app
kill -9 $(pgrep config-server)

Take another look at the window where you’re streaming the logs, and you should see the config-server crash and the container then being recreated.

Tidy up

You can now go ahead and delete the sidecar-dependent-app deployment, we won’t be reusing it in other sections.