How to Use Executioner: Install, Scope, Agents, Findings

Executioner is an open-source desktop app that gives AI agent command-line tools a shared engagement workspace, 33 bundled security tool wrappers and an embedded browser, all on your own machine. This guide walks through a first engagement from install to exported findings, using only what the project's README, SECURITY.md, install scripts and source support. It was written against version 0.0.6.

Authorised use only. Do these steps only against systems you own or have explicit written permission to test: a bug bounty programme you have joined, a pentest with a signed scope, a CTF or your own lab. The README says the same: "You are responsible for what you run." This guide contains no exploit steps and no payloads, by design.

We did not run the app for this guide. Labels come from the source code and may differ slightly on screen; if something does not match, trust the app and the README. For what Executioner is and what to weigh before adopting it, read our Executioner explainer.

Before you start: prerequisites

• A supported machine. The install scripts handle Linux x86_64, macOS (Apple silicon and Intel) and 64-bit Windows. Other combinations stop with a "no build" error.
• At least one agent CLI, installed and signed in: Claude Code, Codex, Gemini, Cursor, OpenCode or Hermes. Executioner does not bundle a model. Each agent CLI talks to its own provider under your account, so anything it reads can reach that provider.
• The security tools you plan to run. Executioner wraps tools; it does not install the underlying programs for you. Settings has a Tools page that probes each one and shows an install hint when it is missing.
• Optional: a remote host reachable over SSH (key-based, since the app never prompts for a password), or Docker with an image such as kalilinux/kali-rolling.
• Authorisation and scope in writing, before you create the engagement (see the checklist at the end).

Step 1: Install it, the careful way

The README's commands are below, exactly as published. They download the latest release, check it against the published checksums and install it.

Linux and macOS

curl -fsSL https://raw.githubusercontent.com/dbx0/executioner/main/install.sh | bash

On Linux it adds Executioner to your app launcher and puts an executioner command in ~/.local/bin, without sudo. On macOS it installs Executioner.app into Applications (or ~/Applications if that is not writable).

Windows (PowerShell)

irm https://raw.githubusercontent.com/dbx0/executioner/main/install.ps1 | iex

Run the same command again to update. You can also download a .dmg, -setup.exe, .AppImage or .deb from the latest release.

PlayCISO advice: inspect before you pipe

Piping a script from the internet into a shell runs whatever it contains with your privileges. The scripts verify a SHA-256 checksum, but the checksum file comes from the same release as the download, so it protects against a corrupted file, not a compromised release. A safer sequence on Linux or macOS:

# 1. Download the script, do not run it yet
curl -fsSL https://raw.githubusercontent.com/dbx0/executioner/main/install.sh -o install.sh

# 2. Read it (it is short). Look at what it downloads, where it writes, what it deletes
less install.sh

# 3. Optional: pin a version you have reviewed instead of "latest"
EXECUTIONER_VERSION=v0.0.6 bash install.sh

The script supports the EXECUTIONER_VERSION variable for this purpose, and the Windows script supports $env:EXECUTIONER_VERSION. To verify a release asset by hand, download both the asset and SHA256SUMS.txt from the release page and compare the hashes yourself (sha256sum on Linux, shasum -a 256 on macOS, Get-FileHash in PowerShell). The asset names follow the pattern Executioner-<version>-linux-x86_64.AppImage, -mac-arm64.zip, -mac-x64.zip and -win-x64-setup.exe. Do this on a test machine first if you manage a fleet. We could not confirm whether the published builds are code-signed; the project's release workflow treats signing as optional, and on macOS the script removes the quarantine flag.

To uninstall (Linux and macOS): curl -fsSL https://raw.githubusercontent.com/dbx0/executioner/main/install.sh | bash -s -- --uninstall. On Windows, set $env:EXECUTIONER_UNINSTALL='1' before the Windows command. Engagement folders and settings are left in place.

Step 2: Onboarding

The first launch runs a short wizard (you can skip it and change everything later in Settings):

1. Default agent. Pick the agent new sessions start with. Only installed CLIs can be chosen, so an unavailable one is your cue to install it first.
2. Theme. Cosmetic.
3. Execution. Choose Local (this machine), SSH (a remote host) or Docker (a container). SSH and Docker add a connection step in which you enter the details and run a test. A passing test is what unlocks the last step. For Docker the test pulls the image and runs a throwaway container, because the Docker backend uses a fresh container for each command, so anything you install inside a running command does not persist for the next one.
4. Engagement. Open an existing engagement or create a new one.

Tip: if you plan to try the app on real data later, point it at a disposable location while you learn. The project's own contributors do this with the EXECUTIONER_HOME environment variable, which moves the user-level directory (workflows, connections, secrets and saved agents) somewhere throwaway.

Step 3: Create an engagement

An engagement is a folder. Inside it Executioner keeps a hidden .executioner directory (a SQLite database and a config file) plus workflows and evidence folders. A new engagement also scaffolds working folders (recon, vuln, notes, docs), a hunt log, and a copy of the scope text you pasted. You can copy it, back it up, or put it under version control; a source-control panel is built in.

When creating one you can fill in the details yourself or use Start with AI, which takes a free-text programme description and the scope text.

Step 4: Paste the scope from the programme page

1. Copy the scope section from the programme page (HackerOne, Bugcrowd or the policy page), including the exclusions and the rules about what testing is allowed.
2. Paste it into the Start with AI scope box when creating the engagement, or, on an existing engagement, open Add rule and use its Start with AI tab. An AI agent reads it and drafts include and exclude rules for hosts, wildcards such as *.example.com, network ranges and URL patterns, with a note on why. On an existing engagement nothing is saved until you confirm a review step.
3. Read the result against the original page. Generated rules are a draft written by a model. Fix anything wrong in the Scope view, where you can add, edit or remove rules by hand; the whole target tree is re-judged each time.
4. Understand the three verdicts. In matches an include rule. Out matches an exclude rule. Unknown means nothing mentions the asset. Executioner does not refuse unknown assets, because pasted scopes are often incomplete, so stop and check before testing one.

Executioner's own tool descriptions say the browser reports an out-of-scope page without blocking it, and the built-in agent prompts ask agents to stay in scope. Neither is a technical barrier, so the discipline is yours. We cover this in the explainer.

Step 5: Run a tool

1. Open the Tools view and choose a tool. The 33 bundled tools cover recon (for example Subfinder, dnsx, WHOIS), web (for example httpx, Katana, ffuf), scanning (for example Nmap, Naabu, Nuclei) and network (for example SSLScan, testssl.sh, Traceroute).
2. Pick one or more targets from the tree. Prefer targets showing in scope.
3. Set the options in the form. A command preview shows the exact command that will run, with each target passed as its own argument.
4. Choose where to run it: this machine, an SSH host or a Docker backend.
5. Run it. Output is parsed into targets (new hosts, ports, technologies) in the tree. If a tool is missing, Settings → Tools shows the install hint for your operating system.

Start with passive or low-impact options and check the programme's rate limits before anything active. Each tool run is a real network action against a real system.

Step 6: Build a first workflow

Workflows chain nodes on a canvas: triggers (manual, schedule, on new target), logic (if, loop, merge, stop), tool nodes, agent nodes, HTTP requests, screenshots, notifications and scripts.

1. Open Workflows and create one. Either place nodes yourself, or describe what you want to the assistant in plain words and review the graph it proposes before it goes on the canvas.
2. Keep the first one small: a manual trigger, one recon tool, and a node that saves results to targets.
3. Run it from the Run workflow panel: choose the target and backend, and switch on step mode to advance node by node and see exactly what each one does.
4. Only then consider a schedule or an on-new-target trigger, and think about rate limits and scope first, because an automated workflow acts without you watching.

Be careful with imported workflows and custom nodes: SECURITY.md treats running commands from imported data as a threat. Review what a workflow runs before you import it. If it uses API keys, reference them by name through the secrets store rather than pasting values into nodes.

Step 7: Launch an agent, or a whole team

1. Use the spawn menu in the workspace to launch one of your installed agent CLIs into the engagement. It arrives with a briefing and a connection to the engagement's scope, targets, findings and workflows over a local MCP endpoint.
2. For a team, choose one of the built-in rosters: Recon & Strike (recon, scanner, exploit, reporter), Web AppSec (crawler, injection, authz, reporter) or Code Audit (mapper, auditor, reporter). Teams are built on Claude Code's sub-agents. The sidebar shows each sub-agent's status, and you get a notification when one needs input.
3. Watch it work in its terminal and stop it if it drifts. Agents run commands through a tool the project classes as dangerous, with a default 120-second limit per command, on whichever backend is selected.
4. Tell the agent your limits in your own words if the programme has them (request rate, no automated scanning of a given area, no account creation), and stop it if it drifts.

Workflow agent nodes (agents inside a workflow) run headless. For Claude, OpenCode, Codex and Gemini the app launches them in restricted modes; Cursor and Hermes cannot be fully restricted per launch, so a node refuses them unless you explicitly opt in. Leave that opt-in off unless you understand why you need it.

Step 8: Use the browser

From the spawn menu, open the engagement's browser. It sits next to the agent's terminal, so you see every click and can take the page back at any time. Each engagement's browser is isolated, with its own cookies and storage. Agents can read network traffic, change request headers, emulate a location, language or user agent, upload files and save screenshots as evidence. If it hits a CAPTCHA or an MFA prompt, the agent asks you in a bar above the page and waits. Complete the step yourself; do not hand over real credentials or one-time codes to a model unless your authorisation covers that account and you accept that the provider may see what the agent sees.

Step 9: Record and export findings

1. Agents, workflows and you all write to one findings list. Each finding carries a severity (critical, high, medium, low or info), a status (open, confirmed, false positive, discarded or fixed), the target it hit, who recorded it, and the evidence.
2. Triage in place. Confirm what you can reproduce yourself, mark false positives, and keep the raw request and response as evidence. Do not rely on an agent's severity: the project's own prompts ask agents to rate by demonstrated impact, but a human decides.
3. Click Export report in the Findings view. It writes a Markdown file called findings-YYYY-MM-DD-HHMM.md into a reports folder in the engagement.
4. Treat that file as a working document. Edit it, redact secrets and personal data to the minimum that proves the point, and check it against the programme's or client's template before submitting.

Safe-use checklist

• Written authorisation from someone entitled to give it, naming the assets, dates and permitted techniques. A bug bounty policy counts only for the programme that publishes it.
• Scope rules that match the paper, reviewed by a human after the AI parses them. Treat "unknown" as "stop and ask".
• Rate limits and impact limits. Agree request rates and forbidden actions (denial of service, data modification, account takeover of real users) up front, and tell the agent. The built-in team prompts say never to run destructive or denial-of-service actions, but a prompt is not a guarantee.
• A named operator watching. Do not leave agents or schedules running unattended against a client.
• Evidence handling. The engagement folder holds client data and proof material. Encrypt the disk, restrict who can open the folder, redact before sharing, and delete it when your contract says so.
• Keep API keys local. Store integration keys through the Secrets page, not in prompts, notes or workflow text. They live in a user-level SQLite file with no encryption that we could see, so protect the machine. Never paste a key into a chat with an agent.
• Know where your data goes. Each agent CLI sends what it reads to its model provider. Check that your contract allows that provider, or use an approved agent.
• Least privilege for the agent's host. Prefer a dedicated test machine, VM or Docker backend over your daily laptop. Agents run real commands with your identity when set to Local.
• Update deliberately. Only the latest release gets security fixes, so check release notes, then update. Report vulnerabilities in Executioner itself privately through GitHub's private vulnerability reporting, as SECURITY.md asks.

To practise deciding what an agent should be allowed to do, try the Agent Tool-Scope and Least-Privilege Lab. It is Pro, free to try with a free account. To see how Executioner sits among other AI pentesting tools, use the pentest tools comparison.

Troubleshooting

Frequently asked questions

How do I install Executioner?

On Linux or macOS the README gives a curl command that pipes install.sh to bash; on Windows it gives a PowerShell command using irm and iex. You can also download a .dmg, -setup.exe, .AppImage or .deb from the latest GitHub release. We recommend downloading and reading the script before running it, and verifying the checksum yourself.

What do I need before I start?

At least one agent CLI installed and signed in (Claude Code, Codex, Gemini, Cursor, OpenCode or Hermes), the security tools you plan to run, and written authorisation for whatever you will test. Building from source also needs Node 24 and pnpm 12.

How do I add a bug bounty scope to Executioner?

Create a new engagement with the Start with AI option and paste the scope text from the programme page, or on an existing engagement use Add rule and its Start with AI tab (you confirm a review step before anything is saved). You can also add include and exclude rules by hand in the Scope view. An AI agent turns pasted text into rules, and each target then shows an in, out or unknown verdict. Always read the generated rules against the original page.

Why does a target show "unknown" scope?

Unknown means no scope rule mentions the asset. Executioner does not treat that as out of scope, because a pasted scope is often incomplete. Stop and check before testing it, and add an include or exclude rule once you know.

Can I run tools without an AI agent?

Yes. Each bundled tool has a form with a preview of the exact command, and you can run it locally, over SSH or in a Docker container. Workflows without an agent node also run without a model. The agent features need an agent CLI.

How do I export findings from Executioner?

Open the Findings view and use Export report. The source writes a Markdown file named findings-YYYY-MM-DD-HHMM.md into a reports folder in the engagement. The code describes it as a working document rather than a finished submission, so edit and redact it before sending.

Where does Executioner store my data?

In an engagement folder you choose, which holds a hidden .executioner directory with a SQLite database and config, plus workflows and evidence folders. API-key secrets are stored in a user-level ~/.executioner directory. The README and CONTRIBUTING.md differ slightly on what lives where, so inspect both before copying an engagement to someone else.

How do I uninstall Executioner?

On Linux or macOS run the README's uninstall command (the install script with --uninstall). On Windows set the EXECUTIONER_UNINSTALL environment variable to 1 and run the Windows command again. Engagement folders and settings are left in place.

Sources

• Executioner README (install commands, features, responsible use)
• install.sh and install.ps1
• SECURITY.md (reporting and supported versions)
• CONTRIBUTING.md (development setup, EXECUTIONER_HOME, repository layout)
• dbx0/executioner repository, tag v0.0.6 (1 November 2026)
• Executioner latest release (not checked by us)