FlaminIA

FlaminIA is a local AI workspace for routing requests across multiple LLM providers from a browser dashboard. It runs as a Node.js CLI/server, keeps user configuration on the local machine, and helps choose the best available model for each task based on cost, latency, health, provider availability, and task type.

The package is designed for local-first use: no Electron runtime, no required native dependencies, no Python sidecar, and no bundled large ML models.

Features

• Local server and dashboard on http://localhost:20128.
• Provider router with model scoring, fallback, circuit-breaker health, and mode packs such as cheap, fast, and quality.
• Support for configured HTTP providers such as Groq, OpenRouter, OpenAI/Codex, Anthropic, Gemini-compatible providers, and custom OpenAI-compatible APIs.
• Project and chat organization with local history persistence.
• Artifact preview for generated files such as DOCX documents.
• Privacy gate with a pure-JS fallback scanner and optional local model installation.
• Local encrypted storage for provider API keys.

Install

npm install -g flaminia

Start the local server:

flaminia

or explicitly:

flaminia serve

Then open:

http://localhost:20128

Quick Start

1. Open the dashboard.
2. Go to Providers.
3. Add the API keys for the providers you want to use.
4. Use Router for quick chats, project chats, file/document generation, and provider-aware routing.
5. Use projects when you want FlaminIA to remember local context, instructions, and related chat history.

Provider Keys

Provider keys are stored by the local server in the user's FlaminIA data directory, ~/.flaminia by default.

Keys are encrypted at rest in provider-secrets.json. FlaminIA generates a per-installation passphrase and stores it locally with restricted file permissions where supported. This protects against accidental exposure of copied configuration files; it does not protect against an attacker with active access to the user's operating-system account.

Do not commit local runtime data or env files. This repository ignores .flaminia/, .env, and .env.* for that reason.

If you override FLAMINIA_HOME to point inside a project folder, keep that folder out of git.

Local Data

By default, FlaminIA stores local runtime data in:

~/.flaminia

This includes:

• provider configuration;
• encrypted provider keys;
• chat history;
• projects;
• project instructions and local context metadata;
• generated artifacts.

Each user has their own local data. Projects and chats are not part of the git repository unless you intentionally place FLAMINIA_HOME inside a tracked folder, which is not recommended.

Privacy Model

The npm package does not bundle large ML models and does not download them by default during install.

To install the optional local privacy model:

flaminia models install privacy-it

Until a model is installed, the privacy gate runs in explicit fallback mode with a small pure-JS scanner and visible warnings.

CLI

flaminia serve [--port 20128]
flaminia models install privacy-it
flaminia init-vault [path]

For local development from this repository:

npm install
npm start

Development

Build all workspaces:

npm run build

Run checks:

npm run check

Run the core server tests:

npm test -w @flaminia/core-server

Create a local npm package for installation testing:

npm pack
npm install -g ./flaminia-*.tgz
flaminia

Publishing Notes

Before publishing a release:

1. Run npm install.
2. Run npm run build.
3. Run npm pack.
4. Install the generated tarball globally with npm install -g ./flaminia-*.tgz.
5. Start flaminia and verify the dashboard responds on localhost:20128.

Do not publish local runtime data, vaults, API keys, generated artifacts, or downloaded model files.

The final npm publish command should be executed manually by the release owner after choosing the correct version and npm tag.

Repository

Source repository (name not yet confirmed as renamed on the git host — kept pointing at the existing olimpia repository path until that is verified):

https://technogit.it/technocenter1/olimpia

License

MIT. See LICENSE.

Third-party notices are listed in THIRD_PARTY_NOTICES.md.