Skip to content

Commit 13846d1

Browse files
CopilotMossaka
Copilot
and
Mossaka
authored
docs: add agent image tooling reference (#426)
* Initial plan * docs: add agent image tools reference - Add comprehensive documentation for pre-installed tools in agent and agent-act images - Include versions for Node.js, Python, git, curl, and other utilities - Document agent-act inheritance from catthehacker/ubuntu:act-24.04 - Add verification instructions with docker run examples - Link from docs/usage.md Pre-installed Tools section - Create both Starlight (docs-site) and markdown (docs) versions for compatibility * docs: simplify agent tool lists Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
1 parent 6b1b30f commit 13846d1

File tree

3 files changed

+276
-0
lines changed

3 files changed

+276
-0
lines changed

‎docs-site/src/content/docs/reference/agent-images.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
---
2+
title: Agent Image Tools
3+
description: Pre-installed development tools and versions in the agent and agent-act container images.
4+
---
5+
6+
Reference guide for the development tools, utilities, and runtime versions pre-installed in the `agent` and `agent-act` container images used by the firewall.
7+
8+
## Overview
9+
10+
The firewall uses two main container image types for running user commands:
11+
12+
- **`agent` (default)**: Lightweight Ubuntu 22.04-based image with essential dev tools
13+
- **`agent-act`**: GitHub Actions runner-compatible image based on Ubuntu 24.04
14+
15+
### Image Selection
16+
17+
Use the `--agent-image` flag to choose which image to use:
18+
19+
```bash
20+
# Default agent image (lightweight)
21+
sudo awf --allow-domains github.com -- node --version
22+
23+
# GitHub Actions-compatible image
24+
sudo awf --agent-image act --allow-domains github.com -- node --version
25+
```
26+
27+
### Base Images
28+
29+
| Image | Base | Purpose |
30+
|-------|------|---------|
31+
| `agent` | `ubuntu:22.04` | Minimal development environment with Node.js, Python, git |
32+
| `agent-act` | `catthehacker/ubuntu:act-24.04` | GitHub Actions runner subset with multiple runtime versions |
33+
34+
:::note
35+
The `agent-act` image inherits from [catthehacker/docker_images](https://github.com/catthehacker/docker_images), which provides medium-sized subsets of GitHub Actions runner images. For full GitHub Actions runner parity, you need the full-sized images (60GB+). See the catthehacker repository for details on runner compatibility.
36+
:::
37+
38+
## Verifying Tools Locally
39+
40+
Check installed tools and versions by running bash in the container:
41+
42+
```bash
43+
# Verify tools in agent image
44+
sudo awf --allow-domains '' -- bash -c 'node --version && python3 --version && git --version'
45+
46+
# Verify tools in agent-act image
47+
sudo awf --agent-image act --allow-domains '' -- bash -c 'which -a node && node --version'
48+
49+
# Interactive exploration
50+
sudo awf --tty --allow-domains '' -- bash
51+
```
52+
53+
## Agent Image Tools
54+
55+
The default `agent` image (based on Ubuntu 22.04) includes the following pre-installed tools:
56+
57+
| Tool | Version | Package | Notes |
58+
|------|---------|---------|-------|
59+
| Node.js | v22.22.0 | — | Includes npm, npx |
60+
| npm | 10.9.4 | — | — |
61+
| npx | 10.9.4 | — | — |
62+
| Python | 3.10.12 | — | No pip installed by default |
63+
| git | 2.34.1 | `git` | Standard git client |
64+
| GitHub CLI | 2.4.0+dfsg1 | `gh-cli` | `gh` command for GitHub API |
65+
| curl | 7.81.0 | `curl` | HTTP client |
66+
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
67+
| ifconfig | 2.10-alpha | `net-tools` | Network interface config |
68+
| netcat | 1.218 | `netcat-openbsd` | TCP/UDP connections |
69+
| iptables | 1.8.7 | `iptables` | Firewall rules (host-level control) |
70+
| gosu | 1.14 | `gosu` | Run commands as other users |
71+
| capsh | — | `libcap2-bin` | Capability management |
72+
| gnupg | 2.2.27 | `gnupg` | GPG encryption |
73+
| ca-certificates | — | `ca-certificates` | Trusted root certificates |
74+
75+
:::caution[Docker CLI Stub]
76+
The `docker` command is present but is a stub—there is no Docker daemon running inside the container. Docker-in-Docker is not supported. Use `--mount` to access Docker sockets from the host if needed.
77+
:::
78+
79+
## Agent-Act Image Tools
80+
81+
The `agent-act` image (based on Ubuntu 24.04) includes the following pre-installed tools:
82+
83+
| Tool | Version | Package | Notes |
84+
|------|---------|---------|-------|
85+
| Node.js | v18.20.8 | — | Default in PATH (from `/opt/hostedtoolcache`) |
86+
| npm | 10.8.2 | — | Bundled with Node.js 18 |
87+
| npx | 10.8.2 | — | Bundled with Node.js 18 |
88+
| corepack | 0.32.0 | — | Yarn/pnpm manager |
89+
| Node.js (system) | v22.22.0 | — | Alternative system installation at `/usr/bin/node` |
90+
| Python | 3.12.3 | — | Includes pip 24.0 |
91+
| pip | 24.0 | — | Python package manager |
92+
| git | 2.52.0 | `git` | Standard git client |
93+
| GitHub CLI | 2.45.0 | `gh-cli` | `gh` command for GitHub API |
94+
| git-lfs | 3.7.1 | `git-lfs` | Git Large File Storage |
95+
| gcc | 13.3.0 | `build-essential` | C compiler |
96+
| g++ | 13.3.0 | `build-essential` | C++ compiler |
97+
| make | 4.3 | `build-essential` | Build automation |
98+
| build-essential | — | `build-essential` | Metapackage with common build tools |
99+
| curl | 8.5.0 | `curl` | HTTP client |
100+
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
101+
| ifconfig | 2.10 | `net-tools` | Network interface config |
102+
| netcat | 1.226 | `netcat-openbsd` | TCP/UDP connections |
103+
| iptables | 1.8.10 | `iptables` | Firewall rules (host-level control) |
104+
| gosu | 1.17 | `gosu` | Run commands as other users |
105+
| capsh | — | `libcap2-bin` | Capability management |
106+
| jq | 1.6 | `jq` | JSON processor |
107+
| gnupg | — | `gnupg` | GPG encryption |
108+
| ca-certificates | — | `ca-certificates` | Trusted root certificates |
109+
110+
:::caution[Docker CLI Stub]
111+
The `docker` command is present but is a stub—there is no Docker daemon running inside the container. Docker-in-Docker is not supported. Use `--mount` to access Docker sockets from the host if needed.
112+
:::
113+
114+
## Custom Base Images
115+
116+
You can use custom base images with `--agent-image`:
117+
118+
```bash
119+
# Use a specific version of the act image
120+
sudo awf \
121+
--agent-image catthehacker/ubuntu:act-24.04 \
122+
--build-local \
123+
--allow-domains github.com \
124+
-- npm test
125+
126+
# Use your own custom image
127+
sudo awf \
128+
--agent-image myorg/my-base:latest \
129+
--build-local \
130+
--allow-domains github.com \
131+
-- ./my-script.sh
132+
```
133+
134+
:::danger[Security Risk]
135+
Custom base images introduce supply chain risks. Only use images from trusted publishers. The firewall cannot protect against malicious code in the base image itself.
136+
:::
137+
138+
## See Also
139+
140+
- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - Complete `--agent-image` flag documentation
141+
- [Usage Guide](/gh-aw-firewall/usage) - Examples of using different agent images
142+
- [catthehacker/docker_images](https://github.com/catthehacker/docker_images) - Source repository for GitHub Actions runner images

‎docs/agent-images.md‎

Lines changed: 132 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
# Agent Image Tools
2+
3+
Reference guide for the development tools, utilities, and runtime versions pre-installed in the `agent` and `agent-act` container images used by the firewall.
4+
5+
> 📘 **Note:** This document is also available in the [online documentation](https://githubnext.github.io/gh-aw-firewall/reference/agent-images/).
6+
7+
## Overview
8+
9+
The firewall uses two main container image types for running user commands:
10+
11+
- **`agent` (default)**: Lightweight Ubuntu 22.04-based image with essential dev tools
12+
- **`agent-act`**: GitHub Actions runner-compatible image based on Ubuntu 24.04
13+
14+
### Image Selection
15+
16+
Use the `--agent-image` flag to choose which image to use:
17+
18+
```bash
19+
# Default agent image (lightweight)
20+
sudo awf --allow-domains github.com -- node --version
21+
22+
# GitHub Actions-compatible image
23+
sudo awf --agent-image act --allow-domains github.com -- node --version
24+
```
25+
26+
### Base Images
27+
28+
| Image | Base | Purpose |
29+
|-------|------|---------|
30+
| `agent` | `ubuntu:22.04` | Minimal development environment with Node.js, Python, git |
31+
| `agent-act` | `catthehacker/ubuntu:act-24.04` | GitHub Actions runner subset with multiple runtime versions |
32+
33+
**Note:** The `agent-act` image inherits from [catthehacker/docker_images](https://github.com/catthehacker/docker_images), which provides medium-sized subsets of GitHub Actions runner images. For full GitHub Actions runner parity, you need the full-sized images (60GB+). See the catthehacker repository for details on runner compatibility.
34+
35+
## Verifying Tools Locally
36+
37+
Check installed tools and versions by running bash in the container:
38+
39+
```bash
40+
# Verify tools in agent image
41+
sudo awf --allow-domains '' -- bash -c 'node --version && python3 --version && git --version'
42+
43+
# Verify tools in agent-act image
44+
sudo awf --agent-image act --allow-domains '' -- bash -c 'which -a node && node --version'
45+
46+
# Interactive exploration
47+
sudo awf --tty --allow-domains '' -- bash
48+
```
49+
50+
## Agent Image Tools
51+
52+
The default `agent` image (based on Ubuntu 22.04) includes the following pre-installed tools:
53+
54+
| Tool | Version | Package | Notes |
55+
|------|---------|---------|-------|
56+
| Node.js | v22.22.0 | — | Includes npm, npx |
57+
| npm | 10.9.4 | — | — |
58+
| npx | 10.9.4 | — | — |
59+
| Python | 3.10.12 | — | No pip installed by default |
60+
| git | 2.34.1 | `git` | Standard git client |
61+
| GitHub CLI | 2.4.0+dfsg1 | `gh-cli` | `gh` command for GitHub API |
62+
| curl | 7.81.0 | `curl` | HTTP client |
63+
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
64+
| ifconfig | 2.10-alpha | `net-tools` | Network interface config |
65+
| netcat | 1.218 | `netcat-openbsd` | TCP/UDP connections |
66+
| iptables | 1.8.7 | `iptables` | Firewall rules (host-level control) |
67+
| gosu | 1.14 | `gosu` | Run commands as other users |
68+
| capsh | — | `libcap2-bin` | Capability management |
69+
| gnupg | 2.2.27 | `gnupg` | GPG encryption |
70+
| ca-certificates | — | `ca-certificates` | Trusted root certificates |
71+
72+
**⚠️ Docker CLI Stub:** The `docker` command is present but is a stub—there is no Docker daemon running inside the container. Docker-in-Docker is not supported. Use `--mount` to access Docker sockets from the host if needed.
73+
74+
## Agent-Act Image Tools
75+
76+
The `agent-act` image (based on Ubuntu 24.04) includes the following pre-installed tools:
77+
78+
| Tool | Version | Package | Notes |
79+
|------|---------|---------|-------|
80+
| Node.js | v18.20.8 | — | Default in PATH (from `/opt/hostedtoolcache`) |
81+
| npm | 10.8.2 | — | Bundled with Node.js 18 |
82+
| npx | 10.8.2 | — | Bundled with Node.js 18 |
83+
| corepack | 0.32.0 | — | Yarn/pnpm manager |
84+
| Node.js (system) | v22.22.0 | — | Alternative system installation at `/usr/bin/node` |
85+
| Python | 3.12.3 | — | Includes pip 24.0 |
86+
| pip | 24.0 | — | Python package manager |
87+
| git | 2.52.0 | `git` | Standard git client |
88+
| GitHub CLI | 2.45.0 | `gh-cli` | `gh` command for GitHub API |
89+
| git-lfs | 3.7.1 | `git-lfs` | Git Large File Storage |
90+
| gcc | 13.3.0 | `build-essential` | C compiler |
91+
| g++ | 13.3.0 | `build-essential` | C++ compiler |
92+
| make | 4.3 | `build-essential` | Build automation |
93+
| build-essential | — | `build-essential` | Metapackage with common build tools |
94+
| curl | 8.5.0 | `curl` | HTTP client |
95+
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
96+
| ifconfig | 2.10 | `net-tools` | Network interface config |
97+
| netcat | 1.226 | `netcat-openbsd` | TCP/UDP connections |
98+
| iptables | 1.8.10 | `iptables` | Firewall rules (host-level control) |
99+
| gosu | 1.17 | `gosu` | Run commands as other users |
100+
| capsh | — | `libcap2-bin` | Capability management |
101+
| jq | 1.6 | `jq` | JSON processor |
102+
| gnupg | — | `gnupg` | GPG encryption |
103+
| ca-certificates | — | `ca-certificates` | Trusted root certificates |
104+
105+
**⚠️ Docker CLI Stub:** The `docker` command is present but is a stub—there is no Docker daemon running inside the container. Docker-in-Docker is not supported. Use `--mount` to access Docker sockets from the host if needed.
106+
107+
## Custom Base Images
108+
109+
You can use custom base images with `--agent-image`:
110+
111+
```bash
112+
# Use a specific version of the act image
113+
sudo awf \
114+
--agent-image catthehacker/ubuntu:act-24.04 \
115+
--build-local \
116+
--allow-domains github.com \
117+
-- npm test
118+
119+
# Use your own custom image
120+
sudo awf \
121+
--agent-image myorg/my-base:latest \
122+
--build-local \
123+
--allow-domains github.com \
124+
-- ./my-script.sh
125+
```
126+
127+
**⚠️ Security Risk:** Custom base images introduce supply chain risks. Only use images from trusted publishers. The firewall cannot protect against malicious code in the base image itself.
128+
129+
## See Also
130+
131+
- [Usage Guide](usage.md) - Examples of using different agent images
132+
- [catthehacker/docker_images](https://github.com/catthehacker/docker_images) - Source repository for GitHub Actions runner images

‎docs/usage.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -456,6 +456,8 @@ When using runner/full images or the `act` preset, you get additional tools like
456456
- Container tools (docker, buildx)
457457
- And many more (see [catthehacker/docker_images](https://github.com/catthehacker/docker_images))
458458

459+
For complete tool listings with versions, see [Agent Image Tools Reference](/gh-aw-firewall/reference/agent-images/).
460+
459461
### Notes
460462

461463
- Presets (`default`, `act`) use pre-built GHCR images for fast startup

0 commit comments

Comments
 (0)