Nebula 3: an AI pentesting workbench where the operator keeps authority

The engagement sprawl Nebula 3 is built to collapse

A penetration test generates a mess long before it generates a report. Terminal scrollback, a notes file, a folder of screenshots, a findings spreadsheet and a half-written document all describe the same engagement, and none of them know about the others. Nebula's pitch is that these are one surface: the README lists terminal, code, browser, assistant, files, notes, missions, findings and reports as parts of a single desktop application.

The intended user is a working operator, not a hobbyist running a scanner once. The README is explicit that the human defines scope, grants authority and decides what runs, and that a model provider is optional: the human terminal, evidence workflow, notes, findings and reports stay available without one. That optionality is the interesting design claim. It means Nebula is positioned as an engagement workbench first and an AI tool second, and you can evaluate the workbench on its own terms.

Intent, assistance, approval, execution, evidence

The README reduces the control flow to a single line: intent to assistance to approval to execution to evidence. Read against the rest of the repository, that pipeline is the architecture, not a slogan.

Nebula Core is a Python service. The pyproject file declares nebula-core and nebula-browserd as console scripts, and the Dockerfile shows Core running as an unprivileged user (uid 10001) behind uvicorn on port 8000, with the data directory at /data and a health endpoint at /api/v1/health. The UI is a Tauri desktop shell built from the ui directory, which is why the source instructions require Node.js and the Rust toolchain alongside Python. Model orchestration uses langgraph with a SQLite checkpointer, and the dependency list includes chromadb, so retrieval over your own notes and artifacts is part of the design rather than an add-on.

The guarantees the README advertises sit between assistance and execution: scope enforcement, approval pauses, hard budgets and isolated OCI execution. That last one is why Docker or Podman is a hard requirement for terminal and automation features. On first launch the application may download, prepare and verify an official Kali image, which the README warns can take several minutes. The durable trail is the other half: content-addressed artifacts, append-only events, execution provenance and integrity-manifested exports. The claim is that you can reconstruct how a conclusion was reached, not just what it was.

Installing Nebula on Debian, Ubuntu or Kali

The current release candidate is Nebula 3.0.0-alpha.5 for Linux x86_64, distributed through a signed APT repository. The README gives an archive-key fingerprint, and verifying it before adding the repository is the step worth not skipping. The commands below import the key, add the prerelease channel and install the package.

curl -fsSL https://berylliumsec.github.io/nebula-apt/nebula-archive-keyring.asc |
  gpg --show-keys --fingerprint
curl -fsSL https://berylliumsec.github.io/nebula-apt/nebula-archive-keyring.asc |
  sudo gpg --dearmor --batch --yes -o /usr/share/keyrings/nebula-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/nebula-archive-keyring.gpg] https://berylliumsec.github.io/nebula-apt prerelease main" |
  sudo tee /etc/apt/sources.list.d/nebula.list >/dev/null
sudo apt update
sudo apt install nebula

The gpg output should print the fingerprint 1D90 1EB3 4C8C 1065 F118 680D 1C5C 924C B4B5 823D. If it does not, stop. The README also documents a manual DEB path and a portable AppImage, both verified against a SHA256SUMS-linux-x64.txt file from GitHub Releases.

Once installed, launch the application and inspect the runtime boundary before doing anything else:

nebula
nebula-core doctor --json

The doctor command reports on the bundled Core and the local runtime boundary. Treat a failure there as blocking, since the contained terminal and automation features depend on a working container runtime. The README states plainly that you should not use pip install nebula-ai to install Nebula 3, even though the package name in pyproject.toml is nebula-ai; that is a real trap for anyone who assumes PyPI is the distribution channel.

Running from source, and migrating a Nebula 2 engagement

Source checkouts are supported and are the only way to work on the UI. The README requires Python 3.11 to 3.13, Poetry 2.1.3, Node.js 20 with npm, the stable Rust toolchain and the Tauri prerequisites for your operating system.

git clone https://github.com/BerylliumSec/nebula.git
cd nebula
poetry install --with dev
poetry run playwright install chromium
npm --prefix ui ci
npm --prefix ui run dev:desktop

The Playwright step matters because the browser component renders JavaScript-driven URL knowledge sources; signed Linux installers bundle a locked Chromium headless runtime, but a source checkout does not, and Nebula can also use an existing system Chrome or Chromium. The final command builds the Core sidecar and opens the native desktop from the checkout. For browser-only development, the README offers npm --prefix ui run build followed by poetry run nebula-core ui, which lets Core pick an available loopback port.

If you already have Nebula 2 data, the migration path is a single command against a copy:

nebula-core import-2x "/path/to/nebula-2-engagement"

The README says to quit Nebula 2, keep a backup, and import without modifying the source, then verify the imported project and its evidence before deleting the original. The full integrity and recovery procedure lives in docs/MIGRATING-2-TO-3.md. I would read that document before running the command rather than after, because the README does not describe what a partially failed import leaves behind.

Where Nebula 3 is the wrong tool

The release matrix is the first hard boundary. macOS, Windows and Linux arm64 installers are not part of the current release matrix, so an operator on a MacBook or an arm64 workstation is out of scope today. That is a large fraction of the people who might want this.

The second boundary is maturity. The current line is 3.0.0-alpha.5, the APT channel is named prerelease on purpose, and the README's own preview note says a build exists only when a nebula-v3.* entry and its native artifacts appear on GitHub Releases, and that you should back up engagement data and review release notes and checksums before use. An alpha with an explicit backup warning is not what you put in front of a client engagement you cannot afford to repeat.

The third boundary is architectural. Nebula inserts approval pauses and hard budgets between the model and the target. If your goal is unattended, high-volume scanning across a large scope, that gating works against you, and a conventional scanner driven by a scheduler will finish the job with less ceremony. Nebula is for deliberate work where a human is present and accountable, which is exactly what the README says it was built for. There is also a dependency cost: Docker or Podman is required, the first launch may pull a Kali image, and the source path wants Python, Poetry, Node, Rust and Playwright all present before anything runs.

Nebula 3 against a plain terminal plus an LLM chat window

The obvious alternative is the setup most testers already have: a terminal, a notes app and a browser tab open to a hosted model. That combination is more flexible than Nebula and has no install cost, and for a short engagement it is genuinely the better choice.

The difference in approach is what happens to the output. In the ad hoc setup, the model's suggestions and your command history live in different places, and the evidence for a finding is whatever you remembered to paste into the report. Nebula's answer is to make the artifact the unit: content-addressed storage, append-only events, execution provenance and integrity-manifested exports, with findings and reports drawing from the same store. The model is a participant in that pipeline rather than a separate chat window, and it can be removed without breaking the pipeline.

That is a real architectural difference, and it is also the reason Nebula is heavier. You are trading the freedom to assemble your own tools for a system that records how each conclusion was reached. Whether that trade is worth it depends entirely on whether you need the trail.

Licence, maintenance and upgrade cost

Nebula is BSD-2-Clause, and pyproject.toml declares the package licence as BSD. That is a permissive licence, so redistributing it or embedding it in a commercial service is broadly permitted provided the copyright notice and licence text are retained. This is a description of the licence identifier, not legal advice; if you plan to redistribute a modified build, read LICENSE.md and get your own review.

Maintenance looks current rather than dormant: the last push to the default branch was on 2026-09-09, and the recent release list shows nebula-v3.0.0-alpha.5 on 2026-07-22 alongside 2.0.1b2 and 2.0.1b1 on 2026-07-20. The version in pyproject.toml, 3.0.0-alpha.17, is ahead of the published alpha.5 artifact, which tells you the source tree moves faster than the packaged preview. On an alpha channel that cuts both ways: fixes arrive quickly, and the thing you installed is not the thing in the repository.

Upgrade cost is low if you used the APT route, since the README notes that future updates stay under administrator control through the normal APT workflow. The AppImage uses a signed direct-update channel. Source checkouts carry the full toolchain upgrade burden, and the Python constraint of 3.11 to below 3.14 is narrow enough to matter when your distribution moves ahead of it.

Editorial conclusion

Adopt Nebula 3 if you run authorized engagements on Debian, Ubuntu or Kali x86_64 and want model assistance that pauses for approval instead of executing on its own. Do not adopt it if you need macOS, Windows or arm64, or if you want the model to run unattended. Before trusting it with client data, run nebula-core doctor --json and confirm the OCI runtime is reachable, because the terminal and automation features depend on it, and read docs/MIGRATING-2-TO-3.md before pointing nebula-core import-2x at an existing Nebula 2 engagement directory.

Frequently asked questions

Official sources

1. berylliumsec/nebula on GitHub
2. License: BSD-2-Clause
3. Project website
4. README
5. Releases