Skip to main content

ctf-flightdeck

Play CTFs with a fleet of AI agents, and stay the pilot.
One terminal console: every challenge, every agent, every flag. You step in with one key.

PyPI version Python versions Tests MIT license Sponsor Pull requests welcome

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

Try it in ten seconds

uvx ctf-flightdeck mock

That opens the console on scripted data: no install, no key, no network, nothing spent. (No uvx? pipx run ctf-flightdeck mock does the same.)

What it is

flightdeck is a terminal harness for capture-the-flag events. It pulls the board, runs your own no-model solver scripts first, starts an AI agent on each challenge in parallel, and submits the flags you approve. Each agent works in its own lane, and you watch them all on one screen. When a lane loops, stalls, overspends or ignores the hint, the console tells you, and one key sends a hint, redirects it, forks it, kills it, moves it to a stronger model or hands you its shell.

  • Bring what you have. An API key (Anthropic, OpenRouter, OpenAI), a free model on your own machine (Ollama, MLX), a coding-agent CLI (Claude Code, Codex), a folder of solver scripts.
  • Built for CTFs. It knows points, solves, categories, waves of 40 challenges, teammates, live instances, flag formats and counted tries. It plays CTFd events and plain folders.
  • Plays by the event's rules. Every stage (pull, solvers, agents, submit, live instances) is auto, confirm, manual or off, checked before anything runs.
  • Safe by default. Each lane runs in its own Docker container with no network, or, when its challenge has a live instance, a network that reaches that instance and nothing else. Challenge text is treated as hostile data, never as instructions. Lanes have token and dollar caps.
  • Hands-on or hands-off. Steer every lane yourself, or engage Autopilot: it runs the event by rule while you are away, inside a budget you set, never looser than the event's rules, and hands back when something needs a human. Runs can go headless, with a status file and a webhook that pings you.
  • Learns from each run. A report of where lanes stalled and which interventions helped, writeup drafts, and the list of challenges your solvers missed.

Status: v0.4.0 (alpha). See the changelog and the roadmap.

Quickstart

Needs Python 3.12+ on macOS or Linux (Windows through WSL). Docker is recommended. Install with pipx or uv, whichever you have; the optional solver pack needs uv and git either way.

pipx install ctf-flightdeck   # or: uv tool install ctf-flightdeck   (from a clone: uv tool install .)
flightdeck init               # a few questions; writes your config and names the key it needs
flightdeck image build        # once, for Docker lanes (about 700 MB)
flightdeck pack install       # optional, needs uv: some 800 no-model solvers that run first
flightdeck doctor             # checks everything and says how to fix each problem
flightdeck practice           # 14 small practice challenges, on your model

Then just run it:

flightdeck

It opens on flightdeck's home screen: resume an event you played before, start a new one, the practice set, or a demo. Starting one is a form on that screen (the event's name, its site, your access token, its VPN file); it makes the event's folder and launches. Your first console opens on a welcome screen that says what you are looking at and the three keys you need.

The same things by name, for a script or a habit:

flightdeck start                                                    # set up an event and play it
flightdeck play ~/ctf/example-ctf                                   # an event you set up before
flightdeck play ~/ctf/example-ctf --autopilot --budget-dollars 20   # Autopilot, inside a run budget
flightdeck play ~/ctf/some-board                                    # or any folder of challenges

--autopilot needs Docker lanes and a run budget. A model on your own machine has no price, so give its budget in tokens (--budget-tokens). Autopilot loosens no rule: where event.toml says confirm, flags and live instances still wait for you (Autopilot).

Already installed? uv tool upgrade ctf-flightdeck (or pipx upgrade ctf-flightdeck) gets the newest release; flightdeck --version says which you have. Your config and keys stay as they are.

practice and play spend money on your model API unless the model runs on your machine. Each lane stops and asks you at $2 or 400,000 tokens by default. Stuck? flightdeck doctor checks your setup and says how to fix each problem.

Everything else is in the player's guide: models and keys, the console's keys, boards, your own solvers, events and teams, coding-agent lanes, Autopilot, headless runs, reports.

The console

An alert on a lane that ignores the description's hint, with numbered one-key answers under the lane list

Lanes that need you sort first, and the line under the list says why and numbers the answers. h hint, r redirect, f fork, k kill, e escalate to the next model, t take over the lane's shell, a approve a flag, Enter for one lane full screen, ? for every key. More pictures in the screenshot gallery.

Your data stays yours

flightdeck has no telemetry, no analytics, no account, no update check and no server of its own. Nothing about you or your runs is sent to this project, ever.

It talks only to what you point it at:

  • The model API in your config. A lane's challenge and its work go to the model you chose, as with any AI tool. Choose a model on your own machine (Ollama, MLX) and nothing leaves it.
  • The CTF platform in your event profile, to pull the board and submit the flags you approve.
  • A webhook of your own, only if you set one up for notifications. It gets a short message (a lane needs you, a flag was accepted) and never a flag.

Your keys stay in your environment or a file only you can read, never in the config, and logs, transcripts and reports replace anything shaped like a credential. Runs are written to a folder on your machine. Sharing a result is something you do by hand: flightdeck share prints a summary and you decide where to paste it. A coding-agent CLI you plug in (Claude Code, Codex) follows its own maker's policy. Details: Security.

Leaderboard

Events flightdeck has flown in, where the team finished, and how hands-on the players were: the leaderboard. Played an event with it? Add your flight and your GitHub name goes on the board.

Help make it better

Three ways, and the first needs no code:

  1. Play and share what you ran. This is the most useful thing you can do. After any run (the practice set counts), flightdeck share latest prints a flight card: your models, your setup, solves, time, cost and how often you stepped in, with no flags and no challenge text. Post it. Enough cards tell everyone which model is fastest, cheapest and best for which kind of challenge, on which hardware.
  2. Build. Fix a bug, add a feature, improve a doc. Good first issues are small and well described, and CONTRIBUTING.md gets you set up in five commands.
  3. Sponsor. flightdeck is free and MIT-licensed. Measuring models costs real API money, and sponsorship pays for it: sponsor on GitHub.

A star helps other players find it.

For AI agents

If you are an AI agent reading this for a user:

  • What this is: a Python CLI (flightdeck, PyPI package ctf-flightdeck) that runs AI agents on CTF challenges under a human's control.
  • Safe to run without asking: uvx ctf-flightdeck mock --screenshot DIR (headless, writes SVGs), flightdeck --help, flightdeck doctor, flightdeck config --example, flightdeck models.
  • Ask your user first: flightdeck practice and flightdeck play spend money on a model API, and play --event talks to a live CTF platform under that event's rules.
  • Machine-readable map of the docs: llms.txt.
  • Working on the code: read AGENTS.md first. It is short and its rules are strict.

Docs

Using flightdeck: Player's guide · Model APIs · Models · Boards · Solvers · Practice set · Screenshots · Leaderboard · Changelog · Security

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

License

MIT. See LICENSE.

Metadata

Release files for ctf-flightdeck 0.4.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.4.0
File Size Uploaded Provenance Actions
ctf_flightdeck-0.4.0.tar.gz 947.5 kB With provenance Details for ctf_flightdeck-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 2.0 MB

Release files / ctf_flightdeck-0.4.0.tar.gz

Download URL ctf_flightdeck-0.4.0.tar.gz
Size 947.5 kB
Tags Source
SHA-256 checksum
How to use checksums
110edd36d9eaf83ce008bd1e11e9d4d2dba61887eb1b37b4cfab673658fdd539
BLAKE2b-256 checksum
How to use checksums
f62be7422731cb8d5b4d8c625a86af65f6ee7c57c8de8c3b2eaa7b04cad445ae
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 14, 2026.

Transparency log

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

Download URL ctf_flightdeck-0.4.0-py3-none-any.whl
Size 1.0 MB
Tags Python 3
SHA-256 checksum
How to use checksums
3cc5b2a87a2d06a585ffcb18b3007b1bbac4e577f07049b94a823cf1d2880a15
BLAKE2b-256 checksum
How to use checksums
28c55819833d16eea7d43c6d40bbebbec0b69628bb29c0ee616c63603cbc2aa7
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 14, 2026.

Transparency log

Security for ctf-flightdeck 0.4.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.4.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 14, 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