azimut 0.2.8

The OSINT workspace that runs on your machine.

Install & run

pipx install azimut   # isolated app install; plain `pip install azimut` also works
azimut                # starts on http://127.0.0.1:8477 and opens a browser tab

No Python? Every release attaches a self-contained binary for Windows, macOS (Apple Silicon) and Linux on the Releases page — download, run, and it opens in your browser.

Your cases and settings live under ~/Azimut, outside the app: upgrading or removing Azimut leaves them alone. Install in detail covers the binaries' first-run warnings, building from source and the development loop.

What Azimut is

A local OSINT workspace for reviewing media, building geolocation proofs and keeping case notes together. It is built for open-source investigators, journalists and researchers. Each case is a plain folder that can be reopened, archived or shared.

The name is the French word for azimuth, the compass bearing you sight along to fix a point on the map.

Under the hood: reusable proof and thread templates, per-case SQLite with a bounded catalog, a durable one-worker thumbnail queue, the map-capture browser extension, and cross-platform binaries with a bundled ffmpeg.

Every tool works one-shot (a scratch session, no setup) or inside a case, a plain directory holding the whole investigation.

New in v0.2.8

Entities, graph and timeline:

• Read the whole case as a table, with one filter bar whose values and counts all come from the case, and file a person, an account or a statement by hand.
• Draw the same question in the Graph: lenses, clustered nodes, verbs on the edges, sources folded onto the edge they stand for, and an undo for the drawing that never writes to the case.
• Put dated statements and media on a Timeline, in coloured tracks, on any zone's clock, with daylight under the ruler at a saved place.
• Create and edit dates on the axis itself, and measure two entries without pretending a coarse date is an exact one.
• Hand one period from Timeline to Board, Graph and a session-only map layer. Fact time never mixes with the date something was filed.
• Keep statement confidence and source reliability apart, with support and contradiction stated as their own links.
• Date a statement through a guided editor for a year, a day, a bounded range or a zoned time range, with the raw syntax still accepted.
• Existing cases upgrade to SQLite schema 17 when they open, and bundles exported by v0.2.7 still import.

Cases on disk

Inside a case, Azimut owns only the azimut/ directory. README.txt explains the boundary; anything else at the case root is yours and travels with the case bundle.

The workspace root stays equally readable: permanent case folders sit directly under ~/Azimut. Azimut keeps scratch sessions, bundles, settings, runtime tools and tile caches under the hidden ~/Azimut/.azimut/ directory. Settings → Storage moves the workspace anywhere you like, including an external drive, or adopts one you moved yourself. The old copy is kept until you delete it.

The Case Doctor checks case integrity, including the derived Timeline index. It only changes a case after you choose a repair, and states what a database rebuild cannot recover before it starts.

Install in detail

Azimut runs in a normal browser tab (Firefox/Chrome); there is no separate window. Closing the terminal it prints its URL into stops the app.

Update with pipx upgrade azimut, remove with pipx uninstall azimut. Your cases and settings live under ~/Azimut; upgrades and uninstalling the app do not remove them. Delete ~/Azimut manually if you also want to remove the data.

Ready-to-run binary (no Python)

Each release attaches a self-contained binary per OS. Download it from the Releases page and run it; it opens Azimut in your browser.

First run, the binaries are unsigned, so the OS warns before letting them open:

• macOS: right-click the file → Open → Open (Gatekeeper only offers "Open" from the context menu for unidentified developers), or run xattr -d com.apple.quarantine ./azimut-macos-* once.
• Windows: SmartScreen shows "Windows protected your PC"; click More info → Run anyway.
• Linux: mark it executable with chmod +x azimut-linux-x86_64.

Azimut checks for a newer release on startup by default and links the download. Settings can disable that check, and Settings → System → Check for updates runs it manually. Replace the old binary with the new one. To uninstall, delete the binary. Either way ~/Azimut stays put, so cases open unchanged.

The downloadable binaries bundle a static ffmpeg (and ffprobe), so video thumbnails, frame scans, video enhancement, and downloads that merge separate audio+video streams work out of the box. If you pip install azimut instead, put ffmpeg on your PATH for those features. Everything else works without it. The bundled ffmpeg is redistributed under its own license; see ffmpeg.org/legal.html.

From source

Requires Python 3.11+ and Node.js 20+ for the frontend build.

macOS and Linux:

git clone https://github.com/OsintMeThat/azimut && cd azimut
python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"
cd frontend && npm ci && npm run build && cd ..
.venv/bin/azimut

Windows PowerShell:

git clone https://github.com/OsintMeThat/azimut
Set-Location azimut
py -3.11 -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
Set-Location frontend
npm ci
npm run build
Set-Location ..
.venv\Scripts\azimut.exe

Rebuild and relaunch the local app with the cross-platform helper:

python3 scripts/relaunch.py       # macOS / Linux
py scripts\relaunch.py            # Windows

The tool rebuilds the frontend, stops the previous Azimut instance started through the same tool, and launches the fresh build. It never kills unrelated processes by name. Use --no-browser to keep it from opening a new tab.

Frontend development (hot reload, proxied API):

.venv/bin/azimut --no-browser &     # backend on :8477
cd frontend && npm run dev          # UI on :5173

Checks (CI runs these on every push):

uv run ruff check src tests   # lint
uv run mypy                    # type-check the backend
cd frontend && npm run check   # svelte-check (blocks on errors)

Capture extension (optional)

A browser extension (Chrome/Edge and Firefox) captures external map sites straight into a case: Google Maps & Earth, Bing, Yandex, OSM, Apple Maps, Zoom Earth, Copernicus Browser and Satellites.pro, one screenshot per click with coordinates parsed from the URL. It also powers the Capture button on the Google (Maps JS) basemap. Install it from Settings → Capture extension (download the zip, load unpacked, pair with the token shown there); full instructions in extension/README.md.

Building & releasing

The Svelte frontend builds into src/azimut/static/ (git-ignored) and is bundled into the Python wheel via hatchling artifacts. So npm run build must run before building the package, or the shipped UI is stale.

cd frontend && npm run build && cd ..    # refresh the bundled UI
uv sync --frozen --no-dev --group release --no-install-project
uv sync --frozen --no-dev --group release --no-build-isolation --no-editable
uv run --no-sync python -m build --no-isolation
uv run --no-sync pyinstaller packaging/azimut.spec

Versions

The app version lives in src/azimut/__init__.py alone; pyproject.toml reads it back, and the release tag must match it.

The capture extension keeps its own version: the app release that last changed a shipped file, so it lags whenever the extension is left alone. Settings reads "bundled newer than installed" as "go reinstall the unpacked folder", which is worth saying once and never for a zip that hasn't moved. tests/test_updates.py digests what extension.zip carries and fails either way — a change without a bump, or a bump without a change. When you do change the extension, set extension/manifest.json to the current app version and record the digest the failing test prints.

Dependencies

pyproject.toml declares ranges (the contract for pip install azimut users); uv.lock pins the exact set, and is what CI and the release builds install. The wheel only declares its dependencies, but the binary contains them, so building it outside the lock ships whatever the resolver happened to pick that day.

uv lock --check                  # CI does this: is the lock in sync with pyproject?
uv lock --upgrade                # refresh everything, then run the suite
uv lock --upgrade-package yt-dlp # refresh one

Raising an upper bound is a deliberate act: bump it in pyproject.toml, run uv lock, and make sure the suite passes before it lands. The weekly "latest deps" CI job re-resolves past the lock, so upstream breakage shows up as a red run of ours rather than a broken install for someone else.

yt-dlp and gallery-dl are deliberately unbounded: they track sites that change, so pinning them just schedules a breakage. They can also be updated from inside the app (Settings → System → Downloaders), which is what keeps a months-old binary working.

Releases are automated: push a semver tag and GitHub Actions (.github/workflows/release.yml) builds the wheel + Windows/Linux/macOS binaries, attaches them to a GitHub release, and publishes to PyPI. Don't publish by hand.

git tag v0.2.8 && git push origin v0.2.8

One-time setup: register the repo as a PyPI Trusted Publisher for the azimut project (no API token to store).

Principles

1. No account, telemetry or automatic upload. The server binds to 127.0.0.1, and Azimut never posts on your behalf.
2. A case contains the investigation's files and SQLite graph. A closed case folder is complete and portable; bundle export carries both Azimut's files and anything kept beside them.
3. One tab = one tool, useful in 30 seconds.
4. Azimut integrates specialized services instead of recreating them.
5. The analyst decides; tools do not produce automated verdicts.
6. Every artifact records how it was produced.
7. Free and open source. No paid key is ever required; bring your own for more basemaps.

Full spec: docs/SPEC.md.

License

AGPL-3.0-only: free and open source; hosted or modified versions must share their source.