[GH-ISSUE #87] [Feature] Rootless periphery agent #4663

New Issue

GiteaMirror · 2026-04-21T23:42:38-05:00

GiteaMirror commented

2026-04-21 23:42:38 -05:00

Originally created by @FoxxMD on GitHub (Sep 19, 2024).
Original GitHub issue: https://github.com/moghtech/komodo/issues/87

When a periphery agent container creates some resources (repos,stacks) in a bind mount these files are currently created as root. This makes reading/writing any of these files inconvenient if the user on the host is not root.

The container can be run with a non-root user by specify user: "UID:GID" or equivalent with docker run and the agent runs fine. It also creates resources with the correct permissions in this instance. However, the agent cannot access docker.sock due to it being owned by root:docker which is for security, I believe.

Please implement a way to allow control over file/folder permissions for resources touched by the agent, or, implement a way to use the container rootless that can still communicate with docker.

Some Thoughts

Enable SSL/HTTP communication with docker

(My preferred solution)

The crate used for docker communication, bollard, supports SSL/HTTP connections out of the box. The current connect_with_local_defaults() function could be try-caught (?) with a fallback to connect_with_http_defaults() and/or connect_with_ssl_defaults() -- both of which use environmental variables to initiate a connection which require no config change for the agent.

This would enable using docker-socket-proxy for communication which would solve non-root communication with docker.

`chown` with UID/GID from ENV

Allow a user to specify UID and GID in environmental variables and then chown files touched by the agent. This would allow the agent to continue to work as root while solving file permissions for bind mounts.

Originally created by @FoxxMD on GitHub (Sep 19, 2024). Original GitHub issue: https://github.com/moghtech/komodo/issues/87 When a [`periphery` agent container](https://komo.do/docs/setup/connect-servers#install-the-periphery-agent---container) creates some resources (repos,stacks) in a bind mount these files are currently created as `root`. This makes reading/writing any of these files inconvenient if the user on the host is not root. The container can be run with a non-root user by specify [`user: "UID:GID"`](https://docs.docker.com/reference/compose-file/services/#user) or equivalent with `docker run` and the agent runs fine. It also creates resources with the correct permissions in this instance. However, the agent **cannot** access `docker.sock` due to it being owned by `root:docker` which is for security, I believe. Please implement a way to allow control over file/folder permissions for resources touched by the agent, or, implement a way to use the container rootless that can still communicate with docker. ### Some Thoughts #### Enable SSL/HTTP communication with docker (My preferred solution) The crate used for docker communication, [`bollard`](https://github.com/fussybeaver/bollard?tab=readme-ov-file#http), supports SSL/HTTP connections out of the box. The current [`connect_with_local_defaults()`](https://github.com/mbecker20/komodo/blob/main/bin/periphery/src/docker.rs#L35) function could be try-caught (?) with a fallback to `connect_with_http_defaults()` and/or `connect_with_ssl_defaults()` -- both of which use environmental variables to initiate a connection which require no config change for the agent. This would enable using [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy) for communication which would solve non-root communication with docker. #### `chown` with UID/GID from ENV Allow a user to specify `UID` and `GID` in environmental variables and then `chown` files touched by the agent. This would allow the agent to continue to work as `root` while solving file permissions for bind mounts.

GiteaMirror added the done label 2026-04-21 23:42:38 -05:00

GiteaMirror closed this issue

2026-04-21 23:42:39 -05:00

GiteaMirror commented

2026-04-21 23:42:40 -05:00

@mbecker20 commented on GitHub (Oct 17, 2024):

Now supports DOCKER_HOST env variable for use with docker-socket-proxy: https://github.com/mbecker20/komodo/releases/tag/v1.15.10

@mbecker20 commented on GitHub (Oct 17, 2024): Now supports DOCKER_HOST env variable for use with [docker-socket-proxy](https://github.com/Tecnativa/docker-socket-proxy): https://github.com/mbecker20/komodo/releases/tag/v1.15.10

GiteaMirror commented

2026-04-21 23:42:41 -05:00

@paulora2405 commented on GitHub (Mar 20, 2025):

How would one go about configuring docker-socket-proxy and the DOCKER_HOST envvar, in order to enable the usage of a non-root user in the periphery agent?

Could you share your config @FoxxMD perhaps?

@paulora2405 commented on GitHub (Mar 20, 2025): How would one go about configuring `docker-socket-proxy` and the `DOCKER_HOST` envvar, in order to enable the usage of a non-root user in the periphery agent? Could you share your config @FoxxMD perhaps?

GiteaMirror commented

2026-04-21 23:42:41 -05:00

@FoxxMD commented on GitHub (Mar 20, 2025):

Hi @paulora2405 I wrote a blog post that covers how to do this, some gotchas I discovered, and sample code:

https://blog.foxxmd.dev/posts/migrating-to-komodo/#create-komodo-periphery-agents

Expand the A Note on Security and Non-Root Periphery section (and Details section within for code example)

@FoxxMD commented on GitHub (Mar 20, 2025): Hi @paulora2405 I wrote a blog post that covers how to do this, some gotchas I discovered, and sample code: https://blog.foxxmd.dev/posts/migrating-to-komodo/#create-komodo-periphery-agents Expand the `A Note on Security and Non-Root Periphery` section (and `Details` section within for code example)

GiteaMirror commented

2026-04-21 23:42:42 -05:00

@willyp713 commented on GitHub (Nov 19, 2025):

@FoxxMD another detail that might be needed (in your blog post or perhaps in the documentation) is that you need to add the rootless path for docker.sock into the systemd config for periphery. I had to piece this together from other issues and posts until I figured it out.

In ~/.config/systemd/user/periphery.service I had to add this line:

[Service]
Environment="DOCKER_HOST=unix:///run/user/1000/docker.sock"

Note that it required the unix:/// prefix or else the periphery agent would fail with an error about invalid URI scheme.

Another workaround is to create a symlink, such as:

ln -s /run/user/1000/docker.sock /var/run/docker.sock

but that didn't persist after a reboot for me, which is what brought me back here. Adding it to periphery.service seems like a more permanent solution (I think).

@willyp713 commented on GitHub (Nov 19, 2025): @FoxxMD another detail that might be needed (in your blog post or perhaps in the documentation) is that you need to add the rootless path for `docker.sock` into the systemd config for periphery. I had to piece this together from other issues and posts until I figured it out. In `~/.config/systemd/user/periphery.service` I had to add this line: ``` [Service] Environment="DOCKER_HOST=unix:///run/user/1000/docker.sock" ``` Note that it required the unix:/// prefix or else the periphery agent would fail with an error about invalid URI scheme. Another workaround is to create a symlink, such as: `ln -s /run/user/1000/docker.sock /var/run/docker.sock` but that didn't persist after a reboot for me, which is what brought me back here. Adding it to `periphery.service` seems like a more permanent solution (I think).

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/komodo#4663

[GH-ISSUE #87] [Feature] Rootless periphery agent #4663

Some Thoughts

Enable SSL/HTTP communication with docker

chown with UID/GID from ENV

`chown` with UID/GID from ENV