Home
Sign up — start free Sign in

BugTape docs

Local LLM diagnosis bridge

Run a diagnosis against your own checkout.

The local bridge sends one selected BugTape occurrence to a model that runs on your computer. BugTape stores the run and its result. BugTape does not receive the model URL, model key, source code, shell access, or a GitHub token.

This first release is a staged, diagnosis-only feature. Each project has its own rollout switch. New projects start with the switch off.

What one click does

  1. A user opens one issue and selects one occurrence.
  2. BugTape creates a redacted packet for that occurrence.
  3. The local bridge pulls one leased packet over outbound HTTPS.
  4. The bridge sends the packet to a loopback Ollama or OpenAI-compatible API.
  5. The bridge returns one bounded diagnosis.
  6. BugTape shows the result and the durable run timeline on the issue.

The run cannot edit files, run commands, create a branch, open a pull request, or write to GitHub. It has one attempt. A lost lease, cancellation, expired key, revoked key, or removed project grant stops the run.

Pair a project

Open Settings → Agents, select the project, and choose Connect local LLM. Enter a name and start pairing. BugTape shows a one-use code and a pinned npx command.

Run the command in a terminal. It reads the code through a hidden terminal prompt. The code does not enter the command line, URL, browser storage, or shell history. Compare these four values in the terminal and console:

  • bridge fingerprint;
  • BugTape origin;
  • project ID;
  • diagnose only capability.

Confirm only when all four values match. The bridge stores its project key in ~/.config/bugtape-agent/store.json. The directory mode is 0700; the file mode is 0600.

If the first heartbeat response is lost, the saved key remains in the store. Run the worker command shown in the console to retry activation. Replace the pairing only when the CLI says that it could not save the key.

Start an Ollama worker

Replace the model placeholder with a model that is already installed in Ollama:

npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter ollama --base-url http://127.0.0.1:11434 --model <installed-model>

The bridge accepts only loopback model URLs. It opens no listener. Use --bridge <id> for one saved bridge or --all for every saved bridge.

For a local OpenAI-compatible server:

BUGTAPE_PROVIDER_KEY=<local-key-if-required> npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter openai-compatible --base-url http://127.0.0.1:1234 --model <model>

The provider key stays inside the local process. The bridge never adds it to a BugTape request or log.

Test the connection

The fake adapter proves pairing, pull, lease, callback, and timeline without a model call:

npx --yes --package=https://app.bugtape.ai/sdk/agent-bridge/0.1.0/bugtape-agent-bridge-0.1.0.tgz bugtape-agent bridge start --bridge <bridge-id> --adapter fake --once

Its result starts with SIMULATED DIAGNOSIS (connection test only). It is not evidence that a model diagnosed the issue.

Packet limits and privacy

The packet contains the selected report, selected occurrence fields, and up to 120 allowlisted events. It has a 64 KiB limit. Each event has a 16 KiB limit. BugTape removes URL credentials, query strings, fragments, cookies, authorization values, session and CSRF values, JWT-like values, opaque secret forms, and email addresses. Paths become short hash values for correlation. DOM payloads, custom event payloads, attachments, and file bytes stay in BugTape unless the packet allowlist includes them.

The issue page shows source-evidence bytes, delivered packet bytes, redacted value count, and truncation. Every packet field remains untrusted model input. The adapter uses a separate system message that tells the model to treat packet text as data.

The result can contain a summary, confidence, references to the exact occurrence and included event IDs, and a test plan. The server rejects source changes, commands, another occurrence, a stale lease, a changed replay, or a result above 64 KiB.

Key authority

Pairing creates one key with only the repair_run action and one project grant. Normal key management cannot widen its actions, add another project, or extend its expiry. An admin or manager can shorten its expiry or revoke it. Revocation stops the next heartbeat or request. The bridge removes its local copy after a definitive invalid, forbidden, or revoked response.

Run states

The console keeps these states after reload:

packet_ready → delivered → acknowledged → diagnosing → diagnosis_ready

A run can instead end as canceled or failed_terminal. Lease expiry is terminal and does not start a second model call. BugTape may retry one uncertain HTTP command with the same command ID. It never retries the model call.