Skip to content

Foil Quick Start

Install

Option A — DMG (recommended)

  1. Download Foil.dmg from foil.peachstudio.be
  2. Open the DMG, drag Foil to Applications
  3. Launch Foil from Applications

Option B — Homebrew

brew tap peachstudio/foil
brew install --cask foil

Requirements

  • macOS Ventura or later (Apple Silicon only)
  • Homebrew — install first if you don't have it: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    On a fresh Mac this will also install Xcode Command Line Tools (~1.5 GB) — let it finish.
  • Python 3.11+ — install via Homebrew: 
    brew install python@3.14

The setup wizard handles everything else. PDF report export (optional) needs pango and cairo — the wizard installs these automatically.

Setup (first launch)

The setup wizard runs automatically:

  1. Python check — verifies Python 3.11+ is installed
  2. System deps — installs pango + cairo via Homebrew (for PDF reports, skipped if unavailable)
  3. Environment setup — creates an isolated Python environment at ~/.foil/venv/ and installs all dependencies
  4. Model download — downloads the default LLM (securereview-7b, ~4 GB). Skip if you'll download later
  5. Ready — starts the server and installs the CLI

Your first scan

Once the server is running (green icon in the menu bar):

From the Web UI

  1. Click the Foil tray icon → Open Web UI
  2. Log in with the default password: IlovePeach (you'll be asked to change it)
  3. On the dashboard, paste this path in the scan field:
~/.foil/samples/python_vuln
  1. Click Scan — Foil will analyze 3 intentionally vulnerable Python files
  2. Review findings in the Findings tab

Want the full walkthrough?

For the step-by-step UI guide — registering a project, running a deep scan (Phase 6 agentic investigation), exporting a PDF report — see UI Guide → Scan a project. Deep scans and PDF reports are only reachable from the Project detail page.

From the CLI

Open a new terminal and run:

foil scan ~/.foil/samples/python_vuln

The CLI delegates to the running server (fast — model already loaded). You'll see findings in JSON:

foil scan ~/.foil/samples/python_vuln --format text

For text output with colors.

View findings

foil findings ~/.foil/samples/python_vuln

Shows stored findings grouped by file with severity colors.

What's in the sample project?

~/.foil/samples/python_vuln/ contains 3 files with real vulnerabilities:

File Vulnerabilities
sql_injection.py SQL injection via string formatting
xss_and_cmdi.py Cross-site scripting, command injection
missing_auth.py Missing authentication on admin routes

Next steps

  • Scan your own code: foil scan /path/to/your/project
  • Deep Dive: click on any finding → Deep Dive for AI-powered analysis (Developer license). Enable Deep for a whole project from UI → Scan a project.
  • Export: findings can be exported as JSON, Markdown, or PDF (PDF from Project detail)
  • Models: download other models from the Preferences → Models tab

CLI reference

foil scan <path>              Scan file or directory
foil scan <path> --standalone Run with local LLM (no server needed)
foil cancel-scan <job_id>     Cancel a running project scan
foil scan-status              Show running scan jobs
foil findings <path>          View stored findings
foil map <path>               Code map (no LLM needed)
foil model list               List downloaded models
foil model download <repo>    Download from HuggingFace
foil status                   Server + vllm-mlx status (shortcut)
foil server status            Server + vllm-mlx status
foil server logs              View server logs
foil --version                Show version

Uninstall

Homebrew (keeps models and scan data): 

brew uninstall --cask foil

Full removal (deletes everything — models, venv, findings, logs): 

brew uninstall --cask foil
rm -rf ~/.foil

DMG install (no Homebrew): 

# Remove the app
rm -rf /Applications/Foil.app
# Remove all data (models ~4 GB, venv, findings, logs)
rm -rf ~/.foil
# Remove preferences
defaults delete be.peachstudio.foil 2>/dev/null
# Remove CLI from PATH (edit ~/.zshrc and remove the Foil line)

Troubleshooting

  • Server won't start: check logs via tray icon → Preferences → Server → Show Logs
  • Scan hangs: the first scan after launch takes longer (model warmup). Subsequent scans are fast
  • "Not authenticated" errors: the web UI at localhost:9090 skips auth when accessed locally. If accessing from another machine, log in with the default password IlovePeach
  • GPU memory: clear GPU cache via Preferences → Server → Clear GPU Cache

By Peach Studio · foil.peachstudio.be