> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buttons.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker

> Use the Buttons Docker image for deployed agents.

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

```
ghcr.io/autonoco/buttons:latest
ghcr.io/autonoco/buttons:v0.128.0   # pinned version
```

* **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`

## Pattern 1: Multi-stage copy (recommended)

The most common pattern for agent deployments. Copy just the binary into your own image — no Alpine overhead:

```dockerfile theme={null}
FROM ghcr.io/autonoco/buttons:v0.128.0 AS buttons

FROM python:3.12-slim AS agent

COPY --from=buttons /usr/local/bin/buttons /usr/local/bin/buttons

# Your agent setup
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt

CMD ["python", "agent.py"]
```

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:

```bash theme={null}
docker run --rm ghcr.io/autonoco/buttons:latest version
docker run --rm ghcr.io/autonoco/buttons:latest list
```

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`:

```bash theme={null}
docker run --rm \
  -v "$HOME/.buttons:/home/buttons/.buttons" \
  ghcr.io/autonoco/buttons:latest \
  press db-backup --arg env=staging --arg retention=7d
```

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:

<CodeGroup>
  ```dockerfile Python theme={null}
  FROM ghcr.io/autonoco/buttons:v0.128.0

  RUN apk add --no-cache python3 py3-pip
  ```

  ```dockerfile Node theme={null}
  FROM ghcr.io/autonoco/buttons:v0.128.0

  RUN apk add --no-cache nodejs npm
  ```

  ```dockerfile Python + Node + Bash theme={null}
  FROM ghcr.io/autonoco/buttons:v0.128.0

  RUN apk add --no-cache bash python3 py3-pip nodejs npm
  ```
</CodeGroup>

## Environment variables in containers

Set `BUTTONS_HOME` to control where state is stored inside the container:

```dockerfile theme={null}
ENV BUTTONS_HOME=/data/buttons
```

This is useful when your container has a dedicated data volume at a non-default path.

## Related

* [Installation](/installation) — all install options including curl and Go
* [Install script](/deployment/install-script) — how the install.sh script works
* [Button folder structure](/concepts/folder-structure) — what lives in `BUTTONS_HOME`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.