Skip to content
mcowgerPublic

About

No description, website, or topics provided.

Resources

Stars

16 stars

Watchers

0 watching

Forks

Latest commit

 

History

312 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Solar, a self-hosted AI workspace for models, tools, files, and durable context

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

See it work

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.

Solar desktop conversation showing a sourced research answer, source chips, chat history, model selection, and composer controls

Solar mobile conversation with cited research, source links, and the full composer    Solar dark-theme desktop conversation with cited research and source chips

Evidence stays with the answer

Source chips work inline and a compact source list collects the material behind the response.

Inline source chips from NPR, Reuters, and CBS News beside a cited answer

Set up the conversation, not just the prompt

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.

New-chat preset menu with Legal and Quick presets   Model picker listing configured GPT and Claude models   Answer verbosity selector from minimal through max

Preset editor with model, system prompt, live context values, reasoning effort, verbosity, and scope

MCP tool menu with automatic execution and per-server toggles   Conversation menu showing context, compaction percentage, cost, and a copyable chat ID

Give the agent real work

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.

Solar answer summarizing an attached PDF and image

A Solar response running built-in date and location tools alongside an Exa web-search tool   Completed multi-tool answer with local news, terminal output, solar production data, and source links

What you get

  • Pi-powered, model-flexible chat. pi-coding-agent owns the agent loop and session state, while pi-ai provides 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.

How it works

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.

Quick start

Docker Compose

cp .env.example .env
# Set BETTER_AUTH_SECRET to a strong value of at least 32 characters.
docker compose up --build

Open 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 development

bun install
SOLAR_MOCK_LLM=1 bun run dev

The 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.

Bun package (after publishing)

bunx @mcowger/solar

SQLite, attachments, and pi agent/session state are created relative to the current directory by default.

Administration

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.

Users and API keys

Administration users screen with user creation and role controls

Administration API keys screen with create, rotate, and revoke controls

Providers, models, and context

Provider configuration with API endpoints and imported models

Per-model settings for visibility, documents, thinking, verbosity, context window, and context management   Global context-management settings with a customizable summary prompt

Operations and defaults

Task-model configuration with the chat-title prompt

Large-paste handling settings that convert text to a removable attachment   Usage dashboard aggregating messages and input and output tokens by user and model

Configuration

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.

OIDC / SSO

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.

Backing up and restoring chat history

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.json

Run 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.ts

The script is idempotent (skips conversations that already have sessions) and exits 0 with nothing to do once 029 has applied.

Deployment

bun run deploy:production

The 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.

Status

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.

Releases

See docs/releases.md for the CalVer release process, Docker image, and GitHub release notes.

Development

bun run typecheck
bun run test
bun run build

The 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.

Playwright E2E setup (one-time)

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:install

Run E2E tests with bun run test:e2e (Chromium) or bun run test:e2e:all (Chromium, Firefox, WebKit).

Process supervision note

For real deployments prefer a supervisor (systemd Restart=always or PM2) — bun run itself does not restart on crash or rotate logs.

About

No description, website, or topics provided.

Resources

Stars

16 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages