From d74d49a21552aaf6910769459c1e3598d2b62b46 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Tue, 31 Mar 2026 20:49:51 +0000
Subject: [PATCH] docs: clarify service container accessibility from agent
 sandbox

The agent runs inside an isolated Docker container, so service containers
are not reachable via localhost. Add a note to the services: frontmatter
section explaining that services must be accessed via host.docker.internal.

Addresses the gap described in github/gh-aw#22939.
---
 docs/src/content/docs/reference/frontmatter.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/docs/src/content/docs/reference/frontmatter.md b/docs/src/content/docs/reference/frontmatter.md
index 5a7ddaadaa5..85a52be1d81 100644
--- a/docs/src/content/docs/reference/frontmatter.md
+++ b/docs/src/content/docs/reference/frontmatter.md
@@ -575,6 +575,9 @@ services:
       - 5432:5432
 ```
 
+> [!NOTE]
+> The AWF agent runs inside an isolated Docker container. Service containers expose ports on the runner host, not within the agent's network namespace. To connect to a service from the agent, use `host.docker.internal` as the hostname instead of `localhost`. For example, a Postgres service configured with port `5432:5432` is accessible at `host.docker.internal:5432`.
+
 See [GitHub Actions service docs](https://docs.github.com/en/actions/using-containerized-services).
 
 ## Conditional Execution (`if:`)