An open-source experiment · MIT licensed · self-hosted
per·nix /ˈpɛɾ.nɪks/ — Latin: nimble, swift of foot.
A self-hosted agent harness, wrought in code.
It lives on your hardware, holds memory you own, and runs the same work loop regardless of which model you put inside it.
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 confidence — 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.
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.
git_log read_file × 4 search_memory
five commits, all on session-token rotation. flagging two for compliance review
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. Append-only. Resumable. Restart-proof.
queueA small fast model in a fresh context plans the approach — picks tools, loads only the relevant skills.
fast modelThe main model executes. Streams tokens, calls tools, reads results, calls more tools — until done.
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.
backgroundCompaction 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, and archives post-mortems. The moment you send a new message, Snooze stops — your work always wins.
IV. The state machine
Every session is in exactly one state. Transitions are logged, replayed to the UI in real time, and recovered after a crash.
V. The orchestration
A conversation, a swarm, a recipe. Each one a different way to put the agent to use — chat, parallelize, automate.
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.
repeatable YAML pipelines
A workflow is a YAML pipeline in data/workflows/ — explicit steps, explicit dependencies, parallel waves. Build one for a job you do every Monday, then schedule it on cron. The same workflow runs unchanged whether the brain inside is a local model, a frontier API, or a mix of both. The agent assembles the workers, you read the output.
cronOne conversation. Many workers. Many recipes. Pernix is happiest when you use all three.
VI. The thesis
A chatbot is where you ask for help. An agent harness is where work happens. Pernix is a harness — it has a job to do, a place to run, memory of what happened before, and enough structure that the underlying model can change without destroying the workflow.
Define the workflow once — explicit steps, tool calls, retry logic, scheduling. It runs the same whether today or next quarter, whether the model is local Qwen or a frontier API call. The loop outlives the brain.
Use a fast local model for cheap classification passes. Route hard reasoning to a frontier API. Put a vision specialist in one worker and a code model in another. The workflow doesn't care which brain is inside.
Context, decisions, lessons — in plain Markdown on your disk, tagged with source and confidence, not trapped inside any provider's product. When you switch models or providers, the memory follows. No lock-in. No drift.
VII. The capabilities
Markdown facts, decisions, lessons. Searched before each turn. Idle-time consolidation merges duplicates and ages out stale lessons.
Tavily or DuckDuckGo for search. Playwright for JS-heavy pages, SPAs, paywalled markdown.
Spawn parallel sub-agents on different models. Slow planner, fast editor, vision specialist — same conversation.
Markdown capability packs with YAML frontmatter. The agent loads them only when relevant.
Run agents on a schedule. Morning brief, weekly digest, watchdog scripts — all built in.
When enabled, each response is graded against the original intent. Missed it? The turn re-runs with the lesson appended — bounded retries before surfacing.
The agent can write its own tools and skills. New capabilities show up on the next turn — no rebuild, no restart.
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.
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.
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 -N http://localhost:8090/api/sessions/abc123/messages \ -H "Content-Type: application/json" \ -d '{"text": "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 · 0.x.x · alpha ◇ binding to 127.0.0.1:8090 ◇ ollama: connected · 4 models ◇ swagger: http://localhost:8090/docs ◇ open http://localhost:8090
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…
⚠ Heads up — alpha software. Treat it like a power tool, not a toy.
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.