Skip to main content

ctf-flightdeck

A terminal harness for playing CTFs with AI agents, where you run the loop.

flightdeck pulls the board, runs your own no-model solvers first, starts agent lanes in parallel, and submits flags, while you watch every lane on one console and step in when one goes the wrong way: a hint, a redirect, a fork, a kill, or taking over its shell yourself.

The fleet view: a board of eight challenges on the left; on the right, six agent lanes sorted by what needs you, with chips for a found flag, a lane that ignores the hint, a web lane heading the wrong way and a live box a teammate holds; under the list, the found flag with 1 to submit it and 0 not to

The fleet view, from flightdeck mock: scripted lanes on invented challenges. More in the screenshot gallery.

Bring what you have: an API key (Anthropic, OpenRouter, OpenAI or a local model server), a coding-agent CLI (Claude Code, Codex), a folder of solver scripts.

Status: v0.2.0 (alpha). The console, agent lanes, your L1 solvers, CTFd events, team mode, alerts, practice scoring, post-flight reports and a light model per small job are built. Next: Autopilot, which runs an event end to end while you are away. See the roadmap and the changelog.

Try it with no setup

uvx ctf-flightdeck mock              # nothing installed, nothing spent: the console on scripted data

Once flightdeck is installed, the same console is flightdeck mock:

flightdeck mock                      # the default scenario: every alert, then a 43-challenge wave
flightdeck mock --scenario wave      # also: sstv, overthinking, web, team, flag
flightdeck mock --screenshot DIR     # headless: SVGs of the key moments

The mock uses no model and no network. Every challenge, teammate and flag in it is invented. space freezes its clock and . steps it; the other keys are the real console's (The console).

Quickstart

Needs Python 3.12+ on macOS or Linux (Windows through WSL), and Docker for the safest setup.

pipx install ctf-flightdeck   # or: uv tool install ctf-flightdeck   (from a clone: uv tool install .)
flightdeck init               # a few questions (provider, models, Docker or host); writes your config
# put your key in ~/.config/ctf-flightdeck/keys.env (chmod 600): init names the variable
flightdeck image build        # once, for Docker lanes: pulls Debian and common tools (about 700 MB)
flightdeck doctor             # checks your setup and says how to fix each problem
flightdeck practice           # 14 small practice challenges: spends tokens on your model API

practice and play spend money on your model API. Each lane waits for your approval at 400,000 tokens or $2 (token_cap and dollar_cap under [lanes] in your config, with an alert at 80%), four lanes run at a time by default, and nothing caps a whole run. With init --provider anthropic every lane starts on Claude Haiku 5.5 ($0.10 / $0.50 per million input / output tokens). It moves up to Sonnet or Opus 5.5, at 20 to 40 times that, only when you escalate it. A model on your own machine costs nothing (init writes no dollar cap for Ollama or an MLX server), and flightdeck mock spends nothing.

flightdeck on its own says what to do next on your machine. flightdeck doctor checks Python, the config, the key variables, a local model server and its models, the light model, Docker, the lane image and your terminal's size. Before the console opens, play and practice ask the model API whether it takes your key and serves every model in your ladder, and stop with what to fix if not. ctfdeck and ctf-flightdeck are other names for the flightdeck command.

Docker or host

init asks where lanes run. A lane is one agent working one challenge, with a shell of its own, and the question is where that shell is.

Docker is the default (runtime = "docker" under [lanes]). Each lane runs in its own container of the lane image, with only that lane's copy of the challenge in it, and your L1 solvers run in containers too. flightdeck image build builds the image once, and flightdeck image dockerfile prints what it builds. A lane of flightdeck's own loop gets no network unless its challenge has a live instance it may reach: a web origin, or a TCP service like nc host port (tcp://host:port in the challenge's urls). Under an event whose instance policy is confirm, the lane asks you first. It then gets Docker's bridge network, which reaches any host, not only the instance: there is no per-host allowlist yet. A coding-agent lane (--agent) is always on that network, for its CLI's API.

--host (or runtime = "host") runs lane commands as you, on this machine. A lane can read your files, your keys file and flightdeck's own environment, and send what it reads to its model's API, which nothing can take back. flightdeck says so before every host run. A lane's commands get an environment built from an allowlist, with no keys in it, and the run log, the console, transcripts, reports and writeup drafts show a key's name but not its value. That is cleanup, not a fence: use Docker, a disposable VM, or a separate key with a low limit.

A coding-agent CLI holds its own credential, and the commands it runs can read it, in Docker too: give it a key you can revoke, with a low spending limit. Practise in Docker: on the host, a lane can read the practice set's reference solutions in a clone of this repository.

Words used here

  • Board: a folder of challenge folders, each with a challenge.json and its handout files (Boards). With CTFd, flightdeck pulls one into a folder.
  • Lane: one agent working one challenge: a model conversation with its own shell, in a container (or on this machine with --host). max_lanes run at once (4 by default); the rest queue.
  • Ladder: your models, weakest first ([models] ladder). Lanes start on the first. Escalate (e) restarts a lane on the next one, with a summary of what it did.
  • Fork (f): a second lane on the same challenge. Take over (t): the lane's shell is yours; exit it to hand the lane back.
  • Caps: per lane, token_cap and dollar_cap under [lanes]. An alert comes at 80%, and at 100% the lane waits for you.
  • L1: your own no-model solvers, which run before a lane's first model call. They come as a pack of engines, each with a manifest saying which challenges it fits (Solvers).
  • Light model: an optional small model for small jobs (by default, the hint judge). Off by default.
  • Lane image: the Docker image lanes run in, ctf-flightdeck-lane:1. flightdeck image build builds it once.
  • Event profile (event.toml): what an event's rules allow, and a policy for each stage: auto, confirm, manual or off.
  • Run folder: where a run's event log, transcripts and reports go (~/.local/share/ctf-flightdeck/runs/).

Models and keys

Your config names the environment variable that holds each key, never the key; flightdeck reads it from your environment, else from the keys file, ~/.config/ctf-flightdeck/keys.env, which must be readable by you only:

mkdir -p ~/.config/ctf-flightdeck && touch ~/.config/ctf-flightdeck/keys.env && chmod 600 ~/.config/ctf-flightdeck/keys.env
# then add one line per key, such as ANTHROPIC_API_KEY=... (and OPENROUTER_API_KEY=... on a line of its own)

With an Anthropic key, flightdeck init --provider anthropic writes Claude Haiku, Sonnet and Opus 5.5 with their list prices, so the dollar caps work from the start. If OPENROUTER_API_KEY is set too, it offers OpenRouter as the fallback for a lane whose calls to Anthropic keep failing. OpenRouter, OpenAI, Ollama, an MLX server or any OpenAI-compatible API work as well. For Ollama or an MLX server, init suggests a model, and for any server on your machine it lets a lane wait up to 10 minutes for a reply of up to 8192 tokens, since a local model can take minutes to answer. More on keys, and the fallback, what happens when a model declines, fast mode, time and reply limits, and prices: Model APIs.

Which models fit your machine? flightdeck models looks at it (chip, memory, NVIDIA GPUs, and the model servers running on it; it contacts nothing but 127.0.0.1) and lists, for lanes and for the light model, the models that fit and why: open-weight models on your machine first where they run well, then model APIs. flightdeck models qwen3.5-9b prints how to get one and the config lines that use it. For another machine, describe it: flightdeck models --memory 16 --apple (a 16 GB Apple Silicon Mac) or --memory 32 --gpu-memory 12 (a PC with a 12 GB NVIDIA GPU). It recommends; it never changes your config. How the models did: Models.

The light model

A few small jobs can use a small model, set in [light]. By default there is none, and flightdeck's own rules do these jobs. The first job is the hint judge: when a lane seems to ignore what its description hints at, the alert shows at once, and the light model checks the lane's steps; if it says the lane is using the technique after all, the alert comes down. [light] jobs can add three more: route (a challenge's category where the board names none, and the kind of specialist it suits), recon (a first look at the handout for the lane's opening brief) and flagcheck (a check of a flag before it goes out without you under auto submit; it can only hold a flag for you, never submit one).

Recommended: an open-weight model on your own machine, served by Ollama or an MLX server. No provider's safety classifier stands between it and security work, and it costs nothing. Measure one before you switch it on:

flightdeck eval-local --engine openai --base-url http://127.0.0.1:11434/v1 --model <model>   # scores it beside the rules, job by job
flightdeck init --light ollama --light-model <model>   # a new config; for yours, edit [light] (`flightdeck models ID` prints the lines)

init --light ollama (or mlx) writes engine = "openai" with that server's address: both serve the OpenAI-compatible API. A Claude model or a Strands Decider server can be the light model too, and one job can have an engine of its own; flightdeck config --example shows every setting. eval-local says first how many calls it will make to a paid API.

The light model never holds anything up. When it refuses, fails, times out or answers outside the options, the rules' answer stands, and the run says so once. A refused request is never sent on to another model or provider: you see the refusal and decide. Which models to try, and how each did at each job: Models.

The console

The console raises an alert when a lane spends big on a low-value challenge, ignores what the description hints at, heads the wrong way on web, loops or stalls. Lanes that need you sort first, and the line under the list says why and numbers the answers: one key answers.

A wave of 43 challenges: 16 lanes run and 33 wait in the queue. The selected lane ignores the description's hint of slow-scan TV, and the line under the list offers 1 to redirect it to the hinted technique and 2 to send a hint

An alert with its quick answers, from flightdeck mock (invented challenges).

Enter opens a lane full screen: its transcript, the files it changed with diffs, and a chat box (plain text is a message to the lane; /redirect, /approve, /diff and the rest are commands; esc goes back).

One lane full screen: its commands and their output, a needs-you box with two numbered answers, the files it changed and the diff of one of them, and the chat box

A lane full screen, from flightdeck mock (invented challenges).

t takes over a lane's shell (its container in Docker): exit it to hand the lane back, and the lane hears what you changed. The shell starts clean: it reads no startup file, and with --host its HOME is a new folder only you can read, outside the workspace, so nothing the lane wrote runs before you type. e escalates a lane to the next model in your ladder with a summary of what it did, and f forks it.

When a model API failure would hit every lane (a refused key, an unknown model, no credits), the queue is held and the header says why. Once you have fixed it, /unhold starts the queued lanes (a key or model id changed in your config needs a new run).

q asks first while lanes are open, and a run cannot be resumed.

The fleet's keys act on the selected lane: p pause, h hint, r redirect, f fork, k kill, e escalate, t take over, a approve, d decline, 1-9/0 quick answers, c claim (team), / commands, s sort, ? help (every key and command), q quit; Enter opens the lane full screen. The whole design is in the console spec.

Play a board

flightdeck play ~/ctf/some-board --max-lanes 4

A board is a folder of challenge folders, each with its handout files and a challenge.json like this one from the practice set:

{"name": "Crab Walk", "category": "crypto", "points": 50, "solves": 312,
 "description": "…", "files": ["postcard.txt"], "id": "crab-walk"}

The whole format, with answers files and live instances, is in Boards.

Lanes start on the lowest-point challenges first (most solves first among equals); the rest queue. Every lane is a model conversation, capped per lane by [lanes] token_cap and dollar_cap (400,000 tokens and $2 by default; an alert at 80%, your approval at 100%).

A flag a lane finds waits for you: a or 1 submits it, d or 0 declines. On a folder board flightdeck checks a flag against the board's answers.sha256.json when it has one. Without one it cannot check: submit the flag on the platform yourself, then press a if it was accepted or d if not. With --event, a sends it to CTFd (when the event's submit stage is manual or off, you submit it and answer a or d).

Under auto submit (submit = "auto", or play --submit auto) a flag the model submits goes at once, unless it is written in the challenge's own description or handout files (often a decoy): that one still waits for you. A flag found wrong is never asked about again.

Some platforms limit the tries at a challenge's flag (CTFd's "max attempts"). Every flag for such a challenge waits for your approval, under auto submit too, and the approval says how many tries are left. To let auto submit spend those tries without you, the last one included, set submit_limited = "auto" under [lanes]; a wrong flag can then use up the tries for your whole team. flightdeck says so when a run starts.

Every run writes a run folder with an append-only events.jsonl and each lane's transcript; a board with answers (like the practice set) ends with a scorecard. If flightdeck itself is killed (kill -9, a power loss), what its lanes started can keep running: the next play or practice removes it and says what it removed, flightdeck doctor lists it and flightdeck doctor --clean removes it.

Your solvers first (L1)

Point flightdeck at a folder of your no-model solvers and each of flightdeck's own lanes runs the ones that fit its challenge before its first model call, so a solve can cost no tokens at all.

flightdeck l1 import ~/ctf/solvers        # manifests for a folder of plain scripts (the scripts are never changed)
flightdeck l1 list ~/ctf/solvers          # every engine in the pack, with its routes
flightdeck l1 route ~/ctf/solvers ~/ctf/some-board/crab-walk   # which engines a challenge reaches, and why (or why not)
flightdeck l1 run ~/ctf/solvers ~/ctf/some-board/crab-walk     # run them now: on this machine, as you, with no container
flightdeck play ~/ctf/some-board --pack ~/ctf/solvers          # or set [l1] pack in your config

l1 import takes a .py file with an if __name__ == "__main__": block, or any executable script with a #! line, and routes it by its folder's name (crypto/, forensics/) and the words of its file name. To write a manifest yourself, or an engine that reports its evidence: Solvers.

A flag an engine returns as its result waits for your approval, or under auto submit goes to the platform at once; a flag that is only a match in what an engine printed (a plain script that l1 import took in, say) always waits for you. When lanes run in Docker, so do your solvers: each in a container of the lane image, your pack mounted read-only, with no network unless the live-instance policy is auto and the challenge has an instance. With --host they run on this machine, as you.

Events and teams

Write down what the event's rules allow, check it, and play by it:

flightdeck preflight --example > event.toml      # then edit it from the event's rules
flightdeck preflight event.toml                   # what flightdeck will do at each stage, and any problem
export CTFD_TOKEN=...                             # the variable event.toml names (never the token itself)
flightdeck play ~/ctf/event-board --event event.toml

flightdeck talks to CTFd. For any other platform, make a folder board (platform = "manual" in event.toml) and submit flags by hand.

With a CTFd event, flightdeck pulls the board into that folder (and, with pull = "auto", adds new waves as they appear), submits the flags you approve through CTFd and follows your team's solves. A slow CTFd never holds up the console: lanes carry on while their flags are on their way (the fleet shows sending). A challenge whose tries CTFd counts always waits for you, under auto too, and each approval says how many tries are left. flightdeck ctfd pull URL FOLDER pulls a CTFd board without playing it; it exits with status 1 when some challenges could not be pulled.

Each stage (pull, L1, agents, submit, live instance) has a policy in the event profile: auto, confirm (you say yes first; for agents and L1, starting play is that yes), manual or off, never looser than the rules. With agents manual or off, play does not start. Under confirm for live instances, a lane asks before it may reach its challenge's instance and has no network until you allow it. The profile, key by key: Boards.

Team mode shares claims, live-box holds and solves through a folder your teammates sync (a network drive, Syncthing): flightdeck team init DIR once, then play --team-dir DIR. Your lanes never work a challenge a teammate solved. --handle NAME sets your name in the team folder (by default, your login name), and flightdeck team status DIR shows what the folder holds and which files flightdeck ignores there.

Coding-agent lanes

--agent claude (or codex) runs lanes as that coding-agent CLI, on any board or event, behind the same controls. Each uses its own models ([agents] in your config: claude defaults to sonnet, then opus; codex needs a ladder) and its own credential, never your [api] key.

  • claude takes ANTHROPIC_API_KEY (the Anthropic API, billed per token) or CLAUDE_CODE_OAUTH_TOKEN (your Claude subscription; claude setup-token makes one).
  • codex takes CODEX_API_KEY or, on the host only, a saved codex login.

Put the credential in your keys file or your environment; --agent-auth picks one when both are set. In Docker the lane image needs the CLI, and the image flightdeck image build makes has neither: build an image FROM ctf-flightdeck-lane:1 that installs it and set [lanes] image to it, or play with --host. flightdeck doctor --agent claude checks the CLI, its credential and the lane image.

A coding-agent lane is always on Docker's bridge network, for its CLI's API, so an event whose instance policy is not auto refuses agent lanes. They do not run your L1 pack. A CLI says what a turn cost only when the turn ends, so its lane's cost ends in … until then; codex reports no cost at all, so give its models a [prices."<model>"] table for their lanes to show dollars.

After a run

flightdeck report RUN_DIR      # where lanes stalled, which interventions helped, cost per solve
flightdeck writeups RUN_DIR    # a writeup draft per solved challenge (--redact hides the flags)
flightdeck score RUN_DIR       # the run scored against the board's answers
flightdeck gaps RUN_DIR        # the challenges your L1 solvers did not solve, and why
flightdeck build gap CHALLENGE_DIR --pack ~/ctf/solvers   # a new engine stub with a test that must pass
flightdeck build check ~/ctf/solvers                       # run the pack's tests: which engines pass

When a run ends, play prints its run folder with the report, writeups and gaps commands for it (and score, when the board has answers), ready to paste. writeups --polish MODEL has MODEL tidy the prose through the API in your config: it spends tokens, and never sees the run's flags, commands or outputs.

Transcripts, the run log, reports and writeup drafts replace the value of anything shaped like a credential with [redacted], with or without --redact: an upper-case NAME=value naming a key, token, secret, password, cookie or auth; Authorization, Proxy-Authorization and Cookie headers; well-known key prefixes (the full rule is in the architecture). Anything else stays, lower-case names included (a password is everyday CTF content), so read a draft before you share it.

Configuration and files

flightdeck init writes ~/.config/ctf-flightdeck/config.toml (or the file $FLIGHTDECK_CONFIG names). flightdeck config checks it, and flightdeck config --example prints every key with its default. Keys come from your environment, else from ~/.config/ctf-flightdeck/keys.env (or the file $FLIGHTDECK_KEYS names). Each run writes a folder under ~/.local/share/ctf-flightdeck/runs/ ([run] dir, or --run-dir). flightdeck keeps notes of its own in ~/.local/state/ctf-flightdeck/ (or under $XDG_STATE_HOME). l1 import writes manifests into FOLDER/.flightdeck/generated/.

To remove flightdeck: pipx uninstall ctf-flightdeck (or uv tool uninstall ctf-flightdeck), docker image rm ctf-flightdeck-lane:1, and delete those folders.

Optional extras

  • ctf-flightdeck[build]: pytest, for flightdeck build check.
  • ctf-flightdeck[cactus]: Cactus Needle, a small on-device model that can be the light model (engine = "cactus"). flightdeck's own measurement found it unfit for the light jobs (Models), so measure it with flightdeck eval-local --engine cactus before you use it. Its telemetry is turned off, and nothing uses it unless you ask.

Docs

Using flightdeck: Model APIs · Models · Boards · Solvers · Practice set · Screenshots · Changelog · Security

How it is built: Vision · Architecture · Console spec · Decisions · Roadmap · Contributing

License

MIT. See LICENSE.

Metadata

Release files for ctf-flightdeck 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ctf-flightdeck 0.2.0
File Size Uploaded Provenance Actions
ctf_flightdeck-0.2.0.tar.gz 735.1 kB With provenance Details for ctf_flightdeck-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ctf-flightdeck 0.2.0
File Interpreter ABI Platform Actions
ctf_flightdeck-0.2.0-py3-none-any.whl Python 3 none any Details for ctf_flightdeck-0.2.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / ctf_flightdeck-0.2.0.tar.gz

Download URL ctf_flightdeck-0.2.0.tar.gz
Size 735.1 kB
Tags Source
SHA-256 checksum
How to use checksums
39c0c463e7e710ffa9a71cdf22eabce92c4506c74bf3780d8ec3f4dff60c5f05
BLAKE2b-256 checksum
How to use checksums
254e4f67ebdea7aab29dd0de22b81640ba42d0f2d912daed63b1ef5d0dcf7325
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Release files / ctf_flightdeck-0.2.0-py3-none-any.whl

Download URL ctf_flightdeck-0.2.0-py3-none-any.whl
Size 787.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7fab09481a9b8571c71872f71b428de6197510b875c237e1a5108d9dbc54df1a
BLAKE2b-256 checksum
How to use checksums
af3be6ff4db2f163674a613c49fec7a9d3b8c3db98d6706dacb4050ed344fe3b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

Security for ctf-flightdeck 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ctf_flightdeck-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 12, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page