Dockerfile customization

.gitignore

@@ -6,6 +6,9 @@
 # local compose overrides
 compose.override.yml
 
+# user-supplied custom package layer
+Dockerfile.custom
+
 # macOS
 .DS_Store
 

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.0] - 2026-05-09
+
+### Added
+- Support for custom images 
+
 ## [0.2.0] - 2026-05-08
 
 ### Changed

Dockerfile.custom.example

@@ -0,0 +1,13 @@
+# Copy this file to Dockerfile.custom and add your packages.
+# It is layered on top of agentbox:latest by `make build` and retags as agentbox:latest.
+
+FROM agentbox:latest
+
+USER root
+
+# Examples — uncomment and adapt:
+# RUN apk add --no-cache htop httpie
+# RUN pip3 install --no-cache-dir requests pandas
+# RUN npm install -g typescript prettier
+
+USER user

Makefile

@@ -25,6 +25,10 @@ help: ## Show this help
 
 build: ## Build the Docker image (keeps last KEEP builds)
 	DOCKER_BUILDKIT=1 docker build --no-cache --pull -t $(IMAGE):latest -t $(IMAGE):$(shell date -u +%Y%m%d-%H%M%S) .
+	@if [ -f Dockerfile.custom ]; then \
+		echo "Applying Dockerfile.custom"; \
+		DOCKER_BUILDKIT=1 docker build -t $(IMAGE):latest -f Dockerfile.custom .; \
+	fi
 	@docker images $(IMAGE) --format '{{.Tag}}' \
 		| grep -v latest \
 		| sort -r \

README.md

@@ -60,6 +60,27 @@ make shell                # drop into a zsh shell without starting an agent
 
 Each run starts a tmux session with two windows — one running the agent, one with a plain shell. Agent config and auth are persisted to `~/.agentbox/` on the host so settings survive between runs.
 
+## Custom packages
+
+To add your own packages on top of the base image, copy the template and edit it:
+
+```sh
+cp Dockerfile.custom.example Dockerfile.custom
+```
+
+Add your `apk`, `pip`, or `npm` installs:
+
+```dockerfile
+FROM agentbox:latest
+USER root
+RUN apk add --no-cache htop httpie
+RUN pip3 install --no-cache-dir requests
+RUN npm install -g typescript
+USER user
+```
+
+`make build` detects `Dockerfile.custom` automatically, layers it on top of the freshly built base, and retags the result as `agentbox:latest`. The file is gitignored so your customisations stay local.
+
 ## Session branching
 
 Before the agent starts, agentbox creates a timestamped git branch (`agentbox/<branch>/<timestamp>`) in each mounted git repository. This lets you review exactly what the agent changed and discard or merge at will. Set `SNAPSHOT=0` to disable.