Phlox
GitHub
Open source · Self-hosted · Apache 2.0

Your models.
Your AI workspace.

Chat with your choice of local or cloud models. Research documents, the web, and public data, then turn the results into reports, charts, and working code. Keep it together in private projects, with tools and permissions you control.

Get started Read the user guide
v0.4.0 Public data, reports, and more reliable research →
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
Data → reportscollect, analyze, and export
Apache 2.0open source, self-hosted
New in v0.4.0

From research to results

Investigate a question, collect the data, and create something you can use. This release expands research and gives longer tasks more room to finish.

Public data

Go directly to the source

Search NIH RePORTER, PubMed, and ClinicalTrials.gov. Inspect project records, article abstracts and affiliations, or study details with citations.

Explore public-data research → Datasets and reports

Turn records into useful output

Collect beyond a small preview, check coverage, and export CSV or JSON. Build HTML reports with tables and bar charts, or approve custom analysis.

Explore the data workflow → Evidence you can inspect

Keep findings connected to sources

Read deeper into web pages, PDFs, and JSON. Follow source-linked research notes, disagreements, and open questions alongside the report.

Explore cited research → Longer tasks

Build on work already done

Larger research allowances, clearer incomplete results, and saved dataset checkpoints help you continue analysis without collecting the same records again.

Explore continuity and recovery →

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.

Public data and reports

Research publications, grants, and clinical trials. Collect cited datasets, inspect coverage, and create downloadable tables, charts, and reports.

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 →
Agent tools

An agent with tools and clear controls

Go beyond an answer: let the agent work with files, run code, and use connected tools. Follow its progress and review actions in a workspace you can inspect and restore.

01 Code and files

Run Python, JavaScript, or shell commands to analyze data and build applications. Inspect the files and results in the conversation workspace.

02 Planning and delegation

Follow a visible task list as work progresses. Sub-agents can handle parts of a larger task while inheriting the parent’s model, scope, and controls.

03 Permissions and recovery

Choose which tools can run automatically, require approval, or stay disabled. Use Stop to cancel work and checkpoints to restore workspace files.

04 Editable output

Preview HTML and Markdown beside the chat. Edit text and code, review suggested revisions, and save versions you can compare or restore.

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. v0.4.0 improves shutdown handling and preserves completed results during recovery.

  • Enable once in the configuration file and restart
  • Continue a saved dataset by its checkpoint instead of starting collection over
  • 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 and a research notebook with cited findings and open questions
  • Inspect captured passages, including targeted PDF pages and JSON records
  • Export cited Markdown, or create data files and HTML reports with charts
  • Use Stop to cancel further work; incomplete research reports its gaps

Research setup, limits, and examples →

Research requires a tool-capable model and stays within configured limits. Custom code uses an explicit analysis handoff and normal tool permissions; selecting Research does not grant execution access. Enable reconnectable runs to keep research going across refreshes; otherwise keep the chat open.

1
PlanOutline the questions and evidence to gather.
2
GatherCapture evidence and collect supported public datasets.
3
AnalyzeCheck coverage and calculate from saved records. Approve custom code when needed.
4
DeliverReview a cited answer, downloadable data, and the requested report files.
Public data → useful analysis

Research beyond the search results

Ask about publications, funded projects, or registered trials. Phlox queries three public research APIs directly, with no extra API key or service to configure.

Funded projects

NIH RePORTER

Find projects by organization and fiscal year. Inspect reported award amounts, compare years, and review the scope before calculating totals.

Publications

PubMed

Search the literature, read available abstracts, and check author affiliations. Export publication records with citations to the details you inspected.

Clinical studies

ClinicalTrials.gov

Find registered studies by condition and recruitment status. Explore sponsors, phases, eligibility, and available results with links to the registry.

From question to deliverable

Collect once. Keep working with the data.

Bulk collection saves records outside the model’s conversation context. Follow-up analysis can reuse that dataset while its sources remain available.

CSVJSONHTML

  1. Check the query

    Inspect a small preview and confirm the filters match your question.

  2. Collect the records

    Fetch larger pages, save progress, and resume from a dataset checkpoint.

  3. Verify coverage

    See captured and reported counts, missing values, and duplicate records.

  4. Create the report

    Generate tables and bar charts, with downloadable data and source references.

Need a custom chart or calculation?

Approve an analysis handoff to make eligible Python, JavaScript, and shell tools available under your existing permissions. Work from exported records to create custom plots and HTML reports you can preview beside the chat.

Collection remains subject to API and administrator limits. Partial datasets are labelled; missing values stay unknown. These integrations cover the three APIs above, not every public API or full-text journal access.

Queries and examples · Collection and exports · Analysis and reports

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
  • Capture passages from web pages, text-based PDFs, and JSON responses, with source URLs and retrieval 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 searchcombine keyword and semantic matches
4
Rerankrank passages for the query
5
Citeopen retained evidence [S1]
Built for teams

Multi-user controls and accountability

Sign-in is enabled by default. Conversations, documents, and datasets stay private to their owner, while administrators manage accounts, tools, and spending controls.

Auth & SSO

Use local accounts or Microsoft Entra ID single sign-on. Administrators manage accounts and access without an in-app bypass to users’ private conversations, documents, or datasets.

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.
Usage and budgets

See usage. Set spending limits.

Set monthly budgets for users or departments, receive warnings as known spending approaches the limit, and review usage by model.

  • Configure model prices and warning thresholds in the admin console
  • Track known costs; missing usage and unpriced models remain unknown
  • Apply budget checks to chat and the OpenAI-compatible API gateway

Budgets check known spending before new calls to priced models. Concurrent calls can exceed a limit; these controls are not a guaranteed billing cap.

Budget setup and limits →

Connect your other applications

Use per-user API keys to access Phlox through an OpenAI-compatible SDK. The gateway shares model configuration and usage accounting with chat.

API gateway guide →
Admin Budgets panel with monthly limits and spending progress for departments and users
Monthly budgets, warning thresholds, and spending progress in one panel.
Self-hosting

A workspace on your infrastructure

Run Phlox on your own machine or server. Choose the model services and execution environment that fit your deployment.

Start locally

Use the startup scripts on macOS, Linux, or Windows. SQLite is the default; PostgreSQL is available for deployments that prefer it.

Choose where requests go

Use local models or cloud providers. Self-hosting stores application data on your infrastructure; cloud models and web services receive the requests you send them.

Deploy with clear controls

Configure authentication, TLS, backups, and an isolated execution runner for shared use. Production runs one application process per database and data directory.

Deployment guide · Docker and Podman · Technical architecture

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.js 20+ and npmmacOS · Linux · Windows
macOS / Linux 
git clone --branch v0.4.0 --depth 1 https://github.com/robert-mcdermott/phlox.git
cd phlox
./scripts/start.sh dev
Windows PowerShell 
git clone --branch v0.4.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.4.0

  1. Stop Phlox and preserve a complete offline backup of the database, data paths, configuration, and external secrets.
  2. Check out v0.4.0, install the release dependencies, and follow the checked upgrade procedure. Startup applies migrations through 0009_api_datasets for retained public-API datasets. Do not stamp the database manually.
  3. Rebuild the frontend for production, then restart using the updated startup scripts. Follow the v0.4.0 deployment guide for custom services, the server entry point, and graceful shutdown settings.

Back up both the database and data directory: retained datasets, artifact versions, and saved files use these stores. Chat and DuckDuckGo remain the defaults; reconnectable runs and code execution still follow your configuration.

Backup, migration, and restore guide →

Documentation · v0.4.0

A guide for every stage

Start with the User Guide for the complete documentation index, then explore 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

Linux deploymentProduction services, TLS, startup, and graceful shutdown. Docker and PodmanContainers, persistent data, and provider networking. Upgrades and backupsChecked migrations, offline backups, and recovery. Accounts and SSOPrivate user data, account management, and Entra ID. Runs and recoveryReconnect, Stop, approvals, and interrupted work. Execution runnersLocal, container, and remote code execution.

Research and create

Research modeScope, depth, notebooks, search providers, and analysis handoff. Public-data researchNIH RePORTER, PubMed, and ClinicalTrials.gov examples. Datasets and exportsBulk collection, saved progress, coverage, and downloads. Analysis and reportsTables, charts, methods, and reproducible data files. Projects and contextShared instructions, selected documents, and context inspection. Editable artifactsPreview, revise, compare, and restore saved output.

Configure and extend

Model discoveryAutomatic catalogs, searchable selection, and curated lists. Usage and budgetsSpending thresholds and enforcement boundaries. MCP toolsConnect and manage external tool servers. SkillsReusable workflows and slash commands. API gatewayPer-user keys and OpenAI-compatible completions. GuardrailsOptional text-pattern redaction and blocking.

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

Self-host your own AI assistant today

Your choice of models, connected tools, and a workspace you control. Open source under Apache 2.0.

View on GitHub Quick start →