Self-hosted AI chat for teams who prefer a coherent tool over a feature maze.
One Bun process · SQLite · pi JSONL sessions · local attachments · resumable streaming
See it work · Capabilities · Quick start · Administration · Status
Solar keeps research, source evidence, model choice, tools, and the next prompt in one working surface. This example combines web and local-tool calls while keeping its source trail attached to the reply.
Source chips work inline and a compact source list collects the material behind the response.
Start from a reusable preset, choose a configured model, set answer detail, and select the MCP servers that may run. The conversation menu makes its current context window, compaction progress, and cost inspectable.
Files become native model inputs where supported. Tool activity streams as part of the answer, including built-in context tools and remote MCP servers; the finished answer can cite the sources it used.
- Pi-powered, model-flexible chat.
pi-coding-agentowns the agent loop and session state, whilepi-aiprovides a unified path across configured providers and model APIs. Switch models per conversation without rebuilding the workspace around one vendor. - First-class streamed parts. Thinking, tool calls, Markdown, code, LaTeX, citations, and source lists arrive in the thread as they are produced.
- Remote MCP tools. Connect Streamable HTTP MCP servers, discover tools, prompts, and resources, and enable them globally, per user, or per conversation.
- Context that manages itself. Solar builds a bounded context from stable instructions, the first request, a structured rolling summary, and useful recent turns. Background compaction reduces old reasoning and bulky tool transactions before older history is summarized.
- Files without a heavy RAG pipeline. Images become provider-native vision inputs. Plain text and supported Office/PDF documents are extracted or passed through according to model capability—no embeddings or vector database required.
- Persistent by default. Conversation ownership, settings, and attachments
live in SQLite and the local data directory. Canonical conversation messages
and pi session state live as JSONL under
SOLAR_PI_AGENT_DIR. A dropped browser connection does not cancel generation; reload can bring it back. - Responsive and themed. The sidebar becomes a drawer on narrow screens; themes persist automatically, with Solar Light and Solar Dark among the choices.
- Lightweight deployment. A single Bun/Hono process serves the API, SSE stream, and React build. No separate frontend host, queue, vector store, or services bundle is required.
browser
│ typed tRPC + SSE UI Message Stream
▼
one Bun process ── Hono / tRPC / pi RPC bridge
│ │ │
│ │ └── pi --mode rpc child (live generation)
│ └──────────────── models, reasoning, MCP tools
├── React + assistant-ui
├── SQLite (auth, ownership, settings, attachments)
└── Mirage local disk (images, text, documents)
│
└── pi JSONL sessions under SOLAR_PI_AGENT_DIR
The generation task is decoupled from the HTTP request. The pi child persists
the canonical session while the server bridge buffers deltas and lets SSE
subscribers reconnect with Last-Event-ID. Explicit Stop is the
cancellation boundary.
cp .env.example .env
# Set BETTER_AUTH_SECRET to a strong value of at least 32 characters.
docker compose up --buildOpen http://localhost:3000. The ./data directory contains the persistent
database, attachment data, and pi agent/session state.
The first account registered on a fresh deployment becomes the admin. In local
development, the seeded convenience account is admin@solar.local with
password password.
bun install
SOLAR_MOCK_LLM=1 bun run devThe managed server uses scripts/port-allocator.sh to choose a stable worktree-specific
port in the 3000–3999 range. Set PORT to override it. Use SOLAR_MOCK_LLM=1 to exercise the
full UI with a zero-cost local generator. On an empty development database, it
prints the seeded admin login and generated Development API key, which persists
with the database.
To expose the local server through FRP, install frpc and set
FRPC_SERVER_ADDR and FRPC_AUTH_TOKEN. Solar starts the tunnel after /healthz
is ready. FRPC_SERVER_PORT defaults to 7000; FRPC_SUBDOMAIN_HOST optionally
adds the public hostname to the logged URL.
bunx @mcowger/solarSQLite, attachments, and pi agent/session state are created relative to the current directory by default.
Solar puts the operational surface in the product: users and administrator API keys; provider endpoints and imported models; model capabilities and context policy; task-model and large-paste settings; and aggregated token usage.
| Variable | Purpose |
|---|---|
BETTER_AUTH_SECRET |
Required signing secret; use 32+ random characters |
BETTER_AUTH_URL |
Public base URL; every OAuth redirect URI derives from it |
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET |
Optional Google OAuth credentials |
OIDC_ISSUER / OIDC_CLIENT_ID / OIDC_CLIENT_SECRET |
Optional OpenID Connect provider; all three enable it |
OIDC_DISPLAY_NAME / OIDC_SCOPES / OIDC_DISABLE_SIGNUP |
Sign-in button label, requested scopes, and whether first sign-in may provision |
OIDC_ADMIN_CLAIM / OIDC_ADMIN_VALUE |
Optional group claim and value granting the admin role |
CLOUDFLARE_RADAR_API_TOKEN |
Optional Cloudflare Radar token for source categories |
SOLAR_AIRGAP_MODE / AIRGAP_MODE |
Set to 1/true/yes/on to block outbound network calls |
DATABASE_PATH |
SQLite file path |
SOLAR_ATTACHMENTS_DIR |
Local attachment storage directory |
SOLAR_PI_AGENT_DIR |
Persistent pi agent state and canonical conversation sessions |
SOLAR_PI_CWD_ROOT |
Scratch directories used as pi process working directories |
SOLAR_PI_MAX_PROCESSES |
Maximum concurrently live pi RPC children (default 8) |
SOLAR_MCP_TOOL_TIMEOUT_MS |
How long one MCP tool call may run (default 60000); keep it below SOLAR_PI_STALL_TIMEOUT_MS |
SOLAR_MODEL_SYNC_INTERVAL_MINUTES |
Minutes between background model syncs for providers with auto-sync on (default 60; 0 turns the timer off) |
PORT |
Listening port / managed dev-server override |
FRPC_SERVER_ADDR / FRPC_AUTH_TOKEN |
Optional FRP server address and token |
FRPC_SERVER_PORT |
Optional FRP control port; defaults to 7000 |
FRPC_SUBDOMAIN_HOST |
Optional FRP public hostname suffix |
SOLAR_MOCK_LLM |
Enable the local zero-cost mock provider |
Provider keys, enabled models, presets, context policies, and MCP servers are
managed from the authenticated UI. See .env.example for the complete runtime
surface.
Model sync. Each provider card has a Sync models button and an
Auto-sync models switch. A sync reads every endpoint's GET /v1/models
(endpoints sharing a URL are read once):
- New gateway models are added as Private (admins only). Set a model to Public to offer it to everyone, or to Hidden to offer it to nobody: a hidden model stays in the list, so a sync keeps it hidden instead of adding it back.
- What the gateway reports is refreshed: reasoning, vision, service tiers and pi routing. What an admin set is kept: visibility, name, context window and policy, documents, reasoning effort and max tokens.
- Models the gateway no longer lists are removed. The button removes them at once; the timer waits for a second miss in a row.
- A failed, empty or implausible reply (one that would remove every model) changes nothing and is shown on the card.
Providers with auto-sync on sync shortly after start, then every
SOLAR_MODEL_SYNC_INTERVAL_MINUTES. A save from a form loaded before a sync is
refused, so the admin can reload instead of undoing it. Running conversations
pick up changed models on their next turn. Model sync is off in airgap mode.
When SOLAR_AIRGAP_MODE (or AIRGAP_MODE) is active (1, true, yes, or on):
- Geocoding is disabled (browser GPS coordinates are kept, but no reverse-geocoding calls are made to OpenStreetMap Nominatim).
- Domain classification uses local DB cache and bundled registries only, skipping Cloudflare Radar API lookups.
- Google OAuth is disabled and hidden from sign-in options.
- OIDC sign-in stays enabled: a self-hosted identity provider is the operator's own service, not a third-party call.
- Citation favicons are replaced with inline SVG placeholders, suppressing remote favicon fetches in the browser.
- Model sync with provider gateways is off (no Sync button, no background timer).
Source-category badges use a bundled registry of 300+ news domains derived from Wikidata's CC0 news-media and newspaper records. Unknown domains are resolved through the optional Cloudflare Radar fallback and persisted locally.
Google OAuth is enabled when both Google credentials are set. Configure the
Google OAuth redirect URI as ${BETTER_AUTH_URL}/api/auth/callback/google.
Google sign-ins use the verified Google email address to identify and link the
account; accounts with different email addresses are not linked.
Solar can sign users in through one self-hosted OpenID Connect provider. Set
OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_CLIENT_SECRET to enable it; the
sign-in page then shows a "Continue with OIDC_DISPLAY_NAME" button. Endpoints
are read from ${OIDC_ISSUER}/.well-known/openid-configuration, and the flow
uses PKCE. The issuer and discovered userinfo endpoint must use HTTPS; cleartext
HTTP is accepted only for localhost, 127.0.0.1, and [::1] development
endpoints.
Register this redirect URI at the provider:
${BETTER_AUTH_URL}/api/auth/callback/oidc
Issuer values differ by product:
| Provider | OIDC_ISSUER |
Group claim |
|---|---|---|
| Authentik | https://auth.example.com/application/o/<slug>/ |
groups |
| Keycloak | https://kc.example.com/realms/<realm> |
realm_access.roles |
| Zitadel | https://<instance>.zitadel.cloud |
urn:zitadel:iam:org:project:roles |
| Authelia | https://auth.example.com |
groups |
A first sign-in creates the Solar account, subject to AUTH_ALLOWED_DOMAINS.
Set OIDC_DISABLE_SIGNUP=1 to require that an admin create the user first,
matching Google's behaviour. An IdP identity is linked to an existing account
when the email addresses match exactly; differing addresses are never linked.
The first account on a fresh deployment becomes the admin however it signs in.
Setting both OIDC_ADMIN_CLAIM and OIDC_ADMIN_VALUE maps a group to the admin
role, re-checked on every OIDC sign-in, so removing someone from the group at
the provider demotes them (and revokes their API keys) on their next sign-in.
Solar refuses to demote the last remaining admin. The claim must reach Solar in
the ID token or the userinfo response: on Keycloak add a mapper with "Add to ID
token" or "Add to userinfo" enabled, and request whichever scope carries it via
OIDC_SCOPES. Roles stay manually managed in Settings when these are unset.
Sign-ins are PKCE-protected, and when the provider's discovery document advertises a JWKS endpoint the ID token's signature and nonce are verified too.
Pi session JSONL is the canonical conversation history. Back up SQLite, attachments, and the complete pi agent directory together. To move conversations between instances, export a pi-native history bundle:
bun run solar history export --user admin@solar.local --output history.json
bun run solar history import --user admin@solar.local --input history.jsonRun with the same DATABASE_PATH and SOLAR_PI_AGENT_DIR as the server.
Pre-029 one-shot: instances upgrading from a build older than the migration-window cleanup must backfill pi sessions from the archive tables before first booting the new build (029 drops those tables). Stop the server, back up, then run:
DATABASE_PATH=/data/solar.db SOLAR_PI_AGENT_DIR=/data/pi-agent \ bun apps/server/scripts/import-archive-to-pi.ts --dry-run DATABASE_PATH=/data/solar.db SOLAR_PI_AGENT_DIR=/data/pi-agent \ bun apps/server/scripts/import-archive-to-pi.tsThe script is idempotent (skips conversations that already have sessions) and exits 0 with nothing to do once 029 has applied.
bun run deploy:productionThe command uses scripts/deploy.ts. Overrides use
SOLAR_PRODUCTION_* environment variables. Keep the
deployment's /data volume intact across upgrades: it contains SQLite,
attachments, and /data/pi-agent, including canonical session JSONL.
Solar is experimental. The streamed chat path, multi-provider model selection, presets, reasoning controls, citations, attachments, context management, admin surface, PWA shell, and remote MCP integration are present; APIs and UI details may still evolve.
The project deliberately does not include RAG/vector search, voice, image generation, channels, multi-tenant enterprise SSO (SAML, per-organization providers), or horizontal multi-node scaling.
See docs/releases.md for the CalVer release process, Docker image, and GitHub release notes.
bun run typecheck
bun run test
bun run buildThe repository is a Bun workspaces monorepo with apps/server, apps/web, and
packages/shared. The server owns migrations for application tables; Better
Auth owns its auth migrations.
On a new Linux machine, install Playwright's host packages once, then install
browser binaries as the regular user (do not run the second command with sudo,
or the browsers land in root's cache):
sudo node ./node_modules/@playwright/test/cli.js install-deps chromium firefox webkit
bun run test:e2e:installRun E2E tests with bun run test:e2e (Chromium) or bun run test:e2e:all
(Chromium, Firefox, WebKit).
For real deployments prefer a supervisor (systemd Restart=always or PM2) —
bun run itself does not restart on crash or rotate logs.




















