# How to Test Applications on Localhost from Docker Containers Using host.docker.internal with Shannon

> Easily test localhost applications from Docker containers using Shannon and host.docker.internal. Connect directly to your host machine for seamless development.

- Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon)
- Tags: tutorial
- Published: 2026-02-16

---

**Shannon enables testing of localhost applications from within Docker containers by utilizing the `host.docker.internal` DNS name, which resolves to the host machine's IP address instead of the container's internal localhost.**

When running security testing agents inside Docker containers, accessing applications hosted on your local machine requires special networking configuration. The **KeygraphHQ/shannon** repository solves this challenge by implementing Docker's `host.docker.internal` DNS alias, allowing containers to reach host-bound services without exposing them to external networks.

## Why Localhost Fails Inside Docker Containers

Docker containers operate within isolated **networking namespaces**, meaning that `localhost` or `127.0.0.1` references resolve to the container itself rather than the host machine. When Shannon's agents attempt to connect to `localhost:3000`, they target the container's internal loopback interface, not the application running on your development machine.

## Configuring host.docker.internal in Shannon

Shannon leverages Docker Desktop's built-in DNS name `host.docker.internal` to bridge this networking gap. This hostname automatically resolves to the host's IP address within the container's network context.

### Docker Compose Network Configuration

The repository's [`docker-compose.docker.yml`](https://github.com/KeygraphHQ/shannon/blob/main/docker-compose.docker.yml) file explicitly maps the host gateway to ensure DNS resolution works correctly across all containerized agents:

```yaml

# docker-compose.docker.yml

services:
  shannon:
    # …

    extra_hosts:
      - "host.docker.internal:host-gateway"

```

This configuration, found at line 6 of the compose file, guarantees that `host.docker.internal` resolves to the host machine's IP address rather than failing with DNS resolution errors.

### Launching Shannon Against Local Applications

According to the [`README.md`](https://github.com/KeygraphHQ/shannon/blob/main/README.md) (lines 206-212), users should substitute `localhost` with `host.docker.internal` when starting Shannon scans:

```bash
./shannon start URL=http://host.docker.internal:3000 REPO=my-app

```

The [`CLAUDE.md`](https://github.com/KeygraphHQ/shannon/blob/main/CLAUDE.md) documentation (line 131) reinforces this pattern, ensuring consistent guidance across all Shannon documentation for testing locally-hosted applications.

## Practical Implementation Examples

When Shannon agents execute tools like curl, Playwright, or PhantomJS, they automatically inherit the container's networking configuration. Here are specific implementation patterns:

### HTTP Requests with curl

Inside a Shannon agent container, accessing your local API endpoint works seamlessly:

```bash
curl -s http://host.docker.internal:3000/api/health

```

### Browser Automation with Playwright

Shannon's MCP helper for Playwright uses the same hostname pattern. The JSON payload structure for browser automation targets local applications:

```json
{
  "tool": "mcp__playwright-agent2__browser_fill_form",
  "input": {
    "fields": [
      {
        "name": "URL field",
        "type": "textbox",
        "ref": "e7",
        "value": "http://host.docker.internal:3000/"
      }
    ]
  }
}

```

### Security Testing Scenarios

In SSRF exploitation testing, Shannon agents inject `host.docker.internal` to force server-side requests to hit the host machine. An example from the benchmark audit logs demonstrates this pattern:

```bash
curl -s "http://localhost:38291/page?name=%3Czzz%20onfocus%3D%22new%20Image%28%29.src%3D%27http%3A%2F%2Fhost.docker.internal%3A9999%2Fssrf-test%27%3Balert%28%27done%27%29%22%20autofocus%3E"

```

This approach allows security testing of locally-hosted applications without deploying them to external servers.

## Summary

- **Docker containers use isolated networking namespaces**, making `localhost` resolve to the container rather than the host machine.
- **Shannon utilizes `host.docker.internal`** as a DNS alias that resolves to the host's IP address within containers.
- **Configuration requires `extra_hosts` mapping** in [`docker-compose.docker.yml`](https://github.com/KeygraphHQ/shannon/blob/main/docker-compose.docker.yml) to ensure proper DNS resolution.
- **All Shannon agents inherit this networking setup**, enabling tools like curl, Playwright, and PhantomJS to access local applications seamlessly.
- **This pattern supports security testing scenarios** including SSRF and XSS exploitation against locally-hosted services.

## Frequently Asked Questions

### Why can't I use localhost to reach my host machine from Shannon's Docker containers?

Docker containers run in isolated networking namespaces where `localhost` and `127.0.0.1` refer to the container's own loopback interface, not the host machine. When Shannon agents attempt to connect to `localhost:3000`, they target the container itself, which has no service listening on that port. The `host.docker.internal` DNS name provides the necessary bridge to the host's network interface.

### Is host.docker.internal available on all Docker platforms?

The `host.docker.internal` hostname works reliably on Docker Desktop for Windows and macOS. On Linux systems, this DNS name may not be available by default depending on the Docker version and configuration. Shannon addresses this by explicitly adding the `extra_hosts` entry in [`docker-compose.docker.yml`](https://github.com/KeygraphHQ/shannon/blob/main/docker-compose.docker.yml), which ensures the hostname resolves correctly across all supported platforms including Linux environments.

### Do I need to modify my application code to work with Shannon's Docker setup?

No application code changes are required. You only need to modify the URL you pass to Shannon when starting a scan. Replace `localhost` or `127.0.0.1` with `host.docker.internal` in the command line argument. For example, use `URL=http://host.docker.internal:3000` instead of `URL=http://localhost:3000`. Your application continues to bind to its normal host port without any configuration changes.

### Can I use this approach for security testing against local applications?

Yes, this approach is specifically designed to support security testing scenarios. Shannon's agents can target `host.docker.internal` to perform SSRF exploitation, XSS testing, and other vulnerability assessments against applications running on your local machine. The benchmark audit logs in the repository demonstrate real-world examples where agents inject `host.docker.internal` into payloads to force server-side requests back to the host machine, enabling comprehensive security testing without deploying to external servers.