Skip to main content
Buttons publishes a multi-arch Docker image to GitHub Container Registry. Use it to bake the binary into your agent image, run one-off commands, or mount state from the host.

​
Image details

  • Base: Alpine Linux 3.20 (with ca-certificates + tzdata) — ~12 MB
  • Runs as: non-root user buttons (UID 1000), WORKDIR /home/buttons
  • Entrypoint: the buttons binary, so docker run … <verb> runs that command; bare docker run … defaults to --help
  • Shell available: /bin/sh — shell buttons work out of the box
  • Bash / Python / Node: not included — add via apk add in your derived image
  • Architectures: linux/amd64, linux/arm64
The most common pattern for agent deployments. Copy just the binary into your own image — no Alpine overhead:
The buttons binary is statically linked with no external dependencies, so it runs in any Linux image.

​
Pattern 2: Direct docker run

For one-off commands or quick tests:
State created inside the container is discarded when the container exits.

​
Pattern 3: Volume-mounted state

Persist button state and run history to the host by mounting the data dir. The image runs as the non-root user buttons (UID 1000), so its ~/.buttons resolves to /home/buttons/.buttons — mount there, not /root:
This lets you manage buttons on the host and invoke them from containers, or share state between multiple containers. The mounted directory must be writable by UID 1000. If your host user has a different UID, either chown the directory to 1000 or add --user "$(id -u)" to the docker run invocation (combine with -e BUTTONS_HOME=/home/buttons/.buttons so the data dir is found regardless of that user’s home).

​
Adding Bash, Python, or Node to a derived image

Shell buttons work in the base image. For Bash, Python, or Node buttons, extend the image:

​
Environment variables in containers

Set BUTTONS_HOME to control where state is stored inside the container:
This is useful when your container has a dedicated data volume at a non-default path.