When testing applications running on your local machine, you’ll need to use a special hostname to allow Shannon’s Docker containers to reach your host.
The Problem
Docker containers run in an isolated network environment. When Shannon tries to access localhost or 127.0.0.1 from inside a container, it reaches the container’s own network interface, not your host machine.
The Solution
Use host.docker.internal instead of localhost when specifying the target URL.
Usage
./shannon start URL=http://host.docker.internal:3000 REPO=repo-name
Examples
Testing a local web application on port 3000
./shannon start URL=http://host.docker.internal:3000 REPO=my-webapp
Testing a local API on port 8080
./shannon start URL=http://host.docker.internal:8080 REPO=my-api
Testing with HTTPS (if your local app supports it)
./shannon start URL=https://host.docker.internal:3443 REPO=my-secure-app
| Platform | Support |
|---|
| macOS | ✅ Native Docker Desktop support |
| Windows (Docker Desktop) | ✅ Native support |
| Windows (WSL2) | ✅ Supported |
| Linux | ⚠️ May require additional configuration |
Linux Notes
On Linux, host.docker.internal is not automatically available in older Docker versions. You may need to:
- Use
--add-host flag in Docker (handled automatically by Shannon)
- Or use your machine’s actual IP address instead:
# Find your IP address
ip addr show
# Use the IP address directly
./shannon start URL=http://192.168.1.100:3000 REPO=repo-name
Troubleshooting
Connection Refused
If Shannon cannot connect to your local application:
- Verify the app is running: Check that your application is actually running on the specified port
- Check the port: Make sure you’re using the correct port number
- Firewall settings: Ensure your firewall isn’t blocking the connection
- Binding address: Make sure your app is binding to
0.0.0.0 or your machine’s IP, not just 127.0.0.1
Application Binding
Make sure your application is configured to accept connections from all interfaces:
Good (accessible from Docker):
# Binds to all interfaces
node server.js --host 0.0.0.0 --port 3000
# Only binds to localhost
node server.js --host 127.0.0.1 --port 3000
Security Considerations
When binding your application to 0.0.0.0 for testing, it becomes accessible from your network. Only do this in trusted environments.
- Use isolated development environments
- Consider using Docker networks for better isolation
- Don’t expose sensitive applications on your network
- Use firewall rules to restrict access if needed
