Skip to content

docs: add agent image tooling reference #426

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Mossaka merged 3 commits into from
Jan 27, 2026
Merged

docs: add agent image tooling reference #426

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9dafe04
Initial plan
Copilot Jan 26, 2026
37d5735
docs: add agent image tools reference
Copilot Jan 26, 2026
cdb0c2a
docs: simplify agent tool lists
Copilot Jan 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
142 changes: 142 additions & 0 deletions docs-site/src/content/docs/reference/agent-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,142 @@
---
title: Agent Image Tools
description: Pre-installed development tools and versions in the agent and agent-act container images.
---

Reference guide for the development tools, utilities, and runtime versions pre-installed in the `agent` and `agent-act` container images used by the firewall.

## Overview

The firewall uses two main container image types for running user commands:

- **`agent` (default)**: Lightweight Ubuntu 22.04-based image with essential dev tools
- **`agent-act`**: GitHub Actions runner-compatible image based on Ubuntu 24.04

### Image Selection

Use the `--agent-image` flag to choose which image to use:

```bash
# Default agent image (lightweight)
sudo awf --allow-domains github.com -- node --version

# GitHub Actions-compatible image
sudo awf --agent-image act --allow-domains github.com -- node --version
```

### Base Images

| Image | Base | Purpose |
|-------|------|---------|
| `agent` | `ubuntu:22.04` | Minimal development environment with Node.js, Python, git |
| `agent-act` | `catthehacker/ubuntu:act-24.04` | GitHub Actions runner subset with multiple runtime versions |

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

## Verifying Tools Locally

Check installed tools and versions by running bash in the container:

```bash
# Verify tools in agent image
sudo awf --allow-domains '' -- bash -c 'node --version && python3 --version && git --version'

# Verify tools in agent-act image
sudo awf --agent-image act --allow-domains '' -- bash -c 'which -a node && node --version'

# Interactive exploration
sudo awf --tty --allow-domains '' -- bash
```

## Agent Image Tools

The default `agent` image (based on Ubuntu 22.04) includes the following pre-installed tools:

| Tool | Version | Package | Notes |
|------|---------|---------|-------|
| Node.js | v22.22.0 | — | Includes npm, npx |
| npm | 10.9.4 | — | — |
| npx | 10.9.4 | — | — |
| Python | 3.10.12 | — | No pip installed by default |
| git | 2.34.1 | `git` | Standard git client |
| GitHub CLI | 2.4.0+dfsg1 | `gh-cli` | `gh` command for GitHub API |
| curl | 7.81.0 | `curl` | HTTP client |
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
| ifconfig | 2.10-alpha | `net-tools` | Network interface config |
| netcat | 1.218 | `netcat-openbsd` | TCP/UDP connections |
| iptables | 1.8.7 | `iptables` | Firewall rules (host-level control) |
| gosu | 1.14 | `gosu` | Run commands as other users |
| capsh | — | `libcap2-bin` | Capability management |
| gnupg | 2.2.27 | `gnupg` | GPG encryption |
| ca-certificates | — | `ca-certificates` | Trusted root certificates |

:::caution[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.
:::

## Agent-Act Image Tools

The `agent-act` image (based on Ubuntu 24.04) includes the following pre-installed tools:

| Tool | Version | Package | Notes |
|------|---------|---------|-------|
| Node.js | v18.20.8 | — | Default in PATH (from `/opt/hostedtoolcache`) |
| npm | 10.8.2 | — | Bundled with Node.js 18 |
| npx | 10.8.2 | — | Bundled with Node.js 18 |
| corepack | 0.32.0 | — | Yarn/pnpm manager |
| Node.js (system) | v22.22.0 | — | Alternative system installation at `/usr/bin/node` |
| Python | 3.12.3 | — | Includes pip 24.0 |
| pip | 24.0 | — | Python package manager |
| git | 2.52.0 | `git` | Standard git client |
| GitHub CLI | 2.45.0 | `gh-cli` | `gh` command for GitHub API |
| git-lfs | 3.7.1 | `git-lfs` | Git Large File Storage |
| gcc | 13.3.0 | `build-essential` | C compiler |
| g++ | 13.3.0 | `build-essential` | C++ compiler |
| make | 4.3 | `build-essential` | Build automation |
| build-essential | — | `build-essential` | Metapackage with common build tools |
| curl | 8.5.0 | `curl` | HTTP client |
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
| ifconfig | 2.10 | `net-tools` | Network interface config |
| netcat | 1.226 | `netcat-openbsd` | TCP/UDP connections |
| iptables | 1.8.10 | `iptables` | Firewall rules (host-level control) |
| gosu | 1.17 | `gosu` | Run commands as other users |
| capsh | — | `libcap2-bin` | Capability management |
| jq | 1.6 | `jq` | JSON processor |
| gnupg | — | `gnupg` | GPG encryption |
| ca-certificates | — | `ca-certificates` | Trusted root certificates |

:::caution[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.
:::

## Custom Base Images

You can use custom base images with `--agent-image`:

```bash
# Use a specific version of the act image
sudo awf \
--agent-image catthehacker/ubuntu:act-24.04 \
--build-local \
--allow-domains github.com \
-- npm test

# Use your own custom image
sudo awf \
--agent-image myorg/my-base:latest \
--build-local \
--allow-domains github.com \
-- ./my-script.sh
```

:::danger[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.
:::

## See Also

- [CLI Reference](/gh-aw-firewall/reference/cli-reference) - Complete `--agent-image` flag documentation
- [Usage Guide](/gh-aw-firewall/usage) - Examples of using different agent images
- [catthehacker/docker_images](https://github.com/catthehacker/docker_images) - Source repository for GitHub Actions runner images
132 changes: 132 additions & 0 deletions docs/agent-images.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
# Agent Image Tools

Reference guide for the development tools, utilities, and runtime versions pre-installed in the `agent` and `agent-act` container images used by the firewall.

> 📘 **Note:** This document is also available in the [online documentation](https://githubnext.github.io/gh-aw-firewall/reference/agent-images/).

## Overview

The firewall uses two main container image types for running user commands:

- **`agent` (default)**: Lightweight Ubuntu 22.04-based image with essential dev tools
- **`agent-act`**: GitHub Actions runner-compatible image based on Ubuntu 24.04

### Image Selection

Use the `--agent-image` flag to choose which image to use:

```bash
# Default agent image (lightweight)
sudo awf --allow-domains github.com -- node --version

# GitHub Actions-compatible image
sudo awf --agent-image act --allow-domains github.com -- node --version
```

### Base Images

| Image | Base | Purpose |
|-------|------|---------|
| `agent` | `ubuntu:22.04` | Minimal development environment with Node.js, Python, git |
| `agent-act` | `catthehacker/ubuntu:act-24.04` | GitHub Actions runner subset with multiple runtime versions |

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

## Verifying Tools Locally

Check installed tools and versions by running bash in the container:

```bash
# Verify tools in agent image
sudo awf --allow-domains '' -- bash -c 'node --version && python3 --version && git --version'

# Verify tools in agent-act image
sudo awf --agent-image act --allow-domains '' -- bash -c 'which -a node && node --version'

# Interactive exploration
sudo awf --tty --allow-domains '' -- bash
```

## Agent Image Tools

The default `agent` image (based on Ubuntu 22.04) includes the following pre-installed tools:

| Tool | Version | Package | Notes |
|------|---------|---------|-------|
| Node.js | v22.22.0 | — | Includes npm, npx |
| npm | 10.9.4 | — | — |
| npx | 10.9.4 | — | — |
| Python | 3.10.12 | — | No pip installed by default |
| git | 2.34.1 | `git` | Standard git client |
| GitHub CLI | 2.4.0+dfsg1 | `gh-cli` | `gh` command for GitHub API |
| curl | 7.81.0 | `curl` | HTTP client |
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
| ifconfig | 2.10-alpha | `net-tools` | Network interface config |
| netcat | 1.218 | `netcat-openbsd` | TCP/UDP connections |
| iptables | 1.8.7 | `iptables` | Firewall rules (host-level control) |
| gosu | 1.14 | `gosu` | Run commands as other users |
| capsh | — | `libcap2-bin` | Capability management |
| gnupg | 2.2.27 | `gnupg` | GPG encryption |
| ca-certificates | — | `ca-certificates` | Trusted root certificates |

**⚠️ 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.

## Agent-Act Image Tools

The `agent-act` image (based on Ubuntu 24.04) includes the following pre-installed tools:

| Tool | Version | Package | Notes |
|------|---------|---------|-------|
| Node.js | v18.20.8 | — | Default in PATH (from `/opt/hostedtoolcache`) |
| npm | 10.8.2 | — | Bundled with Node.js 18 |
| npx | 10.8.2 | — | Bundled with Node.js 18 |
| corepack | 0.32.0 | — | Yarn/pnpm manager |
| Node.js (system) | v22.22.0 | — | Alternative system installation at `/usr/bin/node` |
| Python | 3.12.3 | — | Includes pip 24.0 |
| pip | 24.0 | — | Python package manager |
| git | 2.52.0 | `git` | Standard git client |
| GitHub CLI | 2.45.0 | `gh-cli` | `gh` command for GitHub API |
| git-lfs | 3.7.1 | `git-lfs` | Git Large File Storage |
| gcc | 13.3.0 | `build-essential` | C compiler |
| g++ | 13.3.0 | `build-essential` | C++ compiler |
| make | 4.3 | `build-essential` | Build automation |
| build-essential | — | `build-essential` | Metapackage with common build tools |
| curl | 8.5.0 | `curl` | HTTP client |
| dig | 9.18.39 | `dnsutils` | DNS lookup utility |
| ifconfig | 2.10 | `net-tools` | Network interface config |
| netcat | 1.226 | `netcat-openbsd` | TCP/UDP connections |
| iptables | 1.8.10 | `iptables` | Firewall rules (host-level control) |
| gosu | 1.17 | `gosu` | Run commands as other users |
| capsh | — | `libcap2-bin` | Capability management |
| jq | 1.6 | `jq` | JSON processor |
| gnupg | — | `gnupg` | GPG encryption |
| ca-certificates | — | `ca-certificates` | Trusted root certificates |

**⚠️ 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.

## Custom Base Images

You can use custom base images with `--agent-image`:

```bash
# Use a specific version of the act image
sudo awf \
--agent-image catthehacker/ubuntu:act-24.04 \
--build-local \
--allow-domains github.com \
-- npm test

# Use your own custom image
sudo awf \
--agent-image myorg/my-base:latest \
--build-local \
--allow-domains github.com \
-- ./my-script.sh
```

**⚠️ 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.

## See Also

- [Usage Guide](usage.md) - Examples of using different agent images
- [catthehacker/docker_images](https://github.com/catthehacker/docker_images) - Source repository for GitHub Actions runner images
2 changes: 2 additions & 0 deletions docs/usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -456,6 +456,8 @@ When using runner/full images or the `act` preset, you get additional tools like
- Container tools (docker, buildx)
- And many more (see [catthehacker/docker_images](https://github.com/catthehacker/docker_images))

For complete tool listings with versions, see [Agent Image Tools Reference](/gh-aw-firewall/reference/agent-images/).

### Notes

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