Rev·Deck AI-Assisted Reverse Engineering Workstation

To perform isolated tasks without polluting the main chat context, use New sub-investigation.

1. Enter a one-line briefing for the sub-thread.
2. Work with a fresh conversation context over the same binary.
3. When finished, choose Return conclusion to parent.

Behavior: Rev·Deck makes one bounded model call to validate evidence citations and adds a provenance-marked conclusion card to the parent chat. The full sub-thread transcript is not added to the parent, only the compact conclusion. If a conclusion has no validated citations, it is marked as unverified.

The fastest way to run Rev·Deck is using Docker Compose. This starts both the web application and the Ghidra service.

1. Copy the example environment file to .env.
2. Edit .env to set API_BASE and MODEL_NAME (and API_KEY if required).
3. Run docker compose up --build.
4. Access the UI at http://127.0.0.1:5000.

Note: Docker Compose will fail early if API_BASE or MODEL_NAME are missing.

cp .env.example .env      # set API_BASE and MODEL_NAME; set API_KEY if required
docker compose up --build

Rev·Deck supports any OpenAI-compatible Chat Completions endpoint. Configuration is handled by setting API_BASE, API_KEY, and MODEL_NAME in your .env file.

Ollama

API_BASE=http://127.0.0.1:11434/v1
API_KEY=not-used
MODEL_NAME=qwen3:8b

OpenRouter

API_BASE=https://openrouter.ai/api/v1
API_KEY=replace-with-your-key
MODEL_NAME=anthropic/claude-opus-4.8

OpenAI

API_BASE=https://api.openai.com/v1
API_KEY=replace-with-your-key
MODEL_NAME=replace-with-a-supported-model-id

LM Studio, vLLM, or llama.cpp

API_BASE=http://127.0.0.1:1234/v1
API_KEY=not-used
MODEL_NAME=replace-with-the-served-model-id

After uploading a binary, you can use two main workspace tabs:

1. Analysis Tab

Provides deterministic evidence views:

• Summary, Functions, Imports, Strings, Query View
• Function Inspector: Pseudocode, cross-references, bounded call graph, and hexdump.
• Advanced (if supported by Ghidra service): Types, globals, sidecar annotations, and Attack Surface ranking.

2. Chat Tab

Interact with the LLM in two modes:

• Copilot (Default): One bounded step/tool call per message for ad-hoc questions.
• Autonomous: Runs a named, budgeted workflow with a live activity timeline.

Note on Budgets: Both modes use a step budget. If a run reaches its budget, you can select Continue to resume the conversation using existing evidence without redoing completed tool calls.

If you want to run only the Ghidra service via Docker, use the following command. Ensure you map a local directory to /data/ghidra_projects to persist your analysis data.

docker run --rm \
  -p 127.0.0.1:9090:9090 \
  -v "$(pwd)/data:/data/ghidra_projects" \
  --security-opt no-new-privileges:true \
  biniamfd/ghidra-headless-rest:latest

To run without Docker, you need Python 3.10+ and Node.js 18+.

1. Set up a virtual environment and install dependencies:

   python -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt

2. Vendor the Mermaid runtime:

   npm ci && npm run vendor

3. Configure environment variables (Note: Python does not load .env automatically, so you must export them):

   cp .env.example .env
   set -a; source .env; set +a

4. Start the Ghidra service separately, then start the web UI:

   python webui/app.py

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
npm ci && npm run vendor

cp .env.example .env
set -a; source .env; set +a

# Start the separate Ghidra service, then:
python webui/app.py

Rev·Deck is configured via environment variables. You must copy .env.example to .env and populate the required fields.

The application manages a workspace that transitions between an 'empty' state and an 'active' state based on the selected job.

Workflow:

1. Job Selection: When a job is selected via the jobs controller, the system checks if the analysis is ready using isAnalysisReady(job.status).
2. Empty State: If the job is not ready (e.g., still queued or running), showJobState(job) is called. This hides the workspace and shows a placeholder title/body.
3. Active State: Once the job status indicates analysis is ready, activateCompletedJob(jobId) is called. This:
   • Hides the empty state.
   • Shows the workspace.
   • Enables the Chat Composer.
   • Resets the Analysis controller.
   • Loads the chat threads for that specific jobId.
4. Removal: Removing a job resets the selectedJob in the store and returns the UI to the 'No job selected' empty state.

Common issues and solutions:

• "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 is an older version that doesn't support these features.
• Chat errors immediately: Verify API_BASE, API_KEY, and MODEL_NAME are correct and the provider is reachable within LLM_TIMEOUT.
• Upload rejected as too large: Increase the MAX_UPLOAD_BYTES environment variable.
• Large analysis times out: Increase the Ghidra container's ANALYSIS_TIMEOUT (e.g., 5400 for large binaries) and re-upload.
• A citation shows "(unverified)": The model cited evidence it never actually retrieved; treat this as an unconfirmed hypothesis.

The ghidra service provides the headless REST API for Ghidra. You can customize its behavior using the following environment variables in your .env file:

• GHIDRA_IMAGE: The Docker image to use. Defaults to biniamfd/ghidra-headless-rest:1.2.1@sha256:971591a3a8448d8ed969079b452306e806f36079c3ddd298f4a618d6e2f1442d.
• ANALYSIS_TIMEOUT: The wall-clock cap for a single headless analysis in seconds. Default is 1800 (30 minutes). Increase this for large binaries (e.g., 10k+ functions).
• DECOMPILE_TIMEOUT: Timeout for decompilation in seconds. Default is 30.

# Example .env configuration for Ghidra
GHIDRA_IMAGE=biniamfd/ghidra-headless-rest:1.2.1
ANALYSIS_TIMEOUT=3600
DECOMPILE_TIMEOUT=60

When using the Autonomous chat mode, you can trigger specific workflows. Some workflows require a target function address.