Installation

Every install channel gives you the same secfoo command. Pick the one that fits the machine.

Which one should I use?

ChannelNeedsGood forBuilt-in api agent
pipPython 3.10+Most people, and CI✓ with secfoo[api]
npmNode.jsMachines without Python; locked-down npm mirrors—
Install scriptNothingmacOS and Linux without Python or Node—
PowerShell scriptNothingWindows without Python or Node—
DockerDockerServing the dashboard from a container—
Using an API key instead of an agent CLI? Install with pip.
Only pip install "secfoo[api]" includes the libraries the api agent needs. The npm package, install scripts, release binaries and Docker image don't, so with those you drive an installed agent CLI such as Claude Code or Codex.

pip (Python 3.10+)

pip install secfoo                 # agent CLIs only
pip install "secfoo[api]"          # plus the built-in api agent

To keep secfoo's dependencies apart from your other Python tools, install it with pipx install secfoo (or pipx install "secfoo[api]"), or inside a virtual environment.

npm

npm install -g @rakfortltd/secfoo

This installs a standalone binary, not a Python wrapper, so you don't need Python. npm downloads only the package for your platform (macOS arm64/x64, Linux x64/arm64, Windows x64), and no post-install script fetches anything from the network. That's why it works behind a locked-down corporate npm or Artifactory mirror.

Install script (macOS and Linux)

curl -fsSL https://raw.githubusercontent.com/secfoo-com/secfoo/main/install.sh | sh

The script detects your OS and CPU, downloads the matching binary from the latest GitHub release, checks it against the release's SHA256SUMS file, and installs it as secfoo:

  • into /usr/local/bin if you can write there,
  • otherwise into ~/.local/bin, with a note if that directory isn't on your PATH.

To install somewhere else, set PREFIX. This installs to $HOME/tools/bin:

curl -fsSL https://raw.githubusercontent.com/secfoo-com/secfoo/main/install.sh | PREFIX="$HOME/tools" sh

PowerShell script (Windows)

irm https://raw.githubusercontent.com/secfoo-com/secfoo/main/install.ps1 | iex

Downloads the Windows binary from the latest release, checks its SHA-256 against SHA256SUMS, and installs it under %LOCALAPPDATA%\secfoo. Open a new terminal afterwards so the updated PATH takes effect.

Standalone binaries

Every GitHub release has a self-contained binary for each platform, with Python and every dependency bundled, plus a SHA256SUMS file. To install one by hand, download the binary and SHA256SUMS into the same folder, check the binary, then put it on your PATH:

shasum -a 256 -c SHA256SUMS --ignore-missing   # macOS
sha256sum -c SHA256SUMS --ignore-missing        # Linux

chmod +x secfoo-<platform>
mv secfoo-<platform> /usr/local/bin/secfoo

Docker

docker run --rm ghcr.io/secfoo-com/secfoo --help

The image contains secfoo and git, but no agent CLI, so secfoo run won't work in it as-is. It's most useful for serving the dashboard from a store that a run on the host created. Mount the store and bind to all interfaces, since the default 127.0.0.1 isn't reachable through Docker's port mapping:

docker run --rm -p 8787:8787 -v ~/.secfoo:/root/.secfoo \
  ghcr.io/secfoo-com/secfoo serve --host 0.0.0.0 --port 8787

To run scans in a container, build your own image FROM this one and install your agent CLI into it.

Only expose the dashboard where you mean to
--host 0.0.0.0 makes the dashboard reachable from other machines that can reach the published port. It has no login. Keep the port bound to localhost (-p 127.0.0.1:8787:8787) unless you've put it behind something that controls access.

Check the install

secfoo --help      # lists the commands
secfoo agents      # lists agent adapters and which are on your PATH

"command not found" after installing

  • pip: pip put secfoo in a scripts folder that isn't on your PATH. python3 -m pip show -f secfoo shows where it went. Add that folder to PATH, or reinstall with pipx, which handles this for you.
  • Install script: it fell back to ~/.local/bin. Add export PATH="$HOME/.local/bin:$PATH" to your shell profile and open a new terminal.
  • Windows: open a new terminal so the updated PATH is loaded.

Upgrading

Installed withUpgrade with
pippip install -U secfoo (or pip install -U "secfoo[api]")
pipxpipx upgrade secfoo
npmnpm install -g @rakfortltd/secfoo@latest
Install scriptsRun the script again. It always installs the latest release.
Dockerdocker pull ghcr.io/secfoo-com/secfoo

Upgrading never touches your data. Runs, reports and settings stay in ~/.secfoo/, and the local database is migrated automatically the first time a new version opens it.

Uninstalling

Installed withRemove with
pip / pipxpip uninstall secfoo / pipx uninstall secfoo
npmnpm uninstall -g @rakfortltd/secfoo
Install scriptDelete the binary: rm "$(command -v secfoo)"
PowerShell scriptDelete the %LOCALAPPDATA%\secfoo folder.

None of these delete your data. To remove that too, delete ~/.secfoo/. See Deleting your data.

Working on secfoo itself

git clone https://github.com/secfoo-com/secfoo
cd secfoo
pip install -e ".[dev]"
← Your first scan Configuration →