--privileged not working on a self hosted runner.

[Alan Pritchard]

I'm trying to use the --privileged tag on a self hosted runner but I keep getting an error stating that it's not allowed.  I've run the same step on bitbucket's docker and it runs fine.  To keep things basic, I'm currently using code cut and pasted from the support page detailing the use of runtime v3.  The only difference I can see is that my runners keep insisting on downloading bitbucket-pipelines-docker-daemon   v25.0.5 while on the hosted environment it appears to be running docker v28.5.1

My bitbucket-pipelines.yml is as follows:

options:

  runtime:

    cloud:

      version: "3"

pipelines:

  custom:

    privileged-docker-run:

        - step:

              runtime:

              cloud:

                 version: 3

              image: atlassian/default-image:5

              runs-on:

                - 'self.hosted'

                - 'linux'

              services:

                - docker

              script:

                - docker version

                - docker info

                - docker run --privileged alpine:3 sh -c "echo 20 > /proc/sys/vm/swappiness && cat /proc/sys/vm/swappiness"

[Alan Pritchard · Accepted solution]

For anyone else who finds this the following AI chatbot response helped me sort this out:

### Current Status of `--privileged` with Bitbucket Runners and Runtime v3

- **Runtime v3** in Bitbucket Pipelines is designed to allow the use of the `--privileged` flag with `docker run`, which was previously restricted for security reasons. This means, in theory, you should be able to use `--privileged` in your build steps if you are using Runtime v3 and have configured your pipeline accordingly.
- However, there is a known issue where conflicts between the Docker CLI bundled with certain images (like `atlassian/default-image:5`) and the runner’s own Docker CLI can cause failures when attempting to use privileged mode. Specifically, the bundled CLI may route builds through BuildKit using the `docker-container` driver, which tries to start a privileged sidecar but fails because `--privileged=true` is not allowed in this context.

#### Workaround

- **Use an older image:** Switch to `atlassian/default-image:4`, which does not ship with its own Docker CLI and will respect the runner’s CLI, avoiding the conflict.
- **Custom build image:** Alternatively, use a custom build step image that does not include a conflicting Docker CLI version.

#### Additional Notes

- If you are running into issues with Docker version mismatches (e.g., runner downloads and runs Docker v25.0.5), ensure that your build image and runner environment are aligned in terms of Docker CLI and daemon versions. Runtime v3 allows you to bring your own Docker CLI, so you can specify the exact version you need.
- If you are using self-hosted runners, you have more flexibility and can define a custom Docker daemon that does not restrict the `--privileged` flag.

#### Relevant Bug

- There is an open bug regarding the CLI conflict and privileged mode: [BCLOUD-23853](https://jira.atlassian.com/browse/BCLOUD-23853). You may want to watch this ticket for updates, as the Atlassian development team is aware of the issue.

---

Would you like guidance on updating your pipeline configuration or help with creating a custom build image?

Sources

1. https://support.atlassian.com/bitbucket-cloud/docs/enable-and-use-runtime-v3/
2. https://jira.atlassian.com/browse/BCLOUD-23853
3. https://support.atlassian.com/bitbucket-cloud/kb/building-multi-architecture-docker-images-with-bitbucket-pipelines/