api/{debug}
Open workspaceDocker install docs
Overview

Agent Manual

Use this page as a technical reference for agent health checks, Docker networking, localhost remapping, saved settings, and recovery actions.

At a glance

  • Browser -> agent: the UI should reach `http://127.0.0.1:8080/health` on the same machine.
  • Dockerized agent -> host localhost: `localhost`, `127.0.0.1`, `::1`, and `*.localhost` are remapped through `host.docker.internal`.
  • Primary health check: `curl http://127.0.0.1:8080/health`.
  • Need the startup command again? Reopen the setup dialog from the workspace or setup modal.
Start here

Quick start checks

If you have not yet identified the failing layer, run through these in order.

  1. 1

    Confirm Docker Desktop or the Docker daemon is running.

  2. 2

    Confirm the `apidebug-agent` container exists and is still running.

  3. 3

    Confirm `http://127.0.0.1:8080/health` responds on the same machine as the UI.

  4. 4

    Confirm the container includes the `host.docker.internal` host-gateway mapping if host localhost targets still fail.

  5. 5

    Confirm the UI agent settings point to the host and port where the agent is actually listening.

Reference

Core commands

Grouped by use case so you can verify one layer at a time instead of collecting unrelated output.

Container state

Check whether the agent exists, is running, and is healthy.

docker ps
docker logs apidebug-agent
docker inspect apidebug-agent

Host reachability

Verify the published port answers on the host before debugging UI state.

docker port apidebug-agent
curl http://127.0.0.1:8080/health

Lifecycle actions

Use these only after you know which layer is failing.

docker compose up -d
docker restart apidebug-agent
AI Insight

LLM integration

Use this section to configure Groq for AI Insight when starting the agent with Docker.

Get a Groq API key

Sign in to the Groq console, create an API key, then paste that value into the `GROQ_API_KEY` environment variable in your Docker command.

Open Groq keys

Docker run with Groq API key

Pass the API key into the container so AI Insight works when the agent runs in Docker.

docker run -d --name apidebug-agent --add-host=host.docker.internal:host-gateway -p 127.0.0.1:8080:8080 -e GROQ_API_KEY="YOUR_GROQ_API_KEY" -e APIDEBUG_AGENT_LISTEN=0.0.0.0:8080 -e APIDEBUG_AGENT_DB_PATH=/data/apidebug.sqlite -e APIDEBUG_AGENT_LOG_DIR=/data/logs -v apidebug-agent-data:/data apidebug-agent

Docker run with optional Groq overrides

Use this if you want to set the Groq model or API URL explicitly in Docker.

docker run -d --name apidebug-agent --add-host=host.docker.internal:host-gateway -p 127.0.0.1:8080:8080 -e GROQ_API_KEY="YOUR_GROQ_API_KEY" -e APIDEBUG_AGENT_LLM_PROVIDER=groq -e APIDEBUG_AGENT_GROQ_MODEL=llama-3.3-70b-versatile -e APIDEBUG_AGENT_GROQ_API_URL=https://api.groq.com/openai/v1/chat/completions -e APIDEBUG_AGENT_LISTEN=0.0.0.0:8080 -e APIDEBUG_AGENT_DB_PATH=/data/apidebug.sqlite -e APIDEBUG_AGENT_LOG_DIR=/data/logs -v apidebug-agent-data:/data apidebug-agent

LLM setup notes

  • AI Insight uses the agent-side Groq integration, so the browser never needs the API key directly.
  • If the key is missing, AI Insight returns `API key not provided` and the drawer links back to this section.
  • The agent reads `GROQ_API_KEY` from the environment. Optional overrides include `APIDEBUG_AGENT_LLM_PROVIDER`, `APIDEBUG_AGENT_GROQ_MODEL`, and `APIDEBUG_AGENT_GROQ_API_URL`.
  • To get a Groq API key: create or sign in to your Groq account, open the API Keys page in the Groq console, create a new key, and copy it into the `GROQ_API_KEY` value in the Docker command.
  • Replace `YOUR_GROQ_API_KEY` with your real Groq key before running the container.
  • After changing environment variables, recreate or restart the Docker container so the new values are loaded.
Networking

Docker localhost remap

Use this when the browser can talk to the local agent, but requests to services on your machine still fail from inside the Dockerized agent.

How it works

  • The UI reaching `127.0.0.1:8080` only proves the browser can talk to the agent. Requests to `localhost` inside Docker are a separate path.
  • The Dockerized agent remaps `localhost`, `127.0.0.1`, `::1`, and `*.localhost` request targets to `host.docker.internal` at dial time.
  • This preserves the original request host for HTTP `Host`, TLS SNI, and certificate validation.

Verify the host-gateway mapping

This is the quickest confirmation that the container was started with the Docker localhost remap support.

docker inspect apidebug-agent --format '{{json .HostConfig.ExtraHosts}}'

If localhost targets still fail

  • Confirm the container includes `host.docker.internal:host-gateway` in `ExtraHosts`.
  • Confirm the target service is actually listening on your machine and not only inside another container or VM.
  • If you start the container manually, make sure the Docker command includes `--add-host=host.docker.internal:host-gateway`.
Connectivity

Port and agent connectivity

Prove the host can reach the agent before debugging settings or outbound request behavior.

Connectivity checks

  • If port `8080` is already in use, Docker cannot bind `127.0.0.1:8080:8080` and the UI will never reach the agent there.
  • Use `docker port apidebug-agent` or `docker inspect apidebug-agent` to verify the container is actually bound to `127.0.0.1:8080`.
  • If you changed `APIDEBUG_AGENT_LISTEN`, make sure the process still listens on `0.0.0.0:8080` when Docker publishes port `8080`.
  • If `curl http://127.0.0.1:8080/health` fails on the host, fix host connectivity before debugging the UI.
Configuration

Agent settings

Check saved host and port values if the agent is healthy but the UI still shows a disconnect.

Settings notes

  • The UI does not always target `127.0.0.1:8080`; users can save a custom host and port in Agent settings.
  • A valid-looking host or port can still be wrong for the running container, so re-check the saved target if health checks fail.
  • After changing settings, retry the connection check and confirm the new target is reachable from the same machine.
Operations

Logs and persistence

Prefer logs first. Only debug volumes, paths, or persisted state after logs point there.

Logs and data

  • The Docker setup stores SQLite data and logs under `/data` inside the container, backed by the named volume `apidebug-agent-data`.
  • Use `docker logs apidebug-agent` first for startup and health failures; inspect the volume only if logs point to data-path issues.
  • Restarting the container should not delete request history, but clearing agent data is expected to remove the local database and logs.
  • Invalid `APIDEBUG_AGENT_LOG_MAX_SIZE_MB` or `APIDEBUG_AGENT_LOG_MAX_FILES` values fall back to defaults, which can hide a bad config change.
Runbook

Recovery steps

Take the smallest action that proves the next layer, rather than restarting everything at once.

  1. 1

    Run `docker ps` and confirm `apidebug-agent` is listed.

  2. 2

    If the container is missing, reopen the setup dialog and reuse the startup command shown there.

  3. 3

    If it exists but is unhealthy or stopped, inspect logs with `docker logs apidebug-agent` and restart with `docker restart apidebug-agent` after fixing the cause.

  4. 4

    Run `curl http://127.0.0.1:8080/health` on the host to confirm the published port works outside Docker.

  5. 5

    If requests to host localhost services fail from inside Docker, verify the container was started with the `host.docker.internal:host-gateway` mapping.

  6. 6

    If the UI is targeting a custom host or port, re-save the correct values in Agent settings and retry the connection check.

  7. 7

    Only recreate the container or clear the Docker volume after logs show a persistent runtime or storage problem.