How to Configure ReClip Using Environment Variables: A Complete Guide

ReClip can be configured at runtime using two environment variables—PORT and HOST—that are read via os.environ.get() in the Flask application entry point.

ReClip is an open-source image search tool that uses CLIP embeddings to find visually similar images. The repository exposes a web interface through a Flask application, and you can customize its network binding without modifying any code by using standard environment variables. This guide covers exactly which variables are supported, where they are read in the source code, and how to use them in local development or Docker deployments.

Environment Variables Supported by ReClip

ReClip reads two environment variables during application startup in app.py:

Variable	Default Value	Purpose
PORT	8899	TCP port for the web server
HOST	127.0.0.1	Network interface to bind to

These defaults ensure the application runs securely in local development mode, listening only on the loopback interface.

Where Environment Variables Are Read in the Source Code

The configuration logic is implemented in app.py at lines 208–210:

# app.py

port = int(os.environ.get("PORT", 8899))
host = os.environ.get("HOST", "127.0.0.1")
app.run(host=host, port=port)

The code uses Python's standard os.environ.get() with fallback defaults, making the variables optional. Changes take effect immediately on the next application start—no rebuild or reinstallation is required.

Running ReClip Locally with Custom Environment Variables

For local development, export variables in your shell before starting the application:

# Bind to all interfaces and use port 8080

export PORT=8080
export HOST=0.0.0.0

# Start the Flask server

python app.py

The server will now be accessible from other machines on your network at http://<your-ip>:8080.

You can also set variables inline for a single command:

PORT=3000 HOST=0.0.0.0 python app.py

Docker and Docker Compose Configuration

The repository includes a docker-compose.yml file that forwards environment variables to the container. The standard pattern uses shell variable substitution with defaults:

services:
  reclip:
    build: .
    environment:
      - PORT=${PORT}
      - HOST=${HOST}
    ports:
      - "${PORT:-8899}:8899"

Using a .env File

Create a .env file in the project root:

PORT=8080
HOST=0.0.0.0

Docker Compose automatically loads this file, so running docker-compose up will apply your configuration:

docker-compose up -d

The container's internal port 8899 is mapped to your specified host port (8080 in this example).

Runtime Overrides Without a .env File

Pass variables directly to the Docker Compose command:

PORT=3000 HOST=0.0.0.0 docker-compose up -d

Or export them first:

export PORT=5000
export HOST=0.0.0.0
docker-compose up -d

Key Files for Environment Configuration

Understanding these source files helps when troubleshooting or extending ReClip's configuration:

• app.py — Main Flask application entry point where PORT and HOST are read from the environment
• docker-compose.yml — Service definition that propagates environment variables into the container
• Dockerfile — Container build instructions that install dependencies and set the working directory

Common Configuration Scenarios

Expose ReClip on a Custom Port

Use when port 8899 is already occupied on your system:

PORT=9000 python app.py

Make ReClip Accessible from Other Devices

Required for remote access or when running in a container on a server:

HOST=0.0.0.0 PORT=8080 python app.py

Production Deployment with Docker

Combine both variables with Docker Compose for a production-ready setup:

# .env

PORT=80
HOST=0.0.0.0

Then run with a reverse proxy (nginx, Traefik, etc.) handling SSL termination.

Summary

• Two variables control ReClip's network behavior: PORT (default 8899) and HOST (default 127.0.0.1)
• Configuration happens in app.py via os.environ.get() with sensible defaults
• Local development: Export variables in your shell or pass them inline
• Docker deployments: Use a .env file or environment blocks in docker-compose.yml
• No code changes required: The application reads these values at startup each time

Frequently Asked Questions

What environment variables does ReClip support?

ReClip supports exactly two environment variables: PORT for the TCP port and HOST for the bind address. These are read in app.py using os.environ.get() with defaults of 8899 and 127.0.0.1 respectively. No other runtime configuration is currently implemented in the codebase.

Can I use a .env file with ReClip?

Yes. When running with Docker Compose, create a .env file in the project root containing PORT and HOST values. Docker Compose automatically loads this file and substitutes variables into the docker-compose.yml service definition. For local Python execution, you would need to load the file manually with a tool like python-dotenv or export variables yourself.

Why does ReClip default to 127.0.0.1 instead of 0.0.0.0?

The default HOST=127.0.0.1 is a security-conscious choice for local development, preventing accidental exposure of the development server to the network. Production deployments or containerized environments should explicitly set HOST=0.0.0.0 to allow external connections.

Do I need to rebuild the Docker image after changing environment variables?

No. Environment variables are read at container runtime, not build time. Simply restart the container with docker-compose up after modifying your .env file or shell exports. The image itself remains unchanged.

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