To run only the Ghidra service:

For a reproducible pin, use the tested release digest instead of latest:

Prerequisites

• Docker and Docker Compose (for the Quick Start path), or Python 3.10+ and Node.js 18+ (for running from source).
• An OpenAI-compatible LLM endpoint (local or hosted) and model name.
• The public Ghidra image: biniamfd/ghidra-headless-rest:latest.

Essential environment variables

Copy .env.example to .env and fill these in; see that file for the full list and defaults.

LLM provider

Rev·Deck talks to any OpenAI-compatible Chat Completions endpoint through the OpenAI SDK, configured entirely by API_BASE / API_KEY / MODEL_NAME. There is no provider-specific header, parameter, or model logic: a local Ollama server (API_BASE=http://127.0.0.1:11434/v1), a self-hosted vLLM/llama.cpp/LM Studio endpoint, OpenAI itself, or a gateway such as OpenRouter all work the same way.

Example .env provider settings (use placeholders, never commit real keys):

By default (LLM_STREAM=auto) the assistant requests a streamed response and relays tokens to the browser as they arrive. Streaming also gives a stronger cancellation guarantee: when you stop a response (or close the tab), Rev·Deck promptly closes the underlying provider stream and performs no further tool or model rounds, so upstream generation is torn down rather than left running to completion in the background.

Caveats:

• Billing. Cancelling closes the stream on our side immediately, but some hosted providers still bill for tokens they had already generated (or for the whole completion) regardless of an early client disconnect. The guarantee is about not doing more work, not about a provider's billing policy.
• Compatibility. Not every OpenAI-compatible endpoint accepts streaming-with-tools. Under auto, if the provider rejects the streamed request with a compatibility error (HTTP 400/404/405/422) before any content or tool-call output, Rev·Deck falls back to a single blocking call once and remembers that for the rest of the process. Auth (401/403), rate-limit (429), and server (5xx) errors are not treated as compatibility problems and are surfaced as errors instead of silently retried. Set LLM_STREAM=false to skip streaming entirely, or LLM_STREAM=true to require it (no fallback).

How to use

Open the app and upload a binary to start an analysis job. Obvious plain-text content asks for confirmation before it is sent to Ghidra; use the explicit raw- binary override only when the content is intentionally firmware/data rather than an executable format. Once analysis completes, switch between two workspace tabs:

• Analysis — deterministic evidence views: summary, functions (filter/paginate), imports, strings, a query view, a function inspector (pseudocode, cross-references, bounded call graph, hexdump), and — when the connected Ghidra service supports them — types, globals, sidecar annotations, archive export, and a deterministic Attack Surface ranking with explainable positive/mitigating signals and evidence coverage.
• Chat — the assistant, in one of two modes:
  • Copilot (default): one bounded step/tool call per message, for ad-hoc questions.
  • Autonomous: start a named, budgeted workflow that runs multiple bounded steps on its own and shows a live activity timeline as it works.

Both modes take a per-task step budget, and a No step limit option that runs until the task finishes (still capped by MAX_STEP_BUDGET so a looping model cannot run away). If a run reaches its budget, it reports partial results and offers Continue — which resumes the same conversation using the evidence already retrieved, without redoing completed tool calls. Cost grows with the number of tool/model calls, so higher budgets cost more.

Available workflows:

Focused sub-investigations

Each analysis job has a Main chat plus optional focused sub-threads. Choose New sub-investigation, enter a one-line briefing, and work with a fresh conversation context over the same binary and the same read-only tools. Thread histories remain isolated, and only one thread streams at a time.

When the focused work is ready, choose Return conclusion to parent. Rev·Deck makes one bounded model call over that sub-thread only, validates its evidence citations, and adds one provenance-marked conclusion card to the parent. The full branch remains reopenable, while the parent context receives only the compact conclusion—not the branch transcript. A returned card with no validated citations is explicitly marked unverified.

Assistant answers cite evidence inline as [function:0xADDR], [string:0xADDR], or [import:name]. Citations are checked against what was actually retrieved during the turn; a citation that doesn't match is flagged "(unverified)" and should be treated as an unconfirmed claim, not fact.

Mermaid diagrams in assistant output (e.g. call-graph sketches) render in a sandboxed frame with no external network access.

Architecture

The browser talks only to the Rev·Deck web application. Rev·Deck coordinates the configured LLM and the headless Ghidra service, then presents the resulting evidence and agent activity in one workspace.

Running from source

Open http://127.0.0.1:5000. Docker Compose reads .env automatically; source execution requires exporting it as shown above. The Flask development server is fine for local use; the Docker image runs Gunicorn.

Security / local-only boundary

This is designed for one trusted analyst on their own machine — not for multi-user or public hosting. By default the app and the Ghidra service bind only to 127.0.0.1, debug mode is off, uploaded binaries are never executed, and the LLM provider key stays server-side.

Testing

Troubleshooting

• "Service offline" / /readyz returns 503 — the Ghidra service is unreachable at GHIDRA_API_BASE, or API_BASE/MODEL_NAME is unset.
• Types/Globals/Annotations show "requires v1" — the connected Ghidra service doesn't advertise that capability; expected on older services.
• Chat errors immediately — verify API_BASE/API_KEY/MODEL_NAME and that the provider is reachable within LLM_TIMEOUT.
• Upload rejected as too large — raise MAX_UPLOAD_BYTES.
• Upload looks like plain text — Rev·Deck asks before sending it to Ghidra; continue as raw binary only when intentional.
• Large analysis times out — increase the Ghidra container's ANALYSIS_TIMEOUT (for example 5400 for 10k+ function C++/Android binaries) and re-upload. LLM_TIMEOUT is unrelated.
• A citation shows "(unverified)" — the model cited evidence it never actually retrieved; treat that claim as an unconfirmed hypothesis.