Get started · Philotas

Prerequisites

Node.js 22 and npm. Docker is optional, for the Compose quickstart. Python 3.13 is optional, for the detection service.

Quickstart

git clone https://github.com/algolotl/philotas.git
cd philotas
npm install
npm run dev

Open http://localhost:8788. The map runs without a basemap key, and the app stores its data in a local file until you point it at a database.

Docker Compose

docker compose up

This starts the application, ingest and Postgres. Add the detection service with docker compose --profile detect up.

First run

Register an account on the sign-in screen. The first account you register becomes the administrator. Accounts registered after it join as operators, and an administrator can change roles and clearance levels.

Environment variables

Every core layer is keyless. Copy the values you need into .env.local.

Variable	Purpose
NEXT_PUBLIC_GOOGLE_MAPS_API_KEY	Enables the Google Maps basemap. Without it the map shows a setup card and the rest of the application still runs.
DATABASE_URL	Postgres connection string. Without it the app uses a local JSON file under `.data/`.
PHILOTAS_LLM_URL	OpenAI-compatible endpoint for the adjudicating model. Without it the ontology resolves with the deterministic fallback.
FIRMS_MAP_KEY	API key for NASA FIRMS fire hotspot data.
OPENSKY_CLIENT_ID	OpenSky OAuth2 client id. Aviation uses adsb.fi by default; OpenSky is opt-in.
OPENSKY_CLIENT_SECRET	OpenSky OAuth2 client secret, used with the client id.
DETECTION_URL	Address of the detection service. Defaults to http://127.0.0.1:8770.
AG_MODEL_DIR	Directory containing a trained AutoGluon model for the detection service.
DETECT_ENGINE	`auto` (default), `autogluon`, or `ultralytics`.
YOLO_MODEL	Path to an ultralytics model. Read only when `DETECT_ENGINE=ultralytics`.
ALLOW_INSECURE_COOKIE	Off by default. Enable only when serving over plain HTTP on a private network.
PHILOTAS_URL	Base URL of a running deployment, used by `philotas-mcp`.

Google Maps key

The map shows a setup card until you set NEXT_PUBLIC_GOOGLE_MAPS_API_KEY to a Maps JavaScript API key with your domain allowed. Restart npm run dev after setting it. The rest of the application still runs without a key.

Detection service

The detection service defaults to AutoGluon, Apache-2.0 licensed. Point AG_MODEL_DIR at a trained AutoGluon model directory. Ultralytics YOLO is an explicit opt-in: set DETECT_ENGINE=ultralytics and YOLO_MODEL to a weights path. Ultralytics is AGPL-3.0 licensed, so review its terms before enabling it, and do not commit .pt files.

MCP server

philotas-mcp exposes read-only tools against a running deployment over the Model Context Protocol. Install it with npx -y @philotas/mcp and point it at a deployment with PHILOTAS_URL.

npx -y -p @philotas/mcp philotas-mcp doctor

Against the public trial, bootstrap a read-only guest session:

PHILOTAS_URL=https://trial.philotas.com PHILOTAS_GUEST=1 npx -y -p @philotas/mcp philotas-mcp doctor

The doctor command checks that PHILOTAS_URL is set and that the deployment answers, then prints a pass or fail per check and exits 0 or 1.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "philotas": {
      "command": "npx",
      "args": ["-y", "@philotas/mcp"],
      "env": { "PHILOTAS_URL": "http://localhost:8788" }
    }
  }
}

Cursor

Add the same block to .cursor/mcp.json:

{
  "mcpServers": {
    "philotas": {
      "command": "npx",
      "args": ["-y", "@philotas/mcp"],
      "env": { "PHILOTAS_URL": "http://localhost:8788" }
    }
  }
}

philotas-mcp is read-only: it returns status, feeds, graphs, search results, alerts and detections, and it scaffolds and validates connectors. It never writes back to a deployment.

Run it on your laptop