Phlox
GitHub
Open source · Self-hosted · Apache 2.0

Your models.
Your AI workspace.

Chat, research documents and the web, and put an agent to work with tools you control. Organize work into private projects and turn answers into editable documents and code. Run it all with local models or your preferred cloud provider.

Get started Read the user guide
v0.3.0 Model discovery, private projects, and versioned artifacts →
Runs over
  • AWS Bedrock
  • OpenAI
  • Ollama
  • OpenRouter
  • vLLM
  • LiteLLM
  • LM Studio
localhost:5173
The Phlox chat interface with the artifact canvas open beside the conversation, live-previewing an interactive DNA-replication web app the agent just built
Local + cloudyour choice of models
Cited researchyour documents + the web
Agent toolscode, files, and MCP
File versionsedit, compare, and restore
Apache 2.0open source, self-hosted
New in v0.3.0

A workspace for work that evolves

Bring in new models, keep projects organized, explore alternate answers, and refine the files you create. Your research and agent tools stay close at hand.

Model discovery

New models, ready to choose

Pull a model in Ollama or download one in LM Studio, then refresh the searchable picker. Discover cloud catalogs too, without restarting Phlox.

Explore model discovery → Projects and context

Keep each project focused

Group conversations with shared instructions and selected documents. Inspect the context before sending and the retained context record after a response.

Explore private projects → Conversation alternatives

Explore another answer

Regenerate a reply or edit an earlier message while preserving the original path. Revisit alternatives with their citations and saved answer files.

Explore conversation alternatives → Editable artifacts

Refine the result

Edit Markdown, HTML, and code beside the chat. Request an AI revision of selected text, review the proposal, and save versions you can compare or restore.

Explore artifact editing →

Discover models from your providers

Connect AWS Bedrock or an OpenAI-compatible endpoint, including Ollama, LM Studio, and vLLM. Choose local inference and embeddings to keep those requests on your own machines. Vision, tools, and context limits depend on your chosen model.

  • Configure a provider in the admin console and choose Automatic discovery
  • Search available models in Settings, assistant setup, and provider configuration
  • Reopen the picker or use Refresh models after adding a model to your server
  • Keep curated lists when you prefer a fixed set of choices

Discovery reads the provider catalog; it does not download models or change your selected model. Bedrock catalog access requires AWS listing permissions.

Model discovery and provider setup →
Optional config.yml seed 
default_profile: local-ollama
profiles:
  local-ollama:
    type: openai
    label: "Ollama (local)"
    endpoint: http://localhost:11434/v1
    api_key: ollama       # ignored by Ollama
    model: your-installed-model
    model_discovery: automatic
    discovery_api: ollama
    supports_tools: true
Features

Chat, research, and action in one workspace

The everyday tools of an AI assistant, connected to your models and infrastructure.

Private projects

Group conversations around shared instructions and selected documents. Keep project work private, with personal memory off by default.

Inspectable context

Review instructions, model destination, history, memory, and document choices before sending. Inspect the retained context record beneath a response.

Conversation alternatives

Edit a message or regenerate an answer without losing the original. Switch between saved paths and continue from the one you choose.

Streaming chat

Image input for vision models, highlighted code, math and Mermaid diagrams, editable messages, conversation search, and Markdown export.

Tools and code execution

An agent can plan, read and write files, run Python or JavaScript, use shell tools, and delegate scoped work to sub-agents.

Approvals and checkpoints

Review sensitive tool calls before execution. Approvals recover after reload, while Git-backed workspace checkpoints let you inspect and restore files.

Artifacts and canvas

Preview HTML and Markdown beside the conversation. Edit text and code, request selected-text AI revisions, and compare, restore, or download saved versions.

Assistants and skills

Create specialized assistants with prompts and knowledge bases. Reuse Markdown workflows through slash commands or on-demand skill discovery.

Research with cited sources

Choose Research for a staged investigation of documents and the web. Follow the plan and open report citations to inspect captured passages. Chat remains the default.

Memory across conversations

Save useful facts and preferences for future chats. Review and manage retained memories in the Memory panel.

MCP and API integration

Connect external tools through MCP. Use per-user API keys for the OpenAI-compatible model gateway, with shared usage accounting.

Multi-user administration

Local accounts or Entra ID SSO, private user content, per-tool permissions, usage reporting, monthly budgets, and live admin configuration.

Private projects · Inspectable context

Give ongoing work a place of its own

Keep related conversations, instructions, and reference documents together. Start a project when you need one; everyday chat remains the default.

Shared direction across your chats

Create a private project with reusable instructions and selected documents. Start conversations inside it, move existing chats in or out, and archive finished projects. Other project conversations are not automatically added to a chat’s history.

  • Project content stays private to its owner, including from administrators
  • Personal memory is off by default in projects
  • Project conversations do not automatically save facts to global memory
Projects guide →

See the context behind an answer

Open Context in the composer to review the model destination, instructions, compatible history, memory, and document choices. Exclude context you do not want included in the next turn.

  • Review the retained context record beneath a response
  • Inspect captured source passages alongside citations
  • Keep the original transcript visible when context changes start a new history segment

Context records describe retained context and attempted model calls; they are not a complete transcript of every outbound request.

Conversation alternatives

Try another direction. Keep the original.

Regenerate a reply or edit an earlier message to create an alternative. Previous answers, citations, context records, and saved answer files remain available. Switch paths with compact controls; your choice survives a reload.

Only the selected path continues into the next chat turn or Markdown export. Switching answers does not roll back workspace files; use a checkpoint when you need to restore the workspace.

Conversation alternatives guide →
Versioned artifacts

From generated file to finished work

Edit supported text files directly in the canvas, preview HTML or Markdown, and compare saved versions. Select a passage and describe a change to request an AI revision, then review and apply or discard the proposed edit.

  1. Edit and review. Make your changes or refine selected text with AI.
  2. Save a version. Keep a durable copy to compare, download, or restore later.
  3. Use in workspace. Explicitly update the file the agent works with.

Saving a version keeps the workspace file unchanged until you choose Use in workspace. Save drafts before refreshing or closing the browser.

Artifact editing guide →
The agentic core

An agent with tools and clear controls

Each turn, the model works in a loop — calling tools, planning, and recovering — inside a per-conversation workspace you can inspect, snapshot, and roll back. Choose container or AgentCore when execution isolation is required.

01 Tool loop

Filesystem (read_file, write_file, edit_file, glob, grep), run_shell, execute_python / execute_node, and search_documents — one unified tool surface the model drives until the task is done.

02 Planning & sub-agents

update_todos keeps a visible plan; spawn_subagent inherits the parent model, settings, scope, and cancellation. Explicitly read-only children can run in a bounded pool; mutating children run sequentially within the parent turn.

03 Memory & checkpoints

save_memory persists durable facts across chats. Every workspace is a git repo that auto-snapshots after mutating tools, with one-click restore. Project chats keep global memory separate and do not automatically save to it.

04 Approvals & permissions

Every tool has an auto / ask / deny policy. The loop pauses on ask, saves the pending review, and rechecks current policy before resuming. Round limits carry across pauses. Sub-agents inherit the turn's approval state — no self-granted bypass.

05 Artifact canvas

Preview HTML and Markdown in a resizable canvas beside the chat. Edit supported text files, review selected-text AI revisions, and save immutable versions. Choose Use in workspace when a saved version should replace the agent’s file.

Reconnectable runs · optional

Keep a task running when you step away

Refresh, switch chats, or lose your connection, then return to saved progress or the completed answer. Pending approvals stay linked to the task.

  • Enable once in the configuration file and restart
  • Use the chat’s Stop button to request cancellation; closing a tab leaves execution running
  • After a server interruption, review saved results and uncertain actions before continuing

Run behavior and recovery →

config.yml · add at the top level 
runs:
  enabled: true

Off by default. Runs are independent of Agent mode. One application process per database/data directory; no automatic replay of uncertain tool actions.

Custom assistants

Specialized assistants for your team

Turn any configured model into a purpose-built assistant: a name, an avatar, a custom system prompt, and starter prompts — published once by an admin, picked by users on the new-chat screen, and pinned per conversation.

  • Built on any provider profile and model you've configured — cloud or local
  • Optional shared knowledge base — documents every user of the assistant can search
  • Per-assistant capability limits: allow or block web search, personal documents, and agent tools
  • Public to all users or restricted — prompt edits apply everywhere, instantly
The admin assistant editor showing a Space Alien persona with an avatar emoji, provider profile and model selection, a custom system prompt, starter prompt suggestions, capability checkboxes, visibility, and a knowledge base upload area
The admin assistant editor — persona, model, prompt, starter suggestions, capabilities, and knowledge base in one panel.
Agent skills

Teach the agent how you work

Skills are named, reusable markdown instruction sets — "how we do data analysis here," "how to write a research report," "how to build a single-file web app." Each one loads its full instructions on demand, while a short catalog helps the agent discover relevant workflows.

  • Two ways to run: type / to pick one, or leave the Skills toggle on and let the agent auto-activate the best match
  • Every user manages their own private skills; admins publish public ones to the whole team
  • Import and export the Anthropic SKILL.md format — drop in community skills or share your own
  • use_skill is a normal gated tool with the usual auto · ask · deny policy and per-assistant capability limits
  • Three example skills — data-analysis, deep-research, web-app — seeded on first boot
The Settings Skills panel: a skill editor with a Name slug, a Description that drives auto-activation, a Markdown instructions workflow, an 'Agent may auto-activate' checkbox, and public/private visibility — above a list of the seeded data-analysis, deep-research, and web-app skills
Settings → Skills — a name, a description that drives auto-activation, the markdown workflow, an auto-activate flag, and public/private visibility.
The chat composer with the slash-command skill picker open, listing the data-analysis, deep-research, and web-app skills above the input, with a Skills toggle among the composer controls
Type / in the composer to pick a skill — its full instructions are injected for that turn, while the Skills toggle lets the agent choose one on its own.
Opt-in Research mode

Set the scope. Follow the evidence.

Change Chat to Research in the composer for a focused investigation. Ask a concrete question, choose your sources, and follow the plan through to a cited report. Normal chat remains the default, including the next turn after a research request.

  • Research the web, selected documents, or documents and web together
  • Choose Brief, Standard, or Thorough depth; optionally limit web domains
  • Follow the plan, gathering progress, source counts, and available model usage
  • Inspect retained passages behind citations and export the report as Markdown
  • Use Stop to cancel further work; incomplete research reports its gaps

Research setup, limits, and examples →

Research uses the current question and selected sources, with bounded gathering and read tools. It requires a tool-capable model. The deep-research skill remains separate guidance in ordinary chat. Enable reconnectable runs to keep research going across refreshes; otherwise keep the chat open.

1
PlanOutline the questions and evidence to gather.
2
GatherSearch selected sources and capture passages within the chosen limits.
3
ReportWrite from available evidence, with citations and gaps to review.
Knowledge & memory

Keep the passage behind every source

Upload PDF, DOCX, Markdown, text, or code. Track processing, retry failures, and search personal, conversation, or assistant documents. Open a citation to inspect its retained passage and available page, section, or table location.

  • Attach files to a message or reference documents with @
  • Hybrid retrieval with reranking; explicit keyword fallback when the embedding index is unavailable or incompatible
  • Web search discovers pages; successful HTML/text fetches supply captured passages with URLs and fetch times
  • Source labels survive approvals, reloads, and Markdown export
  • Rebuild the search index explicitly when changing embedding models; failed rebuilds preserve the previous published index

Document citations · Web evidence · Processing and indexes

Local semantic retrieval needs a configured embedding model. The built-in local-hash fallback is not semantic search. OCR and JavaScript-rendered web pages are not included.

1
ParsePDF · DOCX · TXT · MD · code
2
Chunk & embedpages, sections, and DOCX table rows
3
Hybrid searchRRF fusion across both vectors
4
Rerankrank passages for the query
5
Citeopen retained evidence [S1]
Built for teams

Multi-user controls and accountability

Auth is on by default. Owner-scoped routes and cross-user regression tests protect private user content, while sensitive tools run behind a permission gate you control.

Auth & SSO

Local accounts (bcrypt + JWT) or Microsoft Entra ID SSO. The Entra authorization-code flow validates one-use state, nonce, PKCE, issuer, tenant, and audience. Administrators manage accounts without a bypass to users' private content.

Three execution runners

The fast local subprocess trusts the Phlox host and is not an isolation boundary; it is for trusted single-user use only. Shared deployments use an ephemeral Podman/Docker container with resource/network controls or off-host AWS Bedrock AgentCore execution. Configured isolation fails closed rather than silently running locally.

Per-tool permissions

Each tool is auto, ask, or deny. Mutating and execution tools default to ask; Agent mode is off by default and auto-approves only when explicitly enabled for a turn.

Live admin config

Edit provider profiles, model pricing, resilience, and sandbox limits from an admin panel — applied without a restart. API keys are write-only and masked.

Observability

Per-request structured logs, an optional OpenTelemetry tracing seam, and per-call token/cost records covering chat, children, compaction, fallback, gateway, and probes. Missing usage or pricing is shown as unknown.

Departmental chargeback

A durable usage ledger outlives the accounts it tracks — a departed user's costs stay billable after their account is deleted. Usage by month × user × department × model, CSV-exportable.

Spend budgets

Set monthly budgets per user or department. Current known spending gates subsequent model calls, including children and compaction. Warnings and monthly resets are shared by chat and the gateway; budgets are not a guaranteed billing ceiling.

Hardened harness

Sub-agents inherit the parent’s effective permissions. Web fetching validates destinations and redirects, blocks non-public addresses by default, and bounds response size and time. Stop requests cancellation without claiming to undo completed remote actions.

SQLite or PostgreSQL

Use SQLite by default or configure PostgreSQL. Checked migrations and verified offline backup/restore support both. Run one Phlox process per database/data directory, including with Postgres.

Authentication settings showing Microsoft Entra ID single sign-on configuration
Entra ID SSO & local accounts
Sandbox limits panel with container memory, CPU, PID, and network controls
Container sandbox resource limits
Tools and permissions panel with per-tool auto, ask, and deny policies
Per-tool auto · ask · deny policies
Guardrails

Configurable controls for provider-bound text

Guardrails are optional and disabled by default. When enabled, an administrator can apply text/regex-based rules to provider-bound messages, replayed history, and tool results, and to model output streaming back. Built-in patterns cover emails, phone numbers, SSNs, credit cards, and API keys; custom regular expressions can cover organization-specific identifiers. The original user transcript may still be stored by Phlox.

  • Redact or block, set per direction — filter what reaches the provider, what comes back to users, or both
  • Streaming-safe — buffered output lets rules inspect text patterns that span streamed chunks
  • Per-pattern actions: redact PII globally while hard-blocking project codenames or record numbers
  • Enforced identically in interactive chat and the OpenAI-compatible /v1 gateway
  • Built-in test-pattern preview — try a policy against sample text before you save it
  • Not a DLP guarantee — pattern matching can miss sensitive data; review provider retention, logging, and deployment controls separately

Phlox does not currently support PHI or regulated-data deployments. Those uses remain out of scope until the documented governance, managed-secrets, audit, and independent-review gates are complete.

The admin Guardrails panel: policy enable and save controls with input action set to Redact, five built-in PII detectors with replacement tokens, a custom MRN regex pattern, and a test-pattern preview showing 'Contact me at [EMAIL], call [PHONE], my social security number is [SSN]' with a status footer of policy chips
Settings → Guardrails — global input/output actions, five built-in detectors, custom regex patterns, and a live preview of what the provider would receive.
The platform layer

An LLM gateway and cost ledger for the whole team

Beyond chat, Phlox is an OpenAI-compatible gateway with per-user API keys, live model pricing, department-level chargeback, and monthly spend budgets. Unknown usage and pricing are distinguished from zero. The gateway exposes model completions; it does not expose the interactive agent loop or document retrieval.

Usage and cost dashboard grouped by department, user, and model with per-month totals and CSV export
Usage & cost, grouped by month × department × user × model — exportable to CSV for finance.
API keys management panel showing per-user keys for the OpenAI-compatible gateway
Mint per-user API keys — call Phlox from any OpenAI SDK
Model pricing editor with input and output cost per million tokens for each model
Live model pricing — applied to new turns, no restart
Spend budgets

Track spending and gate subsequent calls

Set monthly budgets per user or department and warn as known spending approaches the limit. Phlox checks the most restrictive applicable budget before subsequent calls to priced models. Missing provider usage and unpriced models remain unknown; concurrent calls can exceed a limit because budgets do not reserve funds.

Admin Budgets panel showing monthly spend caps for departments and users with spent-vs-limit progress bars, editable limit and warning thresholds, and a form to add a budget
Admin budgets — a monthly cap per user or department, with an adjustable warning threshold and live spend bars.
In-app banner warning that the department has used 97.2 percent of its monthly budget
Approaching the limit — an in-app warning at your chosen threshold
In-app banner showing the monthly budget has been reached and priced models are paused until reset
Budget reached — priced models pause; free models still work
A curl request to the OpenAI-compatible gateway returning an insufficient_quota error because the monthly budget is exceeded
Enforced at the gateway too — an OpenAI-shaped insufficient_quota error
Under the hood

A straightforward self-hosted architecture

A FastAPI backend handles LLM orchestration, the agent harness, MCP, RAG, code execution, auth, and persistence — SQLite by default, with optional PostgreSQL. A React + Vite frontend renders the rich, streaming UI.

Frontend React + Vite + Tailwind
  • Zustand store — live streaming assembly
  • Streaming chat and cursor-based run replay
  • Tool cards, reasoning, inline artifacts
  • CSS-variable theme tokens
Backend FastAPI
  • Agent loop, run worker, and document worker
  • Permission gate — the security seam
  • Providers: OpenAI-compatible & Bedrock
  • RAG · sandbox · workspace · MCP
  • SQLite or Postgres + Qdrant index

Development uses Vite and FastAPI. In production, one FastAPI process serves the built frontend and runs the application workers. Postgres or server-mode Qdrant does not enable multiple application workers or replicas.

Make it yours

18 themes. One familiar workspace.

Explore neon, pastel, warm, and minimal palettes. Phlox Dark is the default; switch instantly in Settings → Appearance.

Phlox Research workspace

Help me turn these notes into a plan.

A clear next step

Collect the sources, compare the findings, and draft an outline you can review.

[S1] Retained passage
Message Phlox…
Phlox Dark · Illustrative preview using the app’s palette.

Includes Outrun, Blade Runner 2049, Chaos Theory, both Cyberpunk variants, Synthwave, and more. Full catalog and custom themes →

Start with a local installation

Quick start

The launcher installs project dependencies, creates a config if needed, and opens your browser. Connect a running model server or a cloud provider.

Gituv · Python 3.11+Node/npm · CI uses Node 20macOS · Linux · Windows
macOS / Linux 
git clone --branch v0.3.0 --depth 1 https://github.com/robert-mcdermott/phlox.git
cd phlox
./scripts/start.sh dev
Windows PowerShell 
git clone --branch v0.3.0 --depth 1 https://github.com/robert-mcdermott/phlox.git
cd phlox
.\scripts\start.ps1 dev
  1. Sign in. A fresh database prints a temporary administrator password at startup. Replace it at first login; existing installations retain their accounts.
  2. Connect a provider. Open Settings → Configuration → Provider profiles. Enter the endpoint and credentials, enable Automatic discovery, choose a default model, and save. The launcher does not install model servers or download models.
  3. Start a conversation. Choose a profile and model in Settings. Stop the app with Ctrl+C or the platform’s scripts/stop launcher.

Detailed first-time setup · Provider configuration · Docker / Podman

Preparing a shared deployment

The local execution runner trusts the host. Configure container or AgentCore execution for shared use. Auth-enabled production requires a stable PHLOX_JWT_SECRET and an isolated runner; follow the production setup guide before using prod.

Existing installations

Upgrading to v0.3.0

  1. Stop Phlox and preserve a complete offline backup of the database, data paths, configuration, and external secrets.
  2. Check out v0.3.0, install the release dependencies, and follow the checked upgrade procedure. Startup applies the new project, conversation-alternative, and artifact migrations through 0008_artifacts. Do not stamp the database manually.
  3. Rebuild the frontend for production, then restart Phlox. Chat and DuckDuckGo remain the defaults. Existing provider profiles with configured model lists stay curated; enable Automatic in the admin console to discover additional models.

Artifact versions are stored in the database; saved answer files also use the data directory. Keep both in your backup. Upgrading from before v0.2.0? Follow the full guide for earlier schema and document-index requirements.

Backup, migration, and restore guide →

Documentation · v0.3.0

A guide for every stage

Start with the User Guide, then use the focused guides for your deployment and workflow.

Start here

Phlox User Guide

From your first model connection to upgrades and recovery.

Start and operate

User GuideInstallation, configuration, everyday use, and troubleshooting.Backup and restoreChecked upgrades, offline backups, verification, and recovery.Linux deploymentsystemd, reverse proxy, TLS, and production configuration.Docker / PodmanImages, persistent data, provider networking, and sandbox setup.AuthenticationAccounts, private data, and Entra ID SSO.Execution runnersLocal, container, and remote execution choices.BudgetsMonthly thresholds and enforcement boundaries.

Chat, projects, and sources

Projects and contextPrivate projects, shared instructions, document scope, and context inspection. Conversation alternativesEdit, regenerate, navigate saved paths, and retain answer files. Editable artifactsText editing, AI revisions, saved versions, and workspace updates. Research modeSource scope, depth, progress, citations, and Stop. Web search providersDuckDuckGo, Serper, public SearXNG, and fallback. Runs and StopReconnect, approvals, interruption recovery, and retention.Tool approvalsReview, resume, expiry, and current policy checks.Document citationsCaptured passages, source locations, and export.Web evidenceFetch behavior, source inspection, limitations, and deletion.Document processingUpload progress, retries, reprocessing, and index rebuilds.SkillsReusable workflows and slash-command invocation.

Configure and extend

Model discoveryAutomatic catalogs, searchable selection, curated lists, and provider support. Usage and model callsContext limits, pricing, retries, and unknown usage.ObservabilityUsage reports, structured logs, and tracing.API gatewayPer-user keys and OpenAI-compatible completions.GuardrailsOptional text-pattern redaction and blocking.MCP toolsConnect and manage external tool servers.ThemingThe 18 palettes and custom themes.DevelopmentLocal checks, browser tests, and retrieval fixtures.ArchitectureSystem map and extension points.

For contributors: current roadmap · add a tool · add a provider

Self-host your own AI assistant today

Open source under Apache 2.0. Clone it, point it at a model, and run.

View on GitHub Quick start →