|
1 | 1 | --- |
2 | 2 | title: Sandbox Configuration |
3 | | -description: Configure sandbox environments for AI engines including MCP Gateway and Sandbox Runtime (SRT) |
| 3 | +description: Configure sandbox environments for AI engines including AWF agent container, mounted tools, runtime environments, and MCP Gateway |
4 | 4 | sidebar: |
5 | 5 | order: 1350 |
6 | 6 | --- |
@@ -85,13 +85,55 @@ AWF automatically mounts several paths from the host into the container to enabl |
85 | 85 | | Host Path | Container Path | Mode | Purpose | |
86 | 86 | |-----------|----------------|------|---------| |
87 | 87 | | `/tmp` | `/tmp` | `rw` | Temporary files and cache | |
| 88 | +| `${HOME}/.cache` | `${HOME}/.cache` | `rw` | Build caches (Go, npm, etc.) | |
88 | 89 | | `${GITHUB_WORKSPACE}` | `${GITHUB_WORKSPACE}` | `rw` | Repository workspace directory | |
89 | | -| `/usr/bin/{date,gh,yq}` | `/usr/bin/{date,gh,yq}` | `ro` | System utilities (date, GitHub CLI, yq) | |
| 90 | +| `/opt/hostedtoolcache` | `/opt/hostedtoolcache` | `ro` | Runtimes (Node.js, Python, Go, Ruby, Java) | |
| 91 | +| `/opt/gh-aw` | `/opt/gh-aw` | `ro` | Script and configuration files | |
90 | 92 | | `/usr/local/bin/copilot` | `/usr/local/bin/copilot` | `ro` | Copilot CLI binary | |
91 | 93 | | `/home/runner/.copilot` | `/home/runner/.copilot` | `rw` | Copilot configuration and state | |
92 | 94 |
|
93 | 95 | These default mounts ensure the agent has access to essential tools and the repository files. Custom mounts specified via `sandbox.agent.mounts` are added alongside these defaults. |
94 | 96 |
|
| 97 | +#### Mounted System Utilities |
| 98 | + |
| 99 | +AWF mounts common system utilities from the host into the container as read-only binaries. These utilities are frequently used in workflow scripts and are organized by priority: |
| 100 | + |
| 101 | +**Essential Utilities** (most commonly used): |
| 102 | + |
| 103 | +| Utility | Purpose | |
| 104 | +|---------|---------| |
| 105 | +| `cat` | Display file contents | |
| 106 | +| `curl` | HTTP client for API calls | |
| 107 | +| `date` | Date/time operations | |
| 108 | +| `find` | Locate files by pattern | |
| 109 | +| `gh` | GitHub CLI operations | |
| 110 | +| `grep` | Pattern matching | |
| 111 | +| `jq` | JSON processing | |
| 112 | +| `yq` | YAML processing | |
| 113 | + |
| 114 | +**Common Utilities** (frequently used for file operations): |
| 115 | + |
| 116 | +| Utility | Purpose | |
| 117 | +|---------|---------| |
| 118 | +| `cp` | Copy files | |
| 119 | +| `cut` | Extract text columns | |
| 120 | +| `diff` | Compare files | |
| 121 | +| `head` | Display file start | |
| 122 | +| `ls` | List directory contents | |
| 123 | +| `mkdir` | Create directories | |
| 124 | +| `rm` | Remove files | |
| 125 | +| `sed` | Stream text editing | |
| 126 | +| `sort` | Sort text lines | |
| 127 | +| `tail` | Display file end | |
| 128 | +| `wc` | Count lines/words | |
| 129 | +| `which` | Locate commands | |
| 130 | + |
| 131 | +All utilities are mounted read-only (`:ro`) from `/usr/bin/` on the host. They execute on the read-write workspace directory inside the container. |
| 132 | + |
| 133 | +> [!TIP] |
| 134 | +> Available Utilities |
| 135 | +> Run `which jq` or `jq --version` in your workflow to verify utility availability. The agent has access to all mounted utilities without additional setup. |
| 136 | + |
95 | 137 | > [!WARNING] |
96 | 138 | > Docker socket access is not supported for security |
97 | 139 | > reasons. The agent firewall does not mount |
@@ -123,6 +165,55 @@ The following environment variables are mirrored (if they exist on the host): |
123 | 165 | > Environment Variable Handling |
124 | 166 | > Variables are only passed to the container if they exist on the host runner. Missing variables are silently ignored, ensuring workflows work across different runner configurations. |
125 | 167 |
|
| 168 | +#### Runtime Tools (hostedtoolcache) |
| 169 | + |
| 170 | +AWF mounts the `/opt/hostedtoolcache` directory from the GitHub Actions runner, providing access to all runtimes installed via `actions/setup-*` steps. This directory contains pre-installed and dynamically-installed versions of popular development tools. |
| 171 | + |
| 172 | +**Available Runtimes:** |
| 173 | + |
| 174 | +| Runtime | Setup Action | Example Versions | |
| 175 | +|---------|-------------|------------------| |
| 176 | +| **Node.js** | `actions/setup-node` | 18.x, 20.x, 22.x | |
| 177 | +| **Python** | `actions/setup-python` | 3.9, 3.10, 3.11, 3.12, 3.13, 3.14 | |
| 178 | +| **Go** | `actions/setup-go` | 1.22.x, 1.23.x, 1.24.x, 1.25.x | |
| 179 | +| **Ruby** | `ruby/setup-ruby` | 3.2, 3.3, 3.4 | |
| 180 | +| **Java** | `actions/setup-java` | 8, 11, 17, 21, 25 | |
| 181 | + |
| 182 | +**PATH Integration:** |
| 183 | + |
| 184 | +All runtime binaries are automatically added to PATH inside the agent container. The PATH is configured using a dynamic `find` command that discovers all `bin` directories within `/opt/hostedtoolcache`: |
| 185 | + |
| 186 | +```bash |
| 187 | +# PATH includes all hostedtoolcache binaries |
| 188 | +export PATH="$(find /opt/hostedtoolcache -maxdepth 4 -type d -name bin 2>/dev/null | tr '\n' ':')$PATH" |
| 189 | +``` |
| 190 | + |
| 191 | +**Version Priority:** |
| 192 | + |
| 193 | +When multiple versions of a runtime are installed, versions configured by `actions/setup-*` take precedence. The agent detects which specific version is active by reading environment variables like `GOROOT`, `JAVA_HOME`, and ensures that version's binaries appear first in PATH. |
| 194 | + |
| 195 | +**Using Runtimes in Workflows:** |
| 196 | + |
| 197 | +```yaml wrap |
| 198 | +--- |
| 199 | +jobs: |
| 200 | + setup: |
| 201 | + steps: |
| 202 | + - uses: actions/setup-go@v5 |
| 203 | + with: |
| 204 | + go-version: '1.25' |
| 205 | + - uses: actions/setup-python@v5 |
| 206 | + with: |
| 207 | + python-version: '3.12' |
| 208 | +--- |
| 209 | +
|
| 210 | +Use `go build` or `python3` in your workflow - both are available! |
| 211 | +``` |
| 212 | + |
| 213 | +> [!TIP] |
| 214 | +> Verify Runtime Availability |
| 215 | +> Use `node --version`, `python3 --version`, `go version`, or `ruby --version` in your workflow to confirm runtime availability. The agent automatically inherits all runtimes configured by setup actions. |
| 216 | +
|
126 | 217 | #### Custom AWF Configuration |
127 | 218 |
|
128 | 219 | Use custom commands, arguments, and environment variables to replace the standard AWF installation with a custom setup: |
|
0 commit comments