per·nix /ˈpɛɾ.nɪks/ — Latin: nimble, swift of foot.
An agent server you own outright.
It researches, schedules, remembers, and keeps working after you close the tab — on a local model, a frontier API, or both.
I. The premise
Local with Ollama, cloud via your own OpenRouter key, or both — mixed freely. A fast model scouts and plans. A capable one executes. A lighter one handles background work. Workers pick whichever model fits their task. The workflow doesn't care which brain is inside: swap freely, your keys, your routing, your call.
Markdown files in data/memories/. Plain text, full-text indexed, tagged with source and type — yours forever. Stays put when you switch models. Stays put when a provider changes its terms. Not locked to any subscription, not sludge accumulating in a chat thread. Read, edit, or delete with any text editor — and the agent can correct or retire its own entries as it learns better.
No accounts. No cloud subscription. No usage telemetry. A Python server that binds to localhost until you say otherwise — then network mode with HTTPS and bearer-token auth. The harness is yours to inspect, fork, and rebuild.
II. The anatomy
Pernix is one Python codebase that fits in your head. A FastAPI server, a state machine, a streaming agent loop, a memory store, a workspace. On top of it: a built-in PWA, a REST API, and a Swagger UI you can poke from any browser.
Run it on a dedicated VM, container, or spare Linux box. Open http://localhost:8090. Talk to it. Watch it think. Read the code that made it think that way.
An unedited session: asked for a morning brief, the agent built a three-step workflow and put it on cron. Local model, one take.
III. The unfolding
Every message you send rolls through five phases. Each one runs on a model suited to its job — fast for planning, capable for acting, light for verifying.
Your message lands on a persistent thread — text, images, audio, PDFs. Append-only. Resumable. Restart-proof.
queueA small fast model in a fresh context plans the approach — recalls what you've told it before, picks tools, loads only the relevant skills.
fast modelThe main model executes. Streams tokens, calls tools, reads results, calls more tools — until done. If the cloud rate-limits, it falls back to your local model mid-loop.
main modelA quality gate verifies intent was met. Returns pass, retry, or escalate. Up to two retries before surfacing.
verifyAuto-titling, memory distillation, worker cleanup. The cleanup runs in the background after you've already seen the answer.
backgroundhover a phase to sample its events
Compaction trims old turns when context fills past 75%. The originals stay in the database — only the prompt view changes.
Snooze runs between turns. While the agent is idle, it dedupes memory, distills your profile, mines finished sessions for lessons and skill improvements, and archives post-mortems. The moment you send a new message, Snooze stops — your work always wins.
Recovery assumes the worst. Kill the server mid-turn and restart it: interrupted sessions are swept to safety at boot, parents parked on workers are recovered, and clients replay any events they missed by sequence number. Nothing pretends it didn't happen.
IV. The orchestration
A conversation, a swarm, a recipe, a standing order. Each one a different way to put the agent to use — chat, parallelize, automate, schedule.
a conversation thread
A persistent thread. Append-only. Every message and tool call survives a restart. One agent loop runs at a time per session — but you can have many sessions open and switch between them.
parallel sub‑agents
Within a turn, the main agent can spawn workers — sub-agents in their own sessions, each on whichever model fits its task best. A slow planner orchestrates fast editors. A vision model and a code-specialist run side by side — and the UI shows the whole fleet live as it fans out.
repeatable markdown recipes
A workflow is a WORKFLOW.md recipe in data/workflows/ — YAML-frontmatter steps with explicit dependencies and parallel waves. Describe a job you do every Monday and the agent can draft the workflow itself, submitted for your approval before it ever runs. The same recipe runs unchanged whether the brain inside is a local model, a frontier API, or a mix of both.
a standing order
Put a session or a whole workflow on a schedule. Each run gets its own session — the morning brief is built before you wake, the weekly digest writes itself, the watchdog never sleeps. When something needs you, the agent can ping your phone through the PWA's push notifications or a webhook.
One conversation. Many workers. Many recipes. A clock above them all. Pernix is happiest when you use all four.
V. The state machine
Every session is in exactly one state, and every edge is a (state, reason) pair in an exhaustive table — anything not in the table is rejected. Transitions are logged, replayed to the UI in real time, and recovered after a crash. Hover or tap a state to see its real exits; left alone, the diagram walks an actual turn.
Edges drawn from the table in sessions/state_v2.py. Two housekeeping reasons are omitted for legibility: reaper-unstick and cancel-timeout return any stuck state to idle_ready — explicit rows in the table, not a generic force.
VI. The thesis
A chatbot is where you ask for help. A harness is where work happens — a job to do, a place to run, memory of what came before, and enough structure that the model can change without the workflow noticing.
Define the workflow once — steps, tools, retries, schedule. It runs the same today and next quarter. The loop outlives the brain.
Cheap local passes, frontier reasoning, a vision specialist in one worker and a code model in the next. The workflow doesn't care which brain is inside.
Decisions and lessons in plain Markdown on your disk. Switch models or providers; the memory follows. No lock-in. No drift.
VII. The capabilities
Markdown facts, decisions, lessons. Searched before each turn, with each entry's age and provenance shown at recall. Idle-time consolidation merges duplicates and ages out stale lessons.
remember · recall · update_memory · forget
Tavily for search. Playwright for JS-heavy pages, SPAs, paywalled markdown.
search_web · http_get · browse_web
Spawn parallel sub-agents on different models. Slow planner, fast editor, vision specialist — same conversation.
spawn_worker · message_worker · await_workers
Markdown capability packs with YAML frontmatter. The agent loads them only when relevant.
discover_skills · load_skill · read_skill_resource
Run agents on a schedule. Morning brief, weekly digest, watchdog scripts — all built in.
schedule_job · schedule_workflow · list_scheduled_jobs
When enabled, each response is graded against the original intent. Missed it? The turn re-runs with the lesson appended — bounded retries before surfacing.
core/reflect.py · pass | retry | escalate
The agent can write its own tools and skills. New capabilities show up on the next turn — no rebuild, no restart.
create_tool · create_skill · install_package
Different model for primary, scout, fallback, and background work. Ollama, OpenRouter, or both. Auto-fallback to your local model when the cloud rate-limits, times out, or hiccups.
switch_model · list_available_models · call_model
Attach images for vision models, audio in any common format — transcoded to WAV automatically — and PDFs, extracted to text the agent can read and search.
images · audio → wav · pdf → text
The web UI is an installable PWA with a mobile-first layout and browser push notifications. In network mode, a QR code on the console gets your phone onto it in seconds.
pwa · web push · run.py --qr
Watch every state transition on a live timeline, follow the worker fleet as it fans out, search full-text across all past sessions, and see what each one costs.
GET /api/sessions/{id}/events · sse
Tools are tagged safe, caution, or dangerous. Dangerous calls require per-session approval after the agent declares exactly what it will do — and every distinct action gates separately. The agent gets hands; the user keeps the keys.
ask_user · approve_dangerous_tool
VIII. The interface
The web UI is one client. There are many. Pernix is built on FastAPI, which means every endpoint the UI calls is also yours to call — from a script, a cron job, another service, your terminal.
Open localhost:8090/docs while the server runs and you get a live Swagger UI: every endpoint, every schema, every response model — try-it-able right from the browser. /redoc if you prefer ReDoc. The fastest way to learn the system is to poke it.
/api/sessions/{id}/events for tokens, tool calls, state transitions./openapi.json. Generate clients in any language.curl http://localhost:8090/api/chat \ -H "Content-Type: application/json" \ -d '{"session_id": "abc123", "message": "summarize the auth branch"}'
IX. The soul
Pernix's behavior beyond raw model output is shaped by plain text on disk. SOUL.md defines who it is. RULES.md defines how it acts. SESSIONS.md injects deployment-specific context — the user's timezone and key facts, the domains this installation is allowed to act in, per-domain permission levels, and active long-running intents the agent is tracking.
It's the opposite of a black box. The personality, the operational guardrails, the project conventions — all editable, all auditable, all yours. Open them in any text editor. The agent picks up the change on its next turn.
# Identity You are Pernix — a capable, focused AI assistant. You help with complex tasks, think carefully before acting, and communicate clearly. ## Core Traits - Pragmatic: Prefer working solutions over perfect ones. Ship, then iterate. - Direct: Minimal preamble. Get to the point. No filler phrases. - Curious: Enjoy understanding systems deeply before changing them. - Careful: Confirm intent before irreversible actions. Measure twice, cut once. ## Communication Style - Concise by default — expand when the topic demands it. - No sycophancy. No "great question!" - When referencing code, include file paths and line numbers so the user can navigate directly.
data/agent/SOUL.md · data/agent/RULES.md · data/agent/SESSIONS.md · data/skills/*/SKILL.md
X. The first run
Install Ollama, pull a recent model, clone the repo, run the server. Pernix is well-tested with the latest Qwen 3 series on Ollama, and with current frontier models on OpenRouter. Use whatever's current — agentic workloads benefit from newer models with stronger tool-calling and reasoning.
Python 3.11+. Ollama if you want local models — pull a current Qwen 3 release. An OpenRouter key works too; Ollama is optional.
Standard Python: clone, venv, pip install -r requirements.txt. Optional: copy .env.example for OpenRouter or Tavily keys.
python run.py. Open localhost:8090. Pick a model in Settings. Say hello — and open /docs in another tab to watch the API.
Edit SOUL.md. Write a skill. Save a workflow. Schedule it on cron. Read the code in core/ — it fits in your head.
$ git clone https://github.com/calvincs/Pernix.git $ cd pernix $ python3 -m venv .venv && source .venv/bin/activate $ pip install -r requirements.txt $ cp .env.example .env # add API keys if you have any $ ollama pull <your-current-qwen3> # or any modern frontier model $ python run.py Pernix → http://127.0.0.1:8090 # the UI lives at /, swagger at /docs, redoc at /redoc
XI. Honest about what this is
Pernix is alpha. Actively developed. Things will change. Reading what it's for and what it isn't will save you the wrong expectation.
It is for…
It isn't…
⚠ Alpha software. Here be dragons. Sharp edges. Occasional tears. Bugs included at no extra charge — fire extinguisher sold separately.
Pernix is a working personal tool, not a polished product. Built for daily use and shared openly — use it, learn from it, build on it.