How to Bind FreeLLMAPI to All Network Interfaces (`0.0.0.0`)

Set the HOST environment variable to 0.0.0.0 before starting the server to force the Express listener to bind on every available IPv4 interface instead of localhost only.

FreeLLMAPI exposes an Express-based HTTP server that requires explicit configuration to accept traffic from external sources. By default, the service binds to localhost (127.0.0.1), which limits connectivity to the local machine. Binding to 0.0.0.0 is essential when deploying the tashfeenahmed/freellmapi repository inside Docker containers, virtual machines, or any remote server environment.

Understanding the Binding Logic in server/src/index.ts

The network interface configuration is controlled in server/src/index.ts, the application's entry point. The server initialization calls app.listen() with the HOST environment variable as the second argument:

app.listen(Number(PORT), HOST, onReady(HOST))

According to the source code, if the HOST variable is undefined, the application contains a fallback that explicitly uses the wildcard address:

app.listen(Number(PORT), '0.0.0.0', onReady('0.0.0.0'))

This fallback ensures the server can listen on all interfaces, but explicitly setting HOST=0.0.0.0 is the recommended approach for clarity and compatibility across different deployment scenarios.

Configuring the HOST Environment Variable

You can inject the HOST variable through multiple methods depending on your deployment strategy.

Using a .env File

Create or modify the .env file in the project root:

HOST=0.0.0.0
PORT=8080

The PORT variable is optional and defaults to 3000 if omitted.

Exporting in Shell

For temporary testing or development environments, export the variable directly:

export HOST=0.0.0.0
export PORT=8080
npm run start

Docker and Container Deployments

When running the official Docker image, pass the environment variable using the -e flag:

docker run -e HOST=0.0.0.0 -e PORT=8080 -p 8080:8080 tashfeenahmed/freellmapi

For Docker Compose configurations, add the variable under the environment section of your docker-compose.yml file.

Verifying the Network Binding

After starting the server, confirm it is listening on all interfaces:

netstat -tlnp | grep 8080

Or test accessibility from a remote machine:

curl http://<server-ip>:8080/health

A successful response confirms the API is reachable via the wildcard address.

When to Use 0.0.0.0

Binding to 0.0.0.0 is necessary when:

• Running in Docker containers: The container must accept traffic from the Docker bridge network.
• Cloud deployments: Virtual machines require binding to external interfaces to receive traffic from load balancers.
• Remote development: Accessing the API from another device on your local network.

Avoid using 0.0.0.0 in production without proper firewall rules, as it exposes the service on every network interface attached to the host.

Summary

• The binding logic lives in server/src/index.ts, where app.listen() consumes the HOST environment variable.
• Set HOST=0.0.0.0 to listen on all IPv4 interfaces instead of just localhost.
• The default behavior includes a fallback to 0.0.0.0 in the source code, but explicit configuration prevents ambiguity.
• Docker deployments require the -e HOST=0.0.0.0 flag or equivalent compose configuration.
• Verify connectivity using netstat or remote curl commands to ensure external accessibility.

Frequently Asked Questions

What is the default bind address for FreeLLMAPI?

By default, FreeLLMAPI attempts to bind to the address specified in the HOST environment variable. When HOST is unset, the application falls back to 0.0.0.0 as defined in the server/src/index.ts fallback logic, though some documentation suggests 127.0.0.1 is the intended default for security. Always verify your specific version's behavior by checking the app.listen() implementation.

Is binding to 0.0.0.0 a security risk?

Binding to 0.0.0.0 exposes the API on every network interface, including public-facing ones. This is necessary for containerized environments but requires additional security measures such as firewall rules, reverse proxies with authentication, or VPC isolation to prevent unauthorized access.

How do I bind FreeLLMAPI to a specific interface only?

Instead of 0.0.0.0, set HOST to the specific IP address of the desired network interface (e.g., HOST=192.168.1.100). The app.listen() function in server/src/index.ts will then bind exclusively to that address, restricting traffic to that specific subnet.

Why can't I reach FreeLLMAPI from another machine when using Docker?

If you can access the API via localhost from the host machine but not from external sources, the container is likely binding to 127.0.0.1 inside the container namespace. You must set HOST=0.0.0.0 to ensure the process listens on the container's bridge interface, which Docker then maps to the host through port forwarding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}