ARGUS Guide — how it works & API setup

How it works

Three jobs. Same order every time.

1

Pick a place and collect

One region, one question. Reports land on the map.

2

Decide what to trust

Every item gets a trust grade. Keep what holds; leave the rest out of the brief.

3

Write a short brief with sources

Export on your machine. Confidence follows the evidence.

Install (local)

Clone & install

git clone https://github.com/Shama-Research-llc/argus.git
cd argus
npm install
cp .env.example .env.local

Optional vault — only if you will save API keys in Settings → Integrations:

# Generate once, paste into .env.local, then restart
python3 -c "import os,base64; print('base64:'+base64.b64encode(os.urandom(32)).decode())"

Put the result in VAULT_MASTER_KEY=.

Start
```
npm run dev
```
Open http://localhost:3000. Create a project, collect events, write a brief.

Project wizard — pick a region and question — Example: scope one region and one question in the project wizard.

What works with no keys

Map — MapLibre + OpenStreetMap (no Mapbox signup).
Trust grades & risk — NATO-style scoring, country risk, anomalies, patterns.
Briefs — rules / offline brief when AI keys are missing.
Some free feeds — e.g. ReliefWeb-style crisis data and anonymous OpenSky (tighter limits).

Recommended first upgrades

Serper Best first

Google-quality web hits for aimed / niche collects (campus, ward, local beats). Without it, web search returns far fewer events.

Brave Search

Complement or alternative to Serper. Fine alone; both is better.

Anthropic or OpenAI

Only if you want AI-drafted canvas / project briefs. Rules briefs still work without them.

Map APIs

Optional. Skip all of these and the free basemap still loads.

Env / Settings name	What it does	Where to get it
`NEXT_PUBLIC_MAPBOX_TOKEN`	Richer basemap + 3D terrain. Can also paste in Settings (mirrored for the browser map).	account.mapbox.com
`GOOGLE_MAPS_KEY`	Place context / geocode enrichment on event detail (server).	Google Cloud Console
`NEXT_PUBLIC_GOOGLE_MAPS_KEY`	Same Maps key when the browser Maps JS library needs a public key.	Same project as above

Watch floor map — Watch floor — works on free OSM; Mapbox only upgrades the look.

AI APIs (optional)

Not required. Without these, ARGUS still grades evidence and produces rules-based briefs.

Env / Settings name	What it does	Where to get it
`ANTHROPIC_API_KEY`	Preferred for AI briefs, ACH assists, enrich / verify helpers.	console.anthropic.com
`OPENAI_API_KEY`	Fallback AI + embeddings for semantic ranking.	platform.openai.com

Analyst canvas and ACH — Canvas / ACH — AI can draft; scores and structure still come from ARGUS rules.

Search & news APIs

Recommended for rich event collect. Put keys in .env.local (restart) or Settings → Integrations (needs vault).

Env / Settings name	What it does	Where to get it
`SERPER_API_KEY`	Google results for aimed collect. Expired keys fail silently with almost zero web hits — rotate if collect looks empty.	serper.dev
`BRAVE_API_KEY`	Web search alternative / complement.	api.search.brave.com
`NEWSAPI_KEY`	Headlines connector.	newsapi.org
`GUARDIAN_API_KEY`	Guardian articles connector.	open-platform.theguardian.com
`FIRECRAWL_API_KEY`	Full article text when adding / scraping sources.	firecrawl.dev
`SEMANTIC_SCHOLAR_API_KEY`	Higher rate limits for paper search (OpenAlex works as fallback without a key).	semanticscholar.org

Layers and sources panel — Layers & sources — turn connectors on after keys are set.

Event feed with trust grades after a successful collect.

Conflict & crisis data

Optional structured feeds for political-risk / conflict missions.

Env / Settings name	What it does	Where to get it
`ACLED_EMAIL` + `ACLED_PASSWORD`	myACLED OAuth login (email + password, not a legacy API key). Conflict event data.	acleddata.com
`NASA_FIRMS_KEY`	Wildfire / thermal hotspot map layer.	firms.modaps.eosdis.nasa.gov

Live tracking

Optional vessels and aviation. OpenSky works anonymously with tighter rate limits.

Env / Settings name	What it does	Where to get it
`AISSTREAM_API_KEY`	Live ship positions (AIS).	aisstream.io
`OPENSKY_USERNAME` + `OPENSKY_PASSWORD`	Authenticated ADS-B aircraft positions (higher limits than anonymous).	opensky-network.org

Vault & local access

Env name	What it does	Notes
`VAULT_MASTER_KEY`	Encrypts API keys stored via Settings → Integrations.	Must live in `.env.local` (restart). Saving only in the UI is not enough for first boot.
`ARGUS_PASSWORD`	Locks the instance behind a login screen.	Leave blank for open local access.
`ARGUS_SESSION_SECRET`	Signs cookies when password protection is on.	`openssl rand -hex 32`
`ARGUS_DEV_OPEN`	Dev-only: skip password gate while testing UI.	`true` / `false` — restart after change.

Cloud / Supabase (hosted only)

Not needed for a normal local GitHub install. Use when you host ARGUS for accounts and sync across devices.

Env name	What it does	Where to get it
`NEXT_PUBLIC_SUPABASE_URL`	Supabase project URL.	supabase.com — apply `supabase/schema.sql` + migrations.
`NEXT_PUBLIC_SUPABASE_ANON_KEY`	Public anon key (protect with RLS).	Same Supabase project
`NEXT_PUBLIC_MODE`	`local` (default) or `cloud`.	Hybrid: stay `local` but set Supabase keys for optional backup.
`NEXT_PUBLIC_APP_URL`	Canonical app URL for auth callbacks / share links.	e.g. `http://localhost:3000` or your deploy URL

Where to set keys in the app

First run — skippable setup modal lists recommended keys (nothing required).
Settings → Integrations — full catalog (same list as this page). Needs VAULT_MASTER_KEY.
.env.local — preferred for server keys (Serper, AI, ACLED). Restart the dev server after edits.

Journal

Keep notes and evidence tied to the project — supports the brief later.

Briefs & history

Export intelligence briefs; revisit prior drafts from Brief history.

Export

Markdown brief, printable report, or full backup — stays on your machine.

Research journal — save only what matters.

Brief history panel — Brief history — prior drafts with sources.

Export panel — Export — brief or full backup, local only.

FAQ

Do I need Mapbox?: No. Free OSM via MapLibre is the default.
Do I need AI?: No. Rules-based briefs and scoring work without Anthropic or OpenAI.
Collect returns almost nothing: Add or rotate SERPER_API_KEY (and optionally Brave). Prefer .env.local over a stale vault key. Restart after changing env.
Brief says “rules-based” not AI: That is expected without AI keys — still a usable brief with sources.
Never commit secrets: .env.local and .vault.enc.json are gitignored. Only commit .env.example with empty placeholders.

How ARGUS works — and how to set it up.