ChatMock

Follow these steps to set up and run ChatMock in a Docker environment:

1. Setup environment variables: Copy the example environment file to create your local configuration.

   cp .env.example .env

2. Authenticate with ChatGPT: Run the login service to obtain authentication tokens. This process requires a browser.

   docker compose run --rm --service-ports chatmock-login login

   • The command will print an auth URL. Copy and paste this into your browser.
   • If your browser cannot reach the container's localhost callback, copy the full redirect URL from the browser address bar and paste it back into the terminal when prompted.
   • The server should stop automatically once tokens are received and saved.

3. Start the server: Launch the ChatMock service in detached mode.

   docker compose up -d chatmock

   • The service uses the PORT defined in your .env file.
   • By default, ports bind to localhost. To allow remote connections, set CHATMOCK_PUBLISH_HOST=0.0.0.0 in your .env file.

ChatMock can be configured using a .env file or by passing environment variables. Key configuration options include:

The ModelCatalog uses a background thread to fetch updates from the Codex API to ensure the proxy remains responsive.

1. Caching: On initialization, it attempts to load a cache from cache_path (defaults to ~/chatmock_models_cache.json).
2. Stale-While-Revalidate: When models() or visible_models() is called, the catalog checks if the data is older than refresh_interval_seconds.
3. Background Refresh: If the data is stale, a daemon thread (chatmock-model-catalog-refresh) is spawned to fetch new data.
4. Non-Blocking: By default, calls to models() return the cached data immediately even if a refresh is in progress. If you require the absolute latest data, you must pass wait_for_refresh=True.
5. Error Resilience: If a background refresh fails, the catalog retains the last successful cache and continues to serve it, preventing model discovery failures from crashing the proxy.

Configuration options can be passed as flags after chatmock serve or set via environment variables.

ChatMock implements a session-based optimization layer to facilitate prompt caching and reduce redundant data transfer.

The Workflow:

1. Session Identification: ensure_session_id creates a unique ID based on the conversation's starting instructions and first user message.
2. Request Preparation: When a user sends a request, prepare_responses_request_for_session checks if the input list contains the history of the previous turn. If it does, it strips the history and attaches a previous_response_id to the payload.
3. State Tracking: As the model responds, the developer must call note_responses_stream_event (for streaming) or note_responses_final_response (for non-streaming) to store the response items and ID in the session state.
4. Reuse: The next request uses the stored state to perform the optimization described in step 2.

This mechanism relies on the _ResponsesSessionState which tracks last_request_payload, last_response_id, and last_response_items for every active session.

You can deploy ChatMock using Docker Compose with two primary services: the main server (chatmock) and a login helper (chatmock-login).

• chatmock service: Runs the main server using the serve command. It listens on a configurable port and persists data to a volume.
• chatmock-login service: Used to sign in with your ChatGPT account. This service uses the login command and is part of the login profile. To run it, you must specify the profile in your docker-compose command.

Data is persisted via the chatmock_data volume, which is mapped to /data inside the containers.

services:
  chatmock:
    image: ${CHATMOCK_IMAGE:-storagetime/chatmock:latest}
    container_name: chatmock
    command: ["serve"]
    env_file: .env
    environment:
      - CHATGPT_LOCAL_HOME=/data
      - PORT=${PORT:-8000}
    ports:
      - "${CHATMOCK_PUBLISH_HOST:-127.0.0.1}:${PORT:-8000}:${PORT:-8000}"
    volumes:
      - chatmock_data:/data

  chatmock-login:
    image: ${CHATMOCK_IMAGE:-storagetime/chatmock:latest}
    profiles: ["login"]
    command: ["login"]
    environment:
      - CHATGPT_LOCAL_HOME=/data
      - CHATGPT_LOCAL_LOGIN_BIND=0.0.0.0
    volumes:
      - chatmock_data:/data
    ports:
      - "${CHATMOCK_PUBLISH_HOST:-127.0.0.1}:1455:1455"

volumes:
  chatmock_data: