> For the complete documentation index, see [llms.txt](https://protocol-labs.gitbook.io/testground/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://protocol-labs.gitbook.io/testground/master/table-of-contents/concepts-and-architecture/sidecar.md).

# Sidecar

This `sidecar` is an individual Testground process responsible for network management and traffic shaping for test plan instances. It runs in privileged-mode on host machines, and listens for requests from test plan instances for network configuration through the `sync service`.

The `sidecar` is one of the three processes in the Testground executable. The other two are the Testground daemon and the Testground client. It can be started with:

```bash
$ testground sidecar --runner local:docker # or cluster:k8s
```

**The sidecar runs in Docker and Kubernetes environments** (i.e. when using the `local:docker` or the `cluster:k8s`runners). For now it is not supported and it does not run when using the `local:exec` runner.

On Kubernetes, each worker node runs the sidecar. We schedule it via a [DaemonSet](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/).

Usually, you will never need to start the sidecar manually. Each runner's health checks (which run prior to a test run) will ensure that the sidecar is running.

## Responsibilities

Sidecars are responsible for three things:

1. Initializing the network interfaces of test instances. See [Networking](broken://pages/-M6V03O0jUyEmCfccNr3) for more info.
   * Sidecars watch the local Docker daemon for containers being started and stopped.
   * For each new container, they adjust the routing of the `control` network, and they initialize the `data` network, incrementing the `network-initialized` state on the `sync service` every time a new test plan container is instrumented under a given `run_id`.
2. Applying networking configurations requested by test plan instances, by targeting the appropriate data interface through [Netlink](http://man7.org/linux/man-pages/man7/netlink.7.html). See [Networking](broken://pages/-M6V03O0jUyEmCfccNr3) for more info.
3. Periodically garbage-collect inactive entries in the [sync service](broken://pages/-M6PkaeKIqRYi8KqBEML) (backed by a Redis database), pertaining to finished runs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://protocol-labs.gitbook.io/testground/master/table-of-contents/concepts-and-architecture/sidecar.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.