This is the second post in a series discussing my research and development into solutions for building better, faster, higher-quality, and more secure code with any agent harness, solo or with a team. Before we dive in, let’s briefly reflect on how we’ve traditionally approached this and look at how some companies and teams are adapting with agentic AI. Over the years, we’ve developed all kinds of processes, frameworks, organizational structures, and team roles to solve for the better/faster/quality challenge. Agile software development, 2-Pizza teams, EM’s, reporting to Senior EM’s, reporting to Directors, Staff and Principal engineers, with TPM’s, PM’s driving and supporting. Now, in the agentic era, companies are experimenting with compressed processes, dropping ceremonies, flattening organizational structures, and widening team roles, emphasizing reasoning and architectural skills with a generalist scope. This shift in how we, software engineers and engineering leaders, work fundamentally changes how we think about product knowledge, codebase knowledge (sometimes called tribal knowledge), and even code quality and automation. Skilled agentic practitioners are not writing the code; the models are very good at that now. They are applying patterns, rules, skills, and procedures to make critical architectural decisions. Your role now is to think through and around solutions, as Models will fixate on patching and narrow scope. You must think in patterns and architecture, whereas models will only seek what they consider the most efficient solutions. Combining the agent’s reasoning with your own to develop a complete solution. Now you add a multiplier to that as you’re driving several threads at once and almost unlearning what you spent a career mastering: deep focus, long mental debugging sessions, and even careful architectural planning. We now must keep those skills, set them aside, and master moving in and out of product context, spec building, rapid decision-making, continuous review and rework cycles, and, with that, codifying those practices so agents can work on your behalf autonomously. Now do all of that with a team, teams of teams (humans and agents), with improved quality, security, and release cadence. For companies all-in on agentic AI, this is the reality now, and it’s not one most are prepared for.

This is a hard problem, and I love hard problems like this. There are so many AI Influencer YouTube videos that say, “Solved it!” “Do this to 10x!” “This skill changes everything!” There is, of course, truth to some of it, even though it reads like click bait. It’s a puzzle everyone is trying to solve, with the pieces changing daily. Harnesses are improving their ability to organize and retrieve memory; they are also advancing their own system prompts, increasing context window size and efficiency through caching, improving compression, and getting faster while “reasoning” more. We layer into that our rules (AGENTS.md), skills, and tools, which the agent will “re-learn” each and every session, like an operating system you boot up, do a series of tasks, shut down when done, and repeat. Agent sessions are ephemeral; treat them that way. Now, I don’t see this as a bad thing; it’s actually incredibly powerful if you understand this and focus on working with it rather than forcing old patterns into this new agentic world. Modern harnesses are highly extensible, with a full set of lifecycle hooks, protocols for standardized tool access (MCP), native exploration and execution tools, and native workflows such as planning mode and code reviews. My goal with Myco is to enhance and augment the already powerful coding harness. A fun example would be something like Spider-Man’s suit (The Tony Stark version). Without the suit, Peter Parker is still Spider-Man, but with the suit, he’s faster, stronger, smarter, and more resilient. So can we tap into all those senses and enhance them? If so, can we build faster, smarter, and more reliable solutions, too? That’s the hypothesis for Myco’s Cortex features, which serve as the connection to those senses.

In my first post, I talked about data capture. Capture in Myco is automatic and universal. If Myco is installed and you start a supported harness, Myco will provision your project locally and begin capture immediately in the background, with zero-touch configuration. Data capture in this context is the work being done by your agents, all of their reasoning, all of your initial prompts and steering prompts, and all of the tools being used and their results. This telemetry is the foundation for the enhanced nervous system we want to build. So let’s talk about what Cortex is, how it works, and see it in action with real sessions driving real outcomes.

Myco Cortex

Cortex is a collection of features in the Myco package designed to provide your agent harness with instructions, project context, and codebase knowledge in real time as the agent works and you interact with it. I’ll break down each of its components, how it works, along with where and how it integrates into your harness’s lifecycle.

Injection lifecycle

Most harnesses offer points in the lifecycle where plugins and integrations can inject relevant information into the session context. The most common points are on Session Start, Subagent Start, after you submit a prompt, and, more rarely, before a tool is executed. The most popular, Claude Code and Codex, support all of them, but you’ll see broad support for the first 3, including open-source harnesses like OpenCode and Pi, and in the enterprise with Copilot and Antigravity. See the full list at myco.sh.

Instructions

When enabled, Cortex will automatically inject a compact set of instructions to inform the agent of its enhanced nervous system, explain what it can do and what you can do with it, and provide a quick sit-rep. These instructions are fully generated by the Myco Agent harness (more on that in an upcoming post) to ensure they’re always accurate. Here is a live example from the Myco project itself, where I dogfood Myco, and another from my unifi-mcp project. You can see that the content is largely the same, since it is generated by the same harness using the same prompts and tools, with only recent workstreams varying.

Instructions can also be used with subagents and team agents. Often, when doing complex work with your harness of choice, it may choose to spawn subagents. This is a very effective pattern when building large implementation plans or any set of scoped work. It’s also effective for context management, as each subagent will operate with its own process and context. Since it operates in a fresh context, it will have only the information provided by the primary or orchestrating agent in its initial prompt. Myco will still collect all work performed by this subagent; however, the subagent will not know about Myco explicitly. For harnesses that support this injection point, we simply provide the subagent with the same instructions (slightly tweaked), so it too can choose to tap into the project intelligence layer. For those harnesses without this (about 50/50 of the popular ones), we also have a short paragraph in the primary agents’ instructions that tells them to enhance their subagent prompt with Instructions. Myco may also tailor some content to specific agents. For example, here is a recorded injection for Codex, where we asked it to start working on a plan built in another session:

There are quite a few things happening here, which can give you a sense of how the intersection of knowledge, tools, context, and planning can work symbiotically between Myco and your agent harness. I’m starting the session with a built-in skill, which allows me to seamlessly handoff a plan from another session (captured with myco using harness native planning), it then tells Codex, “hey you don’t have MCP for these tools; you should use the CLI”, which is customized for Codex (which supports MCP, just not for myco, as we cannot determine project tenancy from the global mcp server install), then all the tools, sit-rep, what branch they are on, and its session id. As part of the handoff, the plan may also tell the agent to load recommended skills (like using-superpowers). It then consults its own memory, grabs the plan from myco, and gets to work. Oh, it did a great job too btw 😉

Spores

Spores are the living knowledge of your project. They are created and maintained by the Myco Agent harness and by the coding harness you are using. They represent active decisions, gotchas, discoveries, and bug fixes. As themes and groupings start to emerge, Wisdom spores are created. Similar to us humans, Wisdom is gathered from experience…three different angles of the same gotcha? We are wise to it now, never again. Spores can be active, be superseded by new or updated Spores, and then become obsolete. Spores are the collective knowledge and history of working on and building your project. You can search for them semantically via a local vector store, and agents can find and access them through tools. In Cortex, semantically relevant Spores are automatically injected into the session context after you type your user prompt, providing your agent with the wisdom it may need to be more effective. Let’s see this in action! This is a session I started yesterday to figure out why Myco’s MCP install for Codex was failing to connect.

This is a Claude Code session. I’m starting with a basic debugging investigation project with an example screenshot from the Codex CLI throwing connection errors related to our MCP server. I also lazily just pasted in my notes, as the prompt could have been better, but that’s kind of the point: myco fills in the gaps for me. Claude gets the instructions, and then it gets some Spores. This was a sub-second search against the SQLite vector store (all spores are automatically embedded when created or updated) based on my prompt. Myco applies a basic algorithm to determine the relevance of the search result, and if it clears that, it is then injected back into the session context. You can see by the Spores injected that this is not the first time we’ve had these issues (I actually forgot). We have some Wisdom from an earlier session: Codex, based on how it’s launched, may not pass along knowledge of which project it’s working on. We then have more Wisdom regarding the MCP stdio bridge, when it was missing authentication, so something for Claude to check. Finally, notes on the MCP server not surviving daemon restarts during a live session (this was solved a while back). So all relevant experience to the task at hand with a rich set of Spores and session references for Claude to investigate, along with its own native tool calls. Spore content can be rich and detailed (as shown), so we provide the agent with a brief overview and a reference to retrieve more details. The goal is the highest relevance with the fewest tokens.

Digest

The Cortex Digest is an actively curated and maintained set of compressed project knowledge that agents, or humans, can use to onboard quickly, possibly circumventing the need for lengthy manual exploration and discovery. There are three tiers. T1500 “Executive Briefing”, T5000 “Deep Onboarding”, and T10000 “Institutional Knowledge”, where T{Number} represents the amount of tokens the Myco Agent targets when writing and maintaining them. This is a very rich source of knowledge that remains on tap at all times for the agent to access via the Cortex tool, and it can also be automatically injected into your session context if you opt in. This can be used in combination with Instructions for rapid onboarding for one-shot prompts or in place of instructions to leverage the knowledge, but let your harness lean on its native tooling instead of being biased towards Myco.

Canopy

Canopy is your project’s live code index. It maps your entire codebase, analyzes all relevant project files, describes each file, and embeds that metadata (not the file’s contents) into the local vector store for easy retrieval and injection. Like all Cortex features, this is not designed to replace the coding harnesses’ native code exploration tooling; it’s meant to enhance it.

Let’s start with the Canopy Map. The map is the context-rich cheat sheet for coding harnesses to quickly orient themselves to the project. Rather than general exploration, they can reach the target area after a single tool call that tells them where to go. It’s not just a directory tree; it provides high-level structural guidance, but more than that, it offers semantic knowledge of those files. Not just where the API is, but what it is. You have a GraphQL and REST API located in apps/api; here are the key areas to pay attention to, along with key files in those sections. Updating your CI workflows: where the workflows are and what each one is responsible for. Working on architectural patterns? Here is what’s in use today and how it fits together. Adding a feature? Here is what a good feature looks like.

The instructions tell the agent about the map, why and when to use it, and in my experience, they will use it more often than not, getting the solution faster. Maps are generated by the Myco Agent from the live code index, Spores, and actual project contents. You had two sessions today. When complete, the Agent gets to work reasoning, distilling, and updating your Map so that it remains current for your next session. The best way to understand it is to see it. This is the full and complete live Map Myco generated for the unifi-mcp project

The above Map is, in part, generated from the Canopy Entries. Entries are the files in your project, but Myco only captures the important bits. We don’t need to ingest the file’s contents; your agent will handle that, and it’s always changing anyway. We want to know where it is, what kind of file it is, and what the file is for. This, along with other metadata, is then stored in the local database and embedded for semantic search. For example, when a file is first scanned or its contents change, the Myco Agent harness will “describe” the file in 1–2 sentences and store that description along with its metadata. The file apps/network/src/unifi_network_mcp/runtime.py has the following description " Provides the UniFi‑Network MCP server's core singletons-config, FastMCP instance, and manager helpers-and exposes lazy getters for testable substitution." ...yep, that's what it does.

Now, for Agent harnesses that support it, we can also use canopy data to inject it back into the context before a file is read, allowing the Agent to skip the read and save the tokens. Canopy tracks this as token savings, which not only can improve the speed of your work but also save you some money. Let’s now see how Entries and Map are used in a live session. This is a recent session for unifi-mcp, the same session from earlier in this post, where we are investigating some API changes in the UniFi Alarm Manager and updating our mutating tools based on that investigation. This is a complex task; we are navigating legacy private API’s and a new V2 api surface, abstracting that knowledge from the tool surface and grounding this work in real data gathered from Playwright, and applying that knowledge using established patterns that will be fully tested, unit and smoke, without introducing regression. aka, product development and software engineering. To see it in action, let’s look at my first prompt again, which, if you remember, was a plan handoff from another session that Myco will facilitate. After the agent finishes reading and updating the plans (there are 4 of them), it orients itself by requesting the Map, decides what to do first, then pauses for a Human-in-the-Loop to proceed (as instructed by the handoff skill), and the work begins.

Codex, in this example, calls for the Map 4 times throughout the session. Myco also opportunistically injects canopy entry context while Codex is actively exploring files. As you can see above, we provide metadata, file imports/exports, and a description, along with a note encouraging the agent to skip the full read if they have what they need. For this session, an estimated 42k tokens were saved through agent read skips. This is rough and not precise; it also does not yet account for Map reads and exploration tokens saved. We’ll dial this in as it continues to prove useful. Canopy never prevents a read and aims to be as efficient as possible, which in this case is estimated at 10x efficiency.

Wrap up

Give your smartest engineer the most complex work on an existing project they’ve never worked on, and tell them they have an hour to build, test, and ship it. They know how to code anything, in any language, using any pattern. They have no idea what language the project is in, its patterns, its rules, or, more importantly, why that language, those patterns, and those rules. It’s almost silly to write that, but it’s true. Every time you fire up the harness, your smartest do-anything engineer, this is the reality. Nothing you do today, including all of this, will teach your agent anything, nor will it remember anything… and if you happen to fill that 1M context window, it likely won’t recall an hour ago. Those of us using these tools know this, and there are ways you should use these tools and ways you should not, if you care about high-quality outcomes. I don’t focus on what it can’t do, but rather on what it can do and is good at. It’s good at code exploration; give it a map. It’s curious and seeks why; tell it how to find out. Same for humans. The prompt isn’t perfect; improve it with wisdom. You get it. Cortex is the result of the Myco Symbiont integration system, data capture, FTS, semantic search, MCP server, and the custom Myco Agent harness. So there is more to share and see over on GitHub. May you forever have double usage on your Max plan. See you in the next post.

Originally published at https://chriskirby.net on June 8, 2026.

In my previous post, I went in depth on the issue of agentic memory and how to address it when working with multiple agents locally and with team members who are also using multiple agents, while trying to preserve institutional knowledge. OAK, was a project i worked on, starting late last year, to start to understand and solve these problems for professional developers and teams. Much of the research and development that went into OAK was rooted in the idea of comprehensive data collection. Can we reliably collect rich data from users, coding agent sessions, and then try to pull meaningful memories from them? And then can we make those accessible via semantic search that’s easily accessible to agents and users alike? Spoiler: the answer is yes. While not trivial, certainly possible and becoming more so as these agents mature. There are many projects out there doing some of this well. Many focused on single-agent ecosystems; however, the premise is consistent. Keep as much context resident with your project as possible to make future agent sessions more successful. This is so critical that agents themselves ship comprehensive memory systems, such as Claude Code’s undocumented dream feature. Which automatically recognizes key concepts, follow-ups, and user cues, and curates them to the local file system as a series of markdown documents. Or just search on the dozens of projects based on Karpathy’s wiki for building personal knowledge bases. Memory is table stakes.

Over the several weeks, my interest in this subject hasn’t dwindled; it’s only gotten stronger. OAK was fun and challenging to build. However, where it started (an SDD toolkit) and where it ended up led to a high level of code complexity, with features that were a little disjointed and an ecosystem that had evolved. I also had new ideas I wanted to explore, and since they were so fundamental to the core architecture, it made sense to start fresh, so I began building Myco. Over the next several posts, I’m going to discuss the features of Myco, the problems I think are worth solving, and how you and your team could benefit from either this project or these ideas as you build moving forward.

Let’s start with the name. Why Myco? First, I love themes. It’s just more fun that way. And second, the previous metaphor: OAK “strong” and memory like the rings of a tree, now moving to a more biological metaphor: Myco or mycorrhizal networks, is a more apt mental model. We have spores, akin to memories and concepts. Symbionts, which combined with you, are the originators of knowledge (agents, skills, prompts, summaries, plans). Digests, which are produced by the Myco agent as it consumes spores and synthesizes raw data. This then gets fed back into the Symbionts, and the cycle continues. It’s a living intelligence right inside your project, changing and evolving as you build. See, I told you I like themes 😄

Setup and Collection

Symbiont’s (aka coding agents). This is the Claude Code session that you’re using to build. We want to understand everything you and Claude are doing and inject relevant intelligence back into the context to ensure that each session, short or long, maintains a consistent, evolving understanding of your code, the project, and what it’s doing. And when you open Codex alongside to make sure Claude’s solution is sound, it starts with the same understanding, and its results add to the collective intelligence, which Claude can then benefit from. Most builders use multiple agents, not just one, so Myco’s data collection and integration are comprehensive. Use Claude, Codex, Cursor, Copilot, Antigravity, Windsurf, Pi, and opencode in the same project.

Setup is simple. It’s going to install the myco NPM package, set up a service to host the daemon locally, and establish a .myco directory in your user home. Any supported coding harnesses you have installed will be automatically detected and configured for data collection and intelligence integration via hooks, plugins, transcripts, and local MCP connectivity to access the myco tools. Your project will be automatically registered on your next session, post-Myco install. Simple, easy, and automatic.

Here’s what’s going on at a high level:

• You start a new session in Claude, and through its lifecycle hooks, we can identify that session.
• You submit a prompt. Claude kicks off a series of work on your behalf, including all tool calls, code exploration, skills loaded, MCP tools used, how it accessed them, and the results returned. We capture it all.
• Finally, wrapping up with the summary from the agent. This completes the turn.

This general pattern is applied to each Symbiont you enabled to ensure consistent, uniform collection as you switch between them. Some are also enabled for advanced capture, which leverages the agent’s transcript or hook patterns to collect things like screenshots that you’ve added or plans generated from plan mode or skills like /superpowers specs and plans. SDD gets captured here, too. No need to keep and maintain endless markdown files and artifacts in your repo. This is all stored locally in your myco project’s SQLite database and accessible via the web interface and to your agents via MCP.

Now, that’s pretty cool in and of itself, but it’s just the start. This is when myco really gets to work. In the next post, I’m going to do a deep dive on the Myco agent, which is a purpose-built agent harness that drives the intelligence cycle. The agent has specific tasks to perform. Some are as simple as setting the session title and generating a summary, and as complex as building the edges of a graph to interconnect concepts, spores, plans, and sessions. Here is a preview:

So stay tuned for the Myco Agent deep dive, followed by Teams and Collectives. Myco is in active development, so try it out for yourself. If you find a bug or have a suggestion, engage with me over on GitHub. See you there!

Originally published at https://chriskirby.net on April 16, 2026.

If you read my previous post on The Joy and Agony of Building with AI Agents, you know I’m all in on agentic workflows. Being able to architect a feature and have the agent build it is a superpower. But that was just the start.

Over the past 3+ years, I have been working with AI-generated code, and around 2 years into working with coding agents, much has changed. Capability, model quality, speed, and tooling have all improved dramatically; however, some core challenges remain, and new ones have emerged. The new challenges, especially, have been an interesting avenue of research for me.

As these tools are now geared towards professional software development within businesses and enterprises, those of us who do this for a living are rethinking everything, from how we build teams to how we budget to how we estimate to the entire software development lifecycle. When we, the humans, are no longer the ones writing the code, this fundamentally disrupts the way we’ve done these things for the past 20 years.

We have to think beyond the hyperbole and grand claims of job replacement and start thinking pragmatically. Now, we’re not going to cover the whole industry in this post, but I do want to talk about some practical ways that we can integrate agents and agentic workflows into the teams that we’re in today. And alongside them have tools that solve real problems, don’t get in the way of the rapid innovation, and genuinely offer something new and useful.

The “Groundhog Day” Problem

The most immediate friction point in this new lifecycle is what we call the “Groundhog Day” effect.

You spend an hour teaching an agent why we structure our API responses the way we do. It nods (metaphorically), writes great code, and you close the session. The next day, you spin up a new agent for a related task, only for it to completely ignore yesterday’s architectural decision. Why? Because that context vanished the moment the session ended. This is not an indictment of your prompting skills (well, mostly 😄) but rather a fundamental limitation of the technology itself.

Git captures the code, but it doesn’t capture the story. It doesn’t capture the trade-offs, the “gotchas,” or the architectural plans we discussed. We are left with a diff that lacks intention…lacks soul.

Why “Just More Prompts” Isn’t the Answer

Before building a solution, I tried to solve this manually. I maintained massive context.md and prompt.md files. I meticulously updated .cursorrules and CLAUDE.md. Asked the agent to update the docs, keep the readme current, save the plan to docs.

But here is the hard truth: If a process requires manual discipline to maintain, it will eventually fail.

In the heat of a debugging session, you stop updating the rules file. Your custom agent drifts from the actual architecture. We need something that works for us-an automated background process that brings it all together.

Enter Open Agent Kit (OAK)

I built Open Agent Kit (OAK) to be the “flight recorder” for this new era of development. Many agents, working on many things, with many developers, in a single project.

OAK sits quietly in the background while you work with tools like Claude Code, Cursor, Windsurf, Codex, OpenCode, CoPilot, or Gemini. It automatically captures the plans, decisions, and trade-offs that usually vanish. Then, crucially, it injects that context back into your future sessions…and much more.

The “Tower of Babel”: Solving for Teams

If “Groundhog Day” is the pain of working alone, the “Tower of Babel” is what happens when you bring a team into the mix.

In a modern engineering team, I might be using Claude Code to scaffold a microservice. My lead engineer is refining the frontend in Cursor. Another dev is writing tests with CoPilot. We are all committing code to Git, so the files are in sync. But the brains are not. This is not a new problem, but rather an amplified one in this new era of software development.

OAK includes backup and team sync capabilities that allow you to import session data from your teammates. This creates a form of contextual osmosis. When I synchronize and pull in the team’s session history, my local agent suddenly “knows” why you chose that specific implementation last week. It could prevent the junior dev’s agent from hallucinating a solution that breaks the senior dev’s architecture.

Privacy First: The Local Advantage

If you read my articles on Home Lab or Privacy, you know I don’t take “just send your data to the cloud” lightly. And it’s not just personally, I think businesses need to take this seriously as well. Local also helps keep costs down. My $5,000 MacBook Pro can do a lot more than browse web pages. Fully leverage your investment and save on AI API costs.

OAK is designed to run locally, per project. The daemon runs on your machine. The index, telemetry, and inteligence lives on your machine with your project. When we talk about team sync, we aren’t talking about uploading your data to a mystery SaaS API. You control the data flow.

It uses AST-aware semantic search to index your code locally. When an agent asks, “Where is the auth logic?”, OAK finds it conceptually, even if the file is named login_manager.py.

It uses local LLM providers that run open-source models, such as gpt-oss, gemma, deepseek, and qwen. Size the models for your hardware, and OAK does the rest. Inference happens in real-time while your agents are working.

Getting Started

I’m a fan of tools that are easy to deploy, upgrade, and maintain. Getting OAK running takes about 30 seconds.

1. Install the CLI. I recommend using Homebrew on a Mac, or our install scripts, which will handle and guide you through the pipx or uv install for you on Mac or Windows:

2. Initialize your project. Open your favorite terminal and navigate to your repo, and run init. This interactive mode lets you select your agents and languages. Run again any time after to adjust.

3. Launch the Dashboard. Start the daemon and pop open the UI to start working with OAK:

This takes you to the local web interface for your project, where you need to complete the final configuration step: setting up your local models. You will need something to run those models locally, and any OpenAI-compatible provider will work, though I recommend Ollama or LM Studio. Then you’ll need to pull at least one text embedding model and one general-use LLM. I highly recommend viewing the included help docs for a complete walkthrough, but a very basic setup would look like this:

OAK is now running in the background, indexing your code, and listening. The next time you fire up Claude, Cursor, OpenCode, etc, OAK will be there. Now on to the good stuff. Keep reading for a deep dive into what OAK can do today and where it’s going in the future.

Activity & Semantic search: The “Flight Recorder”

Once OAK is up and running, the Dashboard is your first stop. This gives an at-a-glance view of all OAK activity. Quick stats like Files indexed, total Memories, Session, and Plans, along with System Health and recent Session.

Search

Oak maintains a local vector database in the background, which powers our semantic search across agent sessions, memories, plans, and the current source code. All new activities processed by Oak are embedded in real time and available for you to search via the UI and the agent via the MCP server and skills. This is an incredibly fast and powerful way to get the relevant context quickly. For example, I use OAK to build OAK, so I search for “team sync” across all categories, only with high confidence.

Let’s just quickly reflect on what I just did. Now, I have over 230 agent sessions across Claude, Cursor, Codex, and others. Over 83 plans, actual planning sessions with agents that generate plans, e.g., spec-driven development. Over 5k memories, and over 500 code files. And in less than 1 second, my agent and I can get to the most relevant context and content. Then I drill in, read my plan, view the complete session that generated it, and browse to the actual code.

Now, under the hood, without getting too into the weeds, for that, jump over to GitHub, let’s talk briefly about how this content is getting created.

Code. I’m using AST-based chunking, which preserves the syntax of your code as it was meant to be understood, and combines it with vector embeddings, allowing you to search by concept rather than keywords.

Memories. These are observations Oak will make in real time using captured agent activity. e.g., your prompts, tool calls, plans, and agent responses. Then, prompting the local LLM to classify and reason about them.

Plans. Markdown plans are captured from plan mode in Claude, Windsurf, Cursor, CoPilot, and other apps that support it. OAK will store this, associate it with the agent session to link the spec to the work, and finally, with the outcome.

Sessions. OAK generates and embeds a session summary, which offers an efficient way to find relevant sessions. Sessions themselves could be long and dense, with dozens of prompts, hundreds of activities, and one or more plans. The session summary compresses all of that, and then you can drill into the details.

Sessions

This is just what it sounds like. I fired up Claud Code, gave it a prompt, and we got to work. The moment you do, OAK gets to work, recording your prompt (save all that fancy prompt engineering), all the work the agent is doing, bash, grep, sub agent exploration, file reads/edits, and finally the agent response summary when work is complete. We call that a prompt batch, which is just one chunk of work, with a session consisting of many. Sessions also have lineage. Complex work that may start with a plan, be executed by an agent team or sub-agents, and then tested and verified, can consist of many Claude code sessions. Claude itself will offer to clear context after a plan and auto-compact context, so that a fresher context can result in a new session. OAK can identify this and automatically link those sessions together. And when that can’t be detected, you can manually link them, and OAK will also suggest related sessions to link in the UI, based on conceptually similar summaries. Here is a meaty session from recent OAK work that illustrates these concepts well.

The above sessions show me working on a recent overhaul of the memory and observation system in OAK. The initial design was very useful, but also quite simple. This work was about adding the ability to “observe” whether a memory was no longer relevant or had been superseded by a new one, essentially building in some wisdom, if you will. Unlike raw history, memories should evolve; what was once true may no longer be, or we may know more now, making memories more detailed. As you can see, this was not easy, and it’s still evolving. Let’s just highlight the stats. Three Claude code sessions, 37 prompts, over 2,000 activities, and 2 plans, each built by an agent team with 5 or more agents per team. Super easy to remember, right? Oh, your team member did it? I’m sure they explained it to you 😄. OAK’s got your back.

Plans

Plan mode is awesome, and you should be using it with your agent, and if your agent doesn’t have it, switch to one that does. I would say that, for me, about two out of three sessions start in plan mode and often spawn another plan, depending on how complex the work I’m doing is. This is spec-driven development at its best when it seamlessly integrates into your natural workflow. All OAK is doing here is capturing it, associating it with the session, and embedding it for search. SDD has always lived with the code, whether it’s an RFC, a PRD, or just a really good document. However, these plans live with the context, the work, the memory, the observations. I find this to be much richer and more valuable in the long term.

Memories

The Memories interface offers a simple way to view all the observations Oak has collected over time. Gotchas, discoveries, decisions, fixes, trade-offs, and session summaries, all available. You can also permanently delete and resolve memories individually and in batches. For the most part, just a visual audit and management interface for all of the observations and content that OAK generates in the background. All of this content is also available via the search, but there are a couple of important things happening here: what you see here is everything we store in the SQLite database locally. What’s available in search is everything from the embedded database in our vector database. We do it this way so that the vector database can be rebuilt from the source of truth at any time, or whenever data becomes corrupted or lost. It’s a good idea to rebuild every once in a while to control the file size of the Chroma DB database, and it’s also how we automatically embed sessions and observations from team member files once we sync up. Tools are provided to manage all of this, and most is done automatically.

Team Sync: Building the Hive Mind

Team Sync aims to solve the “Tower of Babel” problem for teams and organizations in the agentic AI age. How do we get all of my agent sessions, context observations, and everything we’ve discussed so far into your context agent sessions and observations? Not only that, but how do we differentiate which ones came from my machine or your machine, and then synchronize them so they all play nice together locally? Well, we built a bunch of tooling 🤖.

In practice, we talk a lot about tribal knowledge in organizations, but in the context of how we’re building software today, it has a completely different meaning. Me as the developer and the leader of my own tribe. My tribe consists of an army of AI agents all doing work independently and sometimes collectively. However, I still work on a team on a project, and my team member is doing the same. We still have the code and the pull requests, and those are still incredibly valuable. However, as we’ve discussed, the way it was built, why it was built the way it was, and the problems it solved as it was being built are all incredibly valuable context for the next time you go in and work on a similar feature. And the next time might be a different team member. It might be a junior team member.

With Oak, we’ve preserved the context, we’ve preserved the why. Now, Team Sync, as it stands today, is pretty simple. We back up the SQLite database to a directory that is ideally set up with Git, then commit it. By default, this is in the same project in oak/history, or you can easily override it to a shared or more secure location. The file is named in a way that identifies it as yours, and it's tagged to the specific machine. If you use multiple machines, you'll have multiple backup files, one for each. OAK provides an interface and CI tooling to both generate those files and import them into your local database. It then embeds all the new content for indexing so it's available to you and your agents. Tribal knowledge was transferred successfully in just a couple of minutes.

Automatic backup -> project/shared directory> oak ci sync --team --include-activities

Also in the Team area is the Sharing section. Sharing came about when I wanted to show someone a session I had been working on, but since it was only local on my machine and the person wasn’t sitting next to me, I wanted an easy way to do it. Simply start sharing, and a reverse proxy tunnel is opened with cloudflared or ngrok (your choice) using a random URL, and share it with a team member. I have bigger plans for this feature in the future, but for now, it’s pretty useful as is…just don’t forget to turn it off 😉

OAK Agents: Turning Context into Action

If the Activity Dashboard is the “Flight Recorder,” then OAK Agents are the autopilot. Recording context is vital, but the real power comes when you put it to work. I didn’t just build OAK to be a librarian; I built it to be an active member of the engineering team.

OAK supports Claude Agent SDK-powered agents and autonomous tasks that can perform work in the background. Because these agents have access to the full OAK “memory index”-including context-rich automations. We can give our agents specific tools, skills, system prompts, and task prompts to perform specific, repeatable tasks that produce very high-quality results. Agents have a rich schema, a declarative manifest for building custom agent tasks, and we ship many built-in agent tasks available after initialization. By leveraging Claude Code under the hood, it uses your same subscription to perform the work. We also have experimental support for using local LLMs with the agent SDK through Ollama and LM Studio. Examples of the built-in agent tasks:

Auto-Documentation: Instead of writing CHANGELOG updates manually, an OAK agent can scan the week's changes, cross-reference them with the "intent" captured in our sessions, and generate documentation that explains why changes were made, not just what changed.

Surfacing Insights: OAK Agents can analyze the development velocity and friction points, highlighting areas where the team seems to be fighting the codebase.

This is just the start of this feature. I have many ideas and big plans. OAK agents today are already maintaining all OAK project documentation, including the Atstro documentation site. Maintaining an active, semantically rich changelog. As well as analyzing my prompt and session quality, offering suggestions and insights. But you can see the power of this. A bug hunting and fixing agent, with all of the context of OAK at its disposal, with specific tools and guard rails only possible with using the Agent SDK, and some of those hyperbolic claims get closer to reality.

The Plumbing

As I’ve been building Oak, it’s become increasingly complex. With that complexity, the drive to push for simplicity. Most of the tooling I package with OAK is meant to be used by agents and agents alone. However, there is some tooling designed for you, the developer, to ensure everything stays up to date and running. Let’s talk a little bit now about the underbelly, some of the things you’ll interact with, and what some of the things wired up behind the scenes do.

Upgrade lifecycle

Keep the package up to date: brew upgrade oak-ci . When upgraded, most functionality just works. The daemon ui will see the update and ask you to restart. You click, it starts, and you get the new stuff. When changes to the installed assets of OAK are updated, things like agent skills, configuration, etc, you run oak upgrade in your project, and OAK handles the rest. When you are working with a new agent and want to wire it up with OAK, oak init Select the agent, and then the hooks, skills, and MCP are wired up.

OAK’s MCP server

When you enable an agent like Claude or Cursor in your project with oak init OAK's MCP server is automatically configured for each agent, and it runs in the background alongside the UI and API. The MCP server has four tools:

• oak_remember - When the agent makes a decision, gotcha, discovery, etc., it chooses to preserve that in OAK. This is a valuable and frequently used tool for agents, offering rich, accurate memories.
• oak_search - searches our vector database across code and all memory categories.
• oak_context - gets memory-related information on specific files in the codebase.
• oak_resolve - new tool for resolving outdated or superseded memories, often used in combination with search

Skills

Two skills are installed by default when you initialize OAK:

1. The Codebase Intelligence Skill — An agent and user invokable skill to fully interact with the OAK platform. It knows how to work with both the SQLite and ChromaDB databases. When asking an agent about sessions, memories, and plans, the skill quickly retrieves the information and loads it into context. It’s also useful to invoke the skill yourself and just use the agent to do anything and everything you could do with the UI. /codebase-intelligence find the work we completed on the memory lifecycle feature and lets start work on adding proper lineage, mentiond as future work in the plan. Skip the token eating exploration and get to the relevant info sooner.
2. The Project Governance Skill — While OAK is the keeper of context, that doesn’t mean your project doesn’t need a strong project Constitution, aka, the rules file or system prompt. With OAK’s support for multiple agents in a single project, each with their own rules files and standards, project governance is a skill that helps you manage them all. It will build your projects oak/constitution.md and synchronize them with all of the rules files CLAUDE.md, AGENTS.md, copilot-instructions.md, etc. This works for brownfield or greenfield projects and will not replace or overwrite your rules files; it will, in fact, use that information to build your constitution. /project-governnance lets build our projects's constitution. or amending our constitution. Use project governance to add a new rule, no magic strings or numbers, we must use constants.

Wrap up and the road ahead

This has been a fun project to work on, and I plan to continue working on it. I’m also curious to hear other ideas, as I know many people are thinking about these challenges and coming up with ways to solve them. This is just my take on it. First and foremost, I built this to solve the challenges I was having. I want to use multiple agents in a project and have a way to preserve and understand all the work being done without getting in the way of the coding agent. That’s why OAK is not an agent framework. It’s not a wrapper around Claude. It simply sits beside it. How do you trust everything the agent is doing? You could review everything line by line, and I often still do. But now I think about the problem differently. The agents and the models they use are highly capable but will make mistakes, so offer them better context to help reduce them and use other agents to verify their work. We are just at the very beginning of these types of workflows. So I can’t wait to see how the tooling evolves and how we evolve with it.

There’s so much more that I didn’t cover in this already very long blog post. So come join me over on GitHub to dig in further. See you there!

Originally published at https://chriskirby.net on February 15, 2026.

Ever feel like Big Brother is lurking behind your screen? Spoiler: it probably is. It’s called Data Loss Prevention (DLP) software, and it lives on your work laptop-it’s a vital guardrail for company data. But once you step through your front door, most of that telemetry is just dead weight: scanning your network, rerouting DNS, and logging IoT devices without delivering meaningful value. Outside the office, your laptop only needs plain‑vanilla internet access. In this walkthrough, I’ll show you how to carve out a dedicated VLAN for your corporate machine-preserving the protections you need while keeping your personal network private, performant, and uncluttered.

Things you’ll need

• A WiFi router that you manage (not the thing your ISP gave you 🗑️), which supports multiple virtual networks and multiple wireless networks (SSIDs). I highly recommend a UniFi Dream Router or UniFi Express device, similar to what I’m using in the screenshots below. This setup will also work with any router with similar capabilities, such as TP-Link Omada EAP, Asus RT-AX86U, Linksys VELOP, and others, all in the $150-$300 price range.
• Your work computer, Mac or Windows PC, connected via WiFi or Ethernet.

Create your new virtual network

If your house is like most, you likely have 20, 30, or more devices connected to your home WiFi. Smart speakers, TVs, Phones, and even your kitchen appliances. Nearly all of these devices are connecting to the internet, and nearly all of them are collecting data on you. Now, I have several other posts on how to help you with that, which I’ll link below; however, it all starts with the VLAN. The best way to ensure those devices follow your rules is to first put them in the same group. Once grouped, you can set up rules (also known as policies), which control how that group can behave on your network.

In this example, I’m configuring a new virtual network in UniFi that I’ll call Work. Most settings can be left to the default, but ensure you allow internet access, and I recommend checking the isolate network option. You can always adjust your settings later if you want to customize things like your VLAN ID / Tag or Subnet, both will be important later. Settings -> Networks -> New virtual network

Optional: Create a new Zone (if using zone-based firewall)

This is a nice option if on UniFi, which makes configuring polices a bit more straightforward and offers automatic isolation from your Internal zone by default.

Add a new Wifi Network (SSID)

I create a new network and ensure that my VLAN Work is set as the default network. This ensures that any device connected to this WiFi is on the Work network. Settings -> WiFi -> Create New

Optional: route all Work internet traffic over a permanent VPN connection

This will add an additional layer of privacy and security. This may cause issues if your work device is using another VPN; if so, skip or disable the policy. Settings -> Policy Engine -> Policy based routes

That’s it for your basic network setup. Any device that is on this new network will automatically be isolated. From here, you can create more advanced policies as you get more comfortable. For example, you might restrict this WiFi and network to your work device only, or create policies that block your work device from connecting to your other home WiFi network. Policies are a powerful way to control what happens on your network, and I encourage you to learn how to leverage them.

Configure your work laptop to use your new network

There are a few things to consider here, and it may depend on the type of computer you have. I’ll break down both WiFi and wired connections (for dock users) for Mac and Windows to cover the basics.

WiFi Configuration

This is the easy one; simply connect to your new SSID, which will automatically route all traffic to your new VLAN. However, there are a few more things you should consider. When logged into a Mac with your iCloud account or a Windows computer with your work and/or personal Outlook/Office 365 account, it will save your network settings. This means your laptop may unintentionally connect back to your home WiFi. Here are some steps to check off to ensure that doesn’t happen.

Make sure to forget your home WiFi network in your WiFi settings.

Mac 

Don’t log in with your personal iCloud account on your work laptop. Now, I do this for Notes, Contacts, etc, and you may too. iCloud is very aggressive about switching network settings to “help”. If you don’t, you’re good. I would still recommend following the steps below for good measure.

OR

Log in with your personal iCloud account, or use an iCloud account associated with your work email. This feature saves all network connection credentials across devices and automatically connects to the first available one. Great for personal devices, but we don’t want this for our work laptop.

If you’re able, turn off Private WiFi Address on your new SSID Settings -> Network -> WiFi -> ... Network Settings This allows us to consistently identify this device when connected to our network.

1. Change Private Wi-Fi address to Fixed.
2. Copy the Wi-Fi address (a.k.a. MAC Address)

Windows

Similar to Mac’s private Wi-Fi address, you should turn off Random hardware addresses in Network & Internet -Wi-Fi -> Work SSID

1. Turn off Random hardware addresses
2. Copy the Physical address (MAC)

Optional: Exclude your MAC address from your home WiFi

If you made those changes and your MAC is now fixed, this is a sure-fire way to make sure you are never connected to your home WiFi.

3. Go to your WiFi settings on your router for your home network and exclude your work MAC address. Even if your laptop tries to switch, your router will deny the connection; Work WiFi, or nothing.

Wired Configuration

I always prefer to hardwire if I have the option. It’s faster and more reliable. To ensure proper isolation on a wired connection, you will need to either be directly connected to an available switch port on your router or to a managed switch that is connected to your router. Because we are using VLANS, you may need to adjust the settings on the port of your switch you are connecting to, or the port you are connected to must be configured to forward tagged network traffic. This is very easy to do on most managed switches; I’ll be showing UniFi, but the same settings will apply to others.

Dedicated port

The easiest way to configure this is to dedicate a port on our router or switch to this new VLAN you created. When configured for that VLAN, any device you connect via Ethernet to that port will automatically be on that virtual network.

• Find the port your laptop or dock is connected to. In UniFi, this is Port Manager -> Select Port
• Change the name of the port (optional, but helpful)
• In the Native VLAN dropdown, select your new Work network

Same dock, different network

I’ll offer some more advanced configurations for those that may have elevated permissions on their work laptop or perhaps share a dock and display, and want to swap between work and personal laptops on the same setup (this is what I do)

Create a new Virtual Network on your personal computer

You may not be able to change your network settings on your work computer, and even if you can, it’s not necessary. You just need to change the settings on your personal computer. If you see in the screenshot above, while we made the default VLAN ‘ Work’, we still have Allow All for other tagged VLANS. That means if your laptop is ‘tagged’ for your home network, then when you dock your personal laptop, it will be on your home network without changing anything on your work laptop, router, or switch.

Mac Configuration

1. Network Settings -> Manage Virtual Interfaces
2. ➕ New VLAN
3. Name it “Home VLAN”, Tag should match the tag you set up in one of the very first setups for your VLAN on your router, mine is 1, which is a common default.
4. The interface should be your Ethernet interface; mine is my dock, showing as USB 10/100/1G/2.5G LAN
5. Now set your service order, and move Home VLAN to the top.

Windows

Here, we’ll just use the existing adapter and tag the traffic to your home network.

1. Network & Internet -> Ethernet -> More adapter options
2. This will bring up the old control panel, because Windows.
3. Select Client for Microsoft Networks, then the Configure button
4. Advanced tab, scroll to VLAN ID, change the value to 1 (or your home network tag)

There may be other ways to do this in Windows, but this was the most direct way I could find. Once changed, your computer will request an IP from your home network instead of being on your new Work network.

Wrap up

Pretty painless, right? Now your work computer has its little corner of your home network, complete with unrestricted internet access. Great way to boost your privacy without compromising work security — everyone wins! Let me know how your setup goes.

You can use these same techniques to isolate other smart home devices. To get a more comprehensive breakdown of how you might approach that, check out my homelab guide below.

Originally published at https://chriskirby.net on August 1, 2025.

As I work on my Home Lab, various open source projects, and projects for work, I’m increasingly leveraging agentic AI tools-tools you can now interact with and act on your behalf directly inside your code editor. I primarily use Cursor and VS Code w/ Copilot, which are both developing interactive agents to improve coding productivity. Claude Code is also impressive and worth a mention as well. These agents can leverage the latest models from, Anthropic, and others to write code and execute commands directly in your code editor. In many ways, it’s the interface you are already familiar with in ChatGPT or Claude, but now, with the ability to automatically gather context from your codebase, create new files, run unit tests, anything you can do manually in your editor or via the CLI. This is incredibly powerful, amazing even…at first. Now, you can certainly “vibe” your way to something, but because we are using natural language with all of the limitations and unpredictability of LLMs, you must know what questions to ask, challenge assumptions, and define consistent context and rules to achieve better, more consistent results. In the hands of a skilled operator (or aspiring, in my case), you can genuinely create code you would feel proud to ship 🐿️. I’m still learning daily, but I wanted to stop and share some of what I’ve learned thus far in the hope that it may also help you on your journey to developing this vital new skill.

Set the ground rules

With all LLMs, your outcomes are only as good as the context you provide and the accompanying prompts or instructions. To achieve better consistency, especially with coding, it’s essential to define a set of rules that will accompany all of your requests. This is a simple markdown or text file you will add manually or configure to include automatically with every chat request. This will help establish the boundaries and the type of code you would like the agent to produce. Cursor offers a first-class feature called Rules to formalize this and even offers ways to automatically include one or more rule files in your chat session. Copilot offers some conventions for defining your prompt files as well, which can be manually included in your chat session. Simply put, LLMs have vast general knowledge but no long-term memory and minimal short-term memory; think of 10-second Tom from the movie 50 First Dates; every chat is a new introduction. “Hi, I’m Chris”. Now, the tools understand this and are getting better at solving this problem every day, but for now, this step is essential to achieving better results. Here are some of my general guidelines, along with some examples:

• Clearly define coding styles and patterns. "I prefer idiomatic C# using the latest language features", "Keep the code DRY".
• Describe the purpose of your project "To make an awesome home assistant custom integration"
• Provide repeatable instructions "Keep a rolling log of each change you make in a file called agent-changelog.md"

Here is an example of a complete global rules file I use when working on my unifi network rules custom integration for home assistant:

There is no substitute for Wisdom, yet

Like very smart and helpful people or perhaps your favorite medical practitioner, agents often focus on treating the symptom and not the root cause. This is by far the most common issue I encounter and where your experience will be leveraged the most. Perhaps you are diagnosing a bug, providing necessary context, logs, and screenshots, and doing all of the right things. However, you must stay diligent. Review the code and ensure the implementation is thorough. Challenge it. "Why are you removing x?", "What about x?". Force it to follow the rules and write better, more thoughtful code. Your best chance of that is when the context is fresh. I reject nearly as many changes as I accept, and you should, too. It's best to be clear about what you want from the start.

Avoid something like:

“help me debug this. here is the log:”

Prefer something like:

“I see we have a problem with x. Lets try to address this in a targeted way, as all other functionality is working correctly. Let’s also ensure that any changes we make are consistent with established rules and patterns. Here is the debug log to help us get started. Analyze and provide recommendations”.

The more instructions and intentions you provide, the better and more consistent the outcome.

Context is King-Give It Everything, Assume Nothing

Just like rules and prompt files can be used to establish general context, it’s vital that you consistently provide relevant context to the agent to get thorough results. Well-written code is complex and uses abstractions, libraries, APIs, and unit tests. A single feature will likely cross dozens of code files. Unless you provide those files, assume it has no clue. Thankfully, VS Code and Cursor make this incredibly easy and are actively improving the tooling for this. Within the agent chat window on the right, you can ➕ files and use syntax like @ or # to include entire folders, individual files, previous chats, and even websites. Do it every time. Missing key context will almost certainly lead to incorrect, incomplete, or duplicate code.

Keep your agent sessions small

While context is critical, as illustrated above, it’s also limited. You’ll often find diminishing returns the longer you chat, so keep each session small and focused. Once you achieve or even get close to the outcome, stop there and start a new chat. Cursor has a nice feature that will summarize your current session and add that summary as context for the new chat. This will keep your agent sessions more productive. Like a good commit or an easy-to-review pull request. This can be a fine line, so use your best judgment here. The general rule I follow here is big context, targeted ask. Avoid small context and vague asks.

Know when to fold ‘em

Agents will take you down a rabbit hole. I’ve spent hours in a single session just trying to get there. What seems like a simple ask can sometimes be 25, 50, or more steps as the agent “thinks” its way through each prompt. Cursor knows this and stops the agent at 25 steps per prompt, asking you if you would like it to continue. By the end, perhaps you can’t keep any of it. Stash it and start over. Sometimes, too much has changed and you’ve risked existing functionality, too many test are broken. I understand the desire to roll forward because things may be worth keeping. The good news is, YOUR short-term memory is outstanding, so use everything you have learned and hit that plus sign to start a new chat. It will be better this time, and you will keep things small. At the first sign of spiraling, stop it, revert, and go back to the previous prompt and change it. The tools are built in a way to manage the state for each session, so use that. Both Cursor and VS Code have chat history and record each step in the history. This has saved me a lot of time and will save time for you too.

Simple is Hard, Hard is Simple

File, project new, "Create me a new console app with an API endpoint that will summarize today's stock market data". No problem! "Add a new API endpoint to x", whole project destroyed! Boy, can AI Agents overcomplicate the most straightforward thing? You've told it not to, given it instructions, but there it goes again. For lack of a better term, it lacks elegance. Simple, clean code seems hard for it. You can get there, but you have to be very clear and hold it accountable to the rules. I hit the stop button the second it starts to deviate or overcomplicate. I'll sometimes go back and update my rules, too. Then, start again. In times like this, I find just getting in the editor myself and making the changes using inline code complete is faster. Agents aren't the tool for every problem; they can slow you down too. You know how to write clean code, so get in there and show the agent how it's done!

REVIEW, REVIEW, and REVIEW AGAIN

I treat AI-generated changes like a junior dev’s pull request. The changes are just a starting point and can often be implemented more thoughtfully. You are the senior engineer, the gatekeeper, if you will. You have the wisdom, and this is where you should apply it. Don’t wholesale accept the changes. Look at each file and each diff; it’s worth it. Reinforce your design principles, be additive, and you will get a better result than you could have achieved alone.

Final thoughts

Coding is complex, so having these incredible tools by your side is truly a shift in how things will be crafted moving forward. AI will touch every pull request, bug fix, and product release, and I say that optimistically. The more we can understand and master our tools, the more prepared and productive we will be moving forward. With that said, things are moving quickly…dare I say too quickly. Trust, but verify, has never been more apt in this context than it is today. If you are a software engineer, engineer adjacent, or a maker, this is the now and most certainly the future. I’m very interested to hear how your experience has been working with these tools. Have you tried them? Had similar experiences or learnings to me? Let me know, and have fun!

Originally published at https://chriskirby.net on March 20, 2025.

That is actually good, fast, and uses the hardware you already have; no subscription required. It’s not only comparable to ChatGPT, Claude, and Perplexity, but you can use those services as well, along with the latest local open-source models from Meta, Microsoft, Google, and others. If you are like me, you might have one or two Apple M-series Macs and maybe a gaming PC or laptop with an RTX GPU. You can use all of that hardware, that is otherwise used for work, web browsing, and games, to serve up local AI queries that can search the web, analyze images, and many more tasks you can enable or even develop yourself. These chats will be run locally, are stored locally, and never leave your home network…unless you want it to. We’ll use the very cool and rapidly improving project Open WebUI as our ChatGPT-like interface and Ollama as our model runner and local API to respond to local chat queries. I’ve been using and fine-tuning my setup for a couple of weeks now and have been having a lot of fun. I think you will, too, so let’s get into it!

We’ll cover

1. Setting up Ollama 🦙 on Mac and Windows as a service that is accessible on your local network.
2. Setting up Open WebUI in Docker 🙂 and Kubernetes via a customized Helm chart 🤓. Choose what works best for you.
3. Fully configuring Open Web UI to run local models like llama3.3, deepseek-r1, phi4, and gemma2 across multiple machines and integrating with OpenAI, Claude, Gemini, and Perplexity for a no-compromise local chat experience…for the whole family 🏠
4. Finally, can this replace my AI subscriptions? I think it could, with some considerations 💪.

Ollama as a Service

Ollama is an awesome tool that I’ve been using for quite a while now, all by itself. With Ollama, you can pull down a model that is cable of running on your computer, and start chatting directly from your favorite terminal. Ollama will load the model and recognize your computer and architecture, automatically leveraging GPU Offloading via Apple Metal or Nvidia RTX to optimize performance. It’s this functionality, along with their built-in API and your metal, that will power our local chat application.

We’ll have to enable Ollama to do two things it doesn’t do by default.

1. Run all the time in the background
2. Allow connections to its API from other machines on the local network by setting two environment variables OLLAMA_ORIGINS=”*” and OLLAMA_HOST=”0.0.0.0"

Configuring Mac M4 Mac mini

brew install ollama

nano ~/Library/LaunchAgents/com.user.ollama.plist

Configuring Windows 11 gaming rig

# install both ollama and nssm 
winget install ollama nssm

Now open your terminal as an administrator and run the remaining commands

Getting and sizing models

Mac 🖥️

If you are memory-constrained, meaning you’re on an M series machine with 8 or 16 GB of shared memory, then stick to the 3b, 7b, and 13b sized models. If you’re on an M2-M4 Mac with 24–64 GB of shared memory, then you can jump up to the higher quality models, like 27b, 30b, and even 70b, like llama3.3 which is comparable to the latest cloud versions of ChatGPT, Claude, and Gemini. From my testing on my M4 Pro, the inference speed and quality sweet spot are 14b to 27b models, like Gemma2 and phi4. I can run llama3.3:70b, thanks to my 64 gigs of RAM, but it’s slow. Nonetheless, it’s very impressive for a computer that looks like my Apple TV…. I just plan for a coffee break while waiting for a response.

ollama pull phi4
ollama pull gemma2
ollama pull qwen2.5
ollama pull llama3.3
ollama pull deepseek-r1:70b

Windows RTX 🕹️

With Windows and a dedicated graphics card, you get the benefits of much higher GPU performance, but are much more memory-constrained. From my research, you can utilize 20, 30, and 40 series cards to run local models; the later the series and the higher in that series you are, the better your results. Older cards, like a 2080 super, are going to be in the 7b range, maybe 13b depending on Vram and model quantization. Similar with the 30 series but with better overall performance. In general, the offload limit seems to be 30–34b models with a high-end card like a 3090 or a 4090 with 24 gigs of Vram. I’m testing with a 4090 with 24 gigs Vram, which performs incredibly well on models like Gemma2:27b, deepseek-r1:32b, qwen2.5:32b, and many others. Performance and responsiveness are comparable to the fastest cloud models, which is quite impressive. If I go up in model size, however, performance drops off a cliff, as work shifts to the CPU.

ollama pull gemma2:27b
ollama pull deepseek-r1:32b
ollama pull qwen2.5:32b
ollama pull codellama:34b

Deploy Open WebUI

OK, Ollama is up and running as a service on one or more machines, and now it’s time to start working with those models you downloaded. My preferred tool for doing this is Open WebUI. I came across the project recently and have been loving it. It’s under active development right now, so you and I should expect many changes to come, but I love that it is open source and is something I can contribute to. It has all of the features you would expect in ChatGPT, Claude, or Gemini, but unlike those tools, Open WebUI allows you to aggregate local and cloud models into the same environment and context. This will enable you to choose the best AI for the task at hand. Not only that but all your chats, even when using Cloud AI models, are stored locally. I’m way underselling this, so please check out their Github and the docs site …and keep reading to see it in action!

Docker

Docker is the best way to get started quickly and is well-documented on their site, but we’ll be using the Advanced configuration, which allows us to use Ollama on another computer. You can, of course, run Docker on the same computer you installed Ollama, which is how I started, and a great way to make sure everything is working and performing well.

# if my ollama service is running on 10.1.1.75
docker run -d -p 3000:8080 -e OLLAMA_BASE_URL=http://10.1.1.75 \
  -v open-webui:/app/backend/data --name open-webui \
  --restart always ghcr.io/open-webui/open-webui:main

You can also run a Pipelines container (optional), which allows for building customizable workflows, like filters and functions. You may not leverage it now, but it’s so easy to set up, so go for it. Open Web UI will automatically recognize it on startup.

docker run -d -p 9099:9099 --add-host=host.docker.internal:host-gateway \
  -v pipelines:/app/pipelines --name pipelines \
  --restart always ghcr.io/open-webui/pipelines:main

And finally, to keep everything updated.

docker run -d --name watchtower \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower -i 300 open-webui

Kubernetes

I shifted most of my homelab apps over to Kubernetes quite a while ago now, and my services run with reasonable high-availability, shared persistent volumes, and TLS termination, so this is where I put my most critical apps. We’ll have the same base functionality of the Docker setup, with quite a bit more. Open WebUI has a helm chart to get you started with some default configuration, but you can easily tweak it to your liking by passing your own custom values file.

If you’re interested in setting up your own cluster, check out this post, which walks through a basic K3s setup, and then meet back here.

I’m doing a few things with my custom values that are not enabled by default.

• I’m enabling pipelines, which will automatically install the pipelines chart as part of this release.
• I’m enabling persistent storage using my NFS provisioner. It is important to note that because Open WebUI uses SQLite as the primary database, it doesn’t play nice with some PV provisioners. NFS on my NAS was my first choice, but I also use SMB and Longhorn. When I tested those, it created locking issues with the database. You can use an external Postgres database, but migrations are not yet supported with external databases, which may change. Stick to local storage (default), a manual persistent volume, NFS, or another provider you think may work.
• I’m enabling WebSockets and Redis for caching.
• Finally, I’m setting up ingress with TLS and nginx as my reverse proxy to ensure I have secure local access through Cloudflare Warp. Open WebUI was tricky to configure behind the proxy, though I managed to get it working through some trial and error.

Optional: To create your own free certificate via Let’s Encrypt, check out my other post Migrating from Pi-hole to AdGuard home and scroll down to configuration and deployment.

kubectl create secret tls owui-tls-cert --namespace=openwebui \
  --cert=fullchain.pem --key=privkey.pemhelm repo add open-webui https://helm.openwebui.com/ helm repo update helm upgrade --install open-webui open-webui/open-webui \ --namespace openwebui --create-namespace \ --values openwebui-values.yaml

helm repo add open-webui https://helm.openwebui.com/
helm repo update
helm upgrade --install open-webui open-webui/open-webui \
  --namespace openwebui --create-namespace \
  --values openwebui-values.yaml

Configuration

Now that you are fully deployed, the configuration should be pretty straightforward. You’ve already specified your local Ollama endpoints in your Docker or Helm configuration, so those models should be connected and available after you create your admin account on your first login.

External API’s

For OpenAI, you can add your API key and the default API URL (if not already there) directly on the connections page. This will pull all models available by default unless you are using a project key on the OpenAI side, which restricts the models available to use.

For Gemini, Claude, Perplexity, Hugging Face, and others. You’ll need to use Functions or Pipelines. Essentially, Python code runs and integrates with the respective API’s. There are already commununity Fuctions avaialble to get you up and running quickly, just add your key. There are also pipeline providers, which offer very similar functionality. You’ll need API credits, and usage will vary by model, but it is generally very affordable for normal chats. Add $5 and have fun.

Web Search

You can enable this same functionality with Open WebUI, a feature you may be used to in ChatGPT and something Perpelexity does out of the box. Navigate to Admin Panel -> Settings -> Web Search and then choose your search provider and get their respective API key. I chose Brave search on their Free tier, which is perfect for my needs.

Chat Flex 💪

Now, let us have some fun with a little 1v1 chat-off.

Metal Specs:

Mac Mini M2 Pro SOC, 32GB Shared Memory
Mac Mini M4 Pro SOC, 64GB Shared Memory
AMD 9800X3d CPU, NVIDIA RTX 4090 GPU, 64GB System Mem, 24GB Video Mem

Side by side Phi4:14b (M2 Pro) vs Gemma2:27b (M4 Pro)

I just purchased a new Unifi Dream Machine Pro; help me learn how to properly set it up using best practices

Gemm2:27b is a significantly larger model and performs very well on the M4 Pro, but gotta love the speed of Phi4 on the M2 Pro, and the quality isn’t bad either.

Side by side Gemma2:27b M4 Pro vs Gemma2:27b RTX 4090

Tell me how Ollama supports GPU Offloading for improved model inference.

That RTX 4090 crushes the M4 Pro, taking less than half the time. If only it weren’t so memory-constrained…perhaps a 5090 is in my future 🏦

Side by side Claude 3.5 Sonnet vs ChatGPT 4o latest

Help me write a short blog post on the benefits of setting up my own home lab

Speed: Both were very fast, as expected. Content: I give it to Claude.

I want my $20!

If you’ve made it this far, you might wonder, do I still need my subscriptions? Honestly, not really. After all, you’re building a Home Lab, so what fun would it be to take the easy way? This is, of course, not completely free, as my M4 Pro fully loaded was quite expensive, as was my 4090 gaming rig, but I was going to buy those things anyway for my normal work and casual gaming. In fact, I was running those side-by-side queries while using the computers, so it’s not disruptive to normal usage. The APIs are also not free, but the cost structures are very reasonable (or included with your sub) if you use the right model for the job. For example, not using use o1 when mini will do, or haiku instead of sonnet or opus will matter more when using the API. Bigger models for bigger tasks and smaller ones for smaller tasks are generally a good rule of thumb. The same goes for the open-source models. If you have the compute and sometimes the patience, skip the API's altogether. There are also product features to consider, like Projects, Web Search, local app integration, and Agents. Open WebUI and open-source projects have tackled many of those, but seeing how those products evolve will be interesting and perhaps worth the subscription fee. Either way, I like keeping my chats saved locally and I like that this is all in-house, I'm sure you will too. Have fun, and let me know how it goes.

Originally published at https://chriskirby.net on January 24, 2025.

Homelab

First off, I still love and use Pi-hole, which, for now, remains part of my ad blocking and local DNS. However, it’s not without its downsides. For years, Pi-hole has been the go-to solution for network-wide ad blocking, and for good reason. It’s practical, lightweight, and easy to set up. Many articles on this site talk about the various ways I’ve used and deployed pi-hole over the years. However, as my home network becomes more complex, I continue to increase security and level up ways to configure, deploy, and maintain my home lab. Pi-hole shows its limitations when you want features like DoH and DOT locally and DoH for upstream DNS. It’s also challenging to deploy fully configured, lacks advanced filtering, and has an aging interface that could use design and performance improvements. I’ve worked around many of these challenges, however there are alternatives worth considering, and this article is about exploring and configuring one of the most popular alternatives, AdGuard home. From advanced filters to built-in parental and safe browsing controls, local and upstream DoH, and overall performance as a single Go binary, many compelling reasons exist to consider making the switch yourself. However, there were a few challenges to solve for me to consider this as a complete replacement.

We’ll cover

1. Automatically converting most, if not all, of your Pi-hole configuration to an AdGuard-supported format. Lists, Filters, and even local DNS.
2. Creating a verified TLS certificate, configuring it with AdGuard, enabling SSL web interface access, DNS over HTTPS (DoH), and DNS over TLS (DOT) locally.
3. Complete configuration via the AdGuard configuration file, allowing you to make changes and deploy them locally or from Git.
4. Deployment to Kubernetes via Helm, with a custom values file configuring and deploying all of the above.

Let’s first establish a baseline of what we must accomplish, with the underlying goal of losing no existing functionality. Check out this post as an example starting point. The tldr; network-wide ad blocking with curated and updated open source ad lists, all upstream DNS over DoH, local DNS resolution, and deployable as a container via Docker or Kubernetes.

Migration

Nearly every feature of AdGuard home can be set via their yaml-based configuration file, which I’ll reference in each area of migration below, along with new functionality. We won’t cover every feature, but I’ll call out some options to consider or chat with AI about what makes sense for your environment along the way.

First, run a Teleporter backup Settings->Teleporter->Backup on your Pi-hole instance, and then download and extract the archive. You'll need these files for some of the following migration scripts.

pi-hole-backup/
├── dnsmasq.d/
│ ├── 01-pihole.conf
│ ├── 05-pihole-custom-cname.conf
│ └── 06-rfc6761.conf
├── etc/
│ └── hosts
├── pihole-FTL.conf
├── custom.list
├── dhcp.leases
├── setupVars.conf
├── client_by_group.json
├── adlist_by_group.json
├── domainlist_by_group.json
├── client.json
├── group.json
├── domain_audit.json
├── adlist.json
├── blacklist.regex.json
├── blacklist.exact.json
├── whitelist.regex.json
└── whitelist.exact.json

Migrate Adlists

The first good news is that the lists you use for Pi-hole will work with AdGuard out of the box. Adlists will now be DNS blocklists. This is just a matter of converting from one format to another, and I used Claude to help me generate a Python script to do just that.

pip install PyYAML

python migrate_adlists_filters.py pi-hole-backup/adlist.json > filters.yaml

Alternative. You can query the gravity.db directly if you prefer: sudo sqlite3 /etc/pihole/gravity.db "SELECT domain FROM domainlist WHERE enabled = 1 AND type = 1;" > blocklist.txt

Whitelists and Blacklists

This is a little more complicated, as Pi-hole allows you to define four types of domain rules, whitelist exact & regex, and blacklist exact & regex. With regex rules, you may need to adjust some based on the complexity, as AdGuard’s interpreter may differ. This script takes all four input JSON files and outputs user_rules: yaml for your configuration file.

python migrate-domains-user-rules.py pi-hole-backup/whitelist.exact.json pi-hole-backup/whitelist.regex.json pi-hole-backup/blacklist.exact.json pi-hole-backup/blacklist.regex.json > user_rules.yaml

Local DNS resolution

I’ve relied on Pi-hole to resolve my local DNS records by creating A and CNAME records for all my homelab resources. Managing those records in AdGuard is less straightforward as it does not have first-class local DNS management like Pi-hole. With that said, we can accomplish the same thing by using the DNS rewrites rules feature. If a request comes in for mywebsite.chriskirby.net, you configure the response to be 10.100.1.45, which simulates an A host response, or it could respond with k3s.chriskirby.net, which simulates a CNAME response. The request is not sent upstream and still shows in the query log as a rewrite, not a resolved DNS entry. It's not as elegant, but it works just fine. Here is how you can convert your DNS records into the corresponding rules.

python migrate-dns.py pi-hole-backup/custom.list pi-hole-backup/dnsmasq.d/05-pihole-custom-cname.conf > dns_rewrites.yaml

DoH upstream

This one is easy and requires no special conversion. Instead of having to relay through a cloudflared proxy to ensure my upstream was encrypted, AdGuard home supports this out of the box.

upstream_dns: 
  - https://cloudflare-dns.com/dns-query 
  - https://dns.google/dns-query

For info on how to configure your network to ensure all local DNS goes through your AdGuard server and is encrypted on the way out, read: Setting up and leveling up your homelab — a comprehensive guide

Configuration and Deployment

with TLS to Kubernetes

Get your certificate

I will cover one common way to do this via Let’s Encrypt. However, there are many other ways to generate your certificate. However, using acme.sh combined with Cloudflare will do away with those annoying privacy warnings when accessing services locally over TLS, like your UDM-Pro, using the default private cert. The steps are simple, but you’ll need a few things to get started:

Get a Cloudflare API key

From your free (or paid) Cloudflare account with both DNS modify and read permissions on the Zone (domain/website) you want to use for your certificate. We’ll generate a wildcard certificate so that this certificate will work for many other services you have that support custom certificates, like your NAS, Proxmox, or Unifi. Cloudflare Dashboard -> Manage Account -> Account API Tokens

Generate with acme.sh

Install acme.sh and any dependencies you may need that aren’t included with the install script.

Install acme.sh and generate the script on a machine that is running all the time, or regularly. The created cert will be automatically renewed from the machine it was created from and is only valid for 90 days. I recommend a Proxmox container or a raspberry pi thats always running.

# Mac via homebrew 
brew install curl socat openssl coreutils

# Ubuntu or WSL 
sudo apt update && sudo apt install -y \ 
  curl socat openssl ca-certificates cron

You now have the privkey.pem and the fullchain.pem files needed for your deployment!

AdGuard configuration

We now have everything we need to complete our configuration. Here is what your complete yaml file should look like:

Shipit 🐿️

Running AdGuard in Kubernetes adds some complexity. If your home lab isn’t there yet, no worries! You can take everything you’ve done to this point and run your new AdGuard home instance via Docker or directly on Metal by following the community-supported guides. Enjoy!

If you are still here, then let’s get into it. We’ll be running some kubectl commands on our already deployed cluster and configuring our custom values for an existing open-source chart for AdGuard.

Namespace and secrets

Let’s set up our namespace and create a secret resource to store our new certificate. We’ll use that later to add it to a mounted volume for our pod in the helm deployment.

# Create the namespace 
kubectl create namespace adguard-dns 

# Create the TLS secret from your certificate files 
kubectl create secret tls adguard-tls-cert \ 
  --cert=yourdomain-cert/fullchain.pem \ 
  --key=yourdomain-cert/privkey.pem \ 
  --namespace=adguard-dns 

# Add annotation to prevent Helm from deleting the secret 
kubectl annotate secret adguard-tls-cert \ 
  --namespace=adguard-dns \ "helm.sh/resource-policy=keep"

# Add the Helm repository 
helm repo add gabe565 https://charts.gabe565.com 
helm repo update

Deploy via Helm

First, we need to create our custom values file, which allows us to override some of the default configuration options the chart provides. We can also do this via command line arguments. However, I find this method more straightforward to understand and manage. I’m adding a custom configuration for my service, using the LoadBalancer to ensure my DNS ports are accessible outside the cluster, similar to Host networking in Docker. In the persistence section, I’m using Longhorn for my storage provider and creating a custom mount for my TLS cert. Finally, I’m adding probes to ensure the pods start and remain healthy.

Deploy and re-deploy AdGuard home to your cluster.

# remove previous release, if any
helm delete adguard-home -n adguard-dns || true
      
# Wait for pods to terminate
kubectl wait --for=delete pod --selector app.kubernetes.io/name=adguard-home -n adguard-dns --timeout=30s || true
      
# remove the previous config which will be replaced by the new one
# the data pvc will remain
kubectl delete pvc -n adguard-dns adguard-home-config --force --grace-period=0 || true

# Install AdGuard Home
helm install adguard-home gabe565/adguard-home \
  --namespace adguard-dns \
  --values adguard-values.yaml \
  --set-file config=AdGuardHome.yaml \
  --set podAnnotations.recreate=$(sha256sum adguard-values.yaml | awk '{print $1}') \
  --atomic \
  --cleanup-on-fail \
  --force \
  --replace \
  --reset-values \
  --wait

Good luck, and feel free to let me know how it goes!

Originally published at https://chriskirby.net on December 20, 2024.

Unifi network traffic rules are one of the most valuable and versatile ways to manage traffic and devices on your network. It’s a feature that’s been around for a little while, and it enables you to quickly set up basic rules like blocking specific devices from accessing the internet at specific times, blocking particular domains and apps on the entire network, or even setting up speed limits on my guest network. One specific use case of interest to me right now is to help manage my kid’s screen time. My kids use many devices: phones, laptops, tablets, gaming handhelds, VR headsets, etc. There are usually ways to manage screen time on those devices individually, but it’s different for iOS, Windows, Chrome/Google, Meta, etc. Frankly, it’s too much. The common denominator is that all these devices need internet access, bringing us back to why we are here. Traffic rules will help identify and block all of those devices, even apps on those devices, but we lose some of the ease of use that many of those OS-specific screen time services provide. Services like extending screen time, temporarily disabling it, or enabling it on-demand. This is where Home Assistant (HA) comes in. Like many of you, HA is the “brains” of my smart home and where all of my other devices and sensors integrate, which makes it an ideal choice to integrate this functionally in an easy-to-use way. We’re getting into the weeds on this one, so let’s get into it!

Establishing the Rules

Let’s create a rule or two. Navigate to Unif Network -> Settings -> Security -> Traffic & Firewall, where there are two tabs: Simple and Advanced. Simple is synonymous with Traffic rules, and Advanced is synonymous with Firewall rules. Though they are different and offer different features in the user interface, they are both essentially firewall rules. The difference is important, though, as Unifi stores them differently, which will matter when it’s time to integrate with HA. From what I can gather, a traffic rule is essentially a feature-wrapped firewall rule that allows you to do additional things, like set a schedule and target specific devices without setting up Profile groups or other more advanced ways of identifying devices on the network. It’s more or less a user-friendly way to set up a rather complicated thing, which is basically why you might want to use Unifi over something like pfsense, for example.

Integrating with UDM

Currently, there is no officially supported way to integrate with most of the advanced features of Unfi devices, like my Dream Machine Pro SE. This may eventually change, given the recent announcement of an official API, but this first version focuses on integrating site manager with 3rd party applications. For now, we have to get a bit more creative and leverage some of the existing private APIs utilized by the web and mobile app interfaces we use today. I wanted to start with something simple: enable my spouse and I to quickly and easily turn the rules we’ve just established on and off. As you see above, I’m already leveraging the schedule feature of the traffic rule, which is fine most of the time, but we needed more flexibility than that. Perhaps there are exceptions; it’s the holidays, or they are on break, etc. Logging into the UDM network application, finding the rule, managing, and then pausing is fine and normal for me, but this is an interface for network administrators. And even though I know where to go and what to do, it’s far less than ideal for this type of functionality. I want Apple Home-level simplicity and the ability to set up automations and triggers. Now, let’s figure out how to do it!

To help you (and me) along, I’ve created a Bruno collection with all of the requests you’ll need to get started. Get it on GitHub.

Logging in

I’m going to log in programmatically just like the Unifi web interface logs in, by calling the private API. There are a couple of caveats to this. Typically, in a public API, I’m either assigned a token that I can use to access, or I authenticate to request and refresh a token. I do need a token here as well, but it’s stored in a cookie, and I also need to capture and send my CSRF token, which ensures my request is authentic.

First, I send a POST with my username and password in the JSON body, then I grab the cookie and the csrf-token and set them to environment variables, which I can use in subsequent requests. You'll also receive a full json payload with your user information, roles, groups, etc. Using a Local Admin account is necessary to get the required permissions to manage firewall rules. You can see here that I'm using the local account homeassistant.

Getting the Rules

This was a little harder to discover, but with some investigation using the browser development tools and the help of Claude, I found that we need two endpoints. One to pull the list of Firewall (advanced) rules, and one to get the list of Traffic (simple) rules. Here, I’m sending two separate GET requests, first pulling the csrf-token and cookie from the environment (saved from the login request) and then passing in the header. You'll receive a JSON array with each rule and its associated details.

Toggling the Rules

This one was even more challenging to discover and to get working correctly. To toggle the enabled flag on a Traffic or Firewall rule, we need to send back the entire rule, similar to what a form submission would do on a web page. So, let’s first get the individual rules to ensure we have the complete shape expected, modify the enabled property, and then post back the modified payload. Use caution here, as posting incorrect values could cause some severe issues. Here, you'll see that we have the same GET and PUT endpoint for Firewall rules and separate GET and PUT endpoints for Traffic rules, along with the full rule payload in both Toggle requests.

Now that we have proved we can modify both sets of rules via the API, it’s time to use that knowledge for home automation.

Home Assistant

HA has a rich ecosystem of integrations and components, and there are several out-of-the-box integrations for Unifi network and Unifi protect, both of which I highly recommend. In this case, I’m exposing more advanced functionality not covered by those existing extensions, which means building a new integration. More specifically, creating my own custom component. There are quite a few excellent tutorials, along with HA’s excellent developer documentation. Still, since I’m not a Python developer and we are in the AI age, I leveraged Claude and ChatGPT to scaffold out my new integration. Many, many chats later, I had something that was starting to resemble the functionality I wanted. It was a great way to get to the 90% mark faster, but I needed good old-fashioned coding and debugging skills to get that last 10%. I’ve found this typical for prototyping and building apps with AI.

This integration has been tested on my local instance of HA, is open source, and is ready for anyone else to test and contribute to. Get it on Github and soon via Home Assistant Community Store (HACS)

Configuration

Once installed, go to Devices and Services and Add Integration, select the Unifi Rule Manager, and enter your UDM’s IP address, username, and password.

Entities

Once configured, all your rules will now be available as switch entities, allowing you to toggle them on/off on demand. The integration will also look for changes every 5 minutes and pull those in as they occur.

Build a Dashboard

I love using custom dashboards in HA. They’re a great way to organize functionality around a room, topic, or set of devices. In this case, I created a new dashboard called Screen Time and will place the Traffic rules I want to toggle as big, giant buttons that are easy to use from your phone.

Wrap up

It was a non-trivial 😉 amount of work just for a few buttons, but it was a lot of fun, which is what it was all about for me. It’s working well, and I plan to keep it working as changes occur and as time allows. Good luck on your own integration and automation journey, and let me know how it goes!

Originally published at https://chriskirby.net on September 21, 2024.

Homelab

I’ve been running some form of a homelab for a long time now. From the early days of broadband, hosting my own active directory and email servers, to where I’m at today (which is quite a bit better, btw). I find owning and operating my own equipment and services to be both fun and rewarding. If you think you’re in the same camp, then you’re in the right place. I’m writing this guide to share some of the things I’ve learned, so if you’re starting out or looking for what to do next, perhaps you can grab an idea or two for your setup. I would always advise starting small, getting comfortable, and then deciding if you are ready for more.

Goals

I found it helpful first to identify what I was trying to accomplish. As a long-time software engineer, platform engineer, and engineering leader, I know certain practices and ideas have become second nature in the workplace. Ideas like the principle of least privilege and practices like Infrastructure as Code (IaC), Site Reliability Engineering (SRE), Automated Testing, and others can and probably should be applied to your personal production environment, your Home.

Better privacy

• I want better control over what data is collected about me and my family. This means first finding out what is being sent or tracked and then deciding what is acceptable and what isn’t.
• I want an easy-to-configure “whole home” VPN for devices that either can’t run a VPN locally or don’t, along with an easy way to opt-out.
• I want to ditch my cloud cameras and move to cameras that operate locally, which will give me full control over my live feeds, recordings, and integrations.

Better security

• I want to isolate connected devices (IoT), such as smart speakers, smart appliances, thermostats, TVs, etc., from communicating with the other trusted devices on my network unless expressly allowed. If one of these devices, which I do not control, were to be compromised, I would like to minimize what a potential bad actor could access. This is often a best practice recommended by security professionals and even the FBI.
• I want to limit what guests can do on my network. Anyone who does not live here 24/7, does not need forever and unfettered access to my network. No more sharing the Wi-Fi password with extended family, friends, or house guests.
• I want a network firewall that offers packet inspection, intrusion prevention, and other security and network features not found in typical consumer wifi routers or the junk most ISPs give you.

Better remote access

• Once I set all of these services up, I want an easy way to access them. One of the first devices I purchased was a Synology NAS, which has been rock solid for me. There are a few ways to connect to it remotely, the main one being QuickConnect. I won’t get into how it works, but it has and does work fine; however, I want one way to access everything, including my NAS.
• I want remote access to be simple and work on every device I own or have access to.
• I want to avoid traditional VPN servers with broad network access when accessing the individual app or service will suffice without compromising security.

Such simple goals-no problem! Now, let’s take a look at some of the choices I made to accomplish these goals.

Network

It all starts here, and it’s easier than you think

I’ve gone through many iterations over the years. My first “prosumer” router/firewall was a Sonicwall appliance. It was relatively easy to use, but was expensive, slow, and had subscription and add-on fees for more advanced features. Then I tried pfsense, and OPNsense, for a while, running on dedicated hardware, which is good but has a fairly high learning curve and had some strange limitations that ultimately caused me to move on to something else. Finally, I found the ubiquiti edgerouter, which was the perfect balance of cost and functionality…which eventually became unsupported in favor of the new, far superior, Unifi Dream Machine SE, which is where I’m at today. Here’s some gear to consider then we’ll get into some configuration.

• Dream Machine. This is the centerpiece and will manage the rest of your gear. If you have fiber, then go with the PRO series, as you’ll want the IPS routing speed to be at or greater than your connection speed. I currently have a 2.5GPS fiber connection and Starlink as a backup, which my PRO SE more than handles. How many devices you buy and adopt are also a factor here, so consider your future growth plans and size accordingly. The Dream Router and Unifi Express are great options for smaller setups especially if you are space-constrained.
• Rack switching. There are so many things to consider here. I have a mix of 2.5GB, 1GB, 1GB PoE++, and 10GB network devices, spread across many floors, inside and outside. I started with a single PoE Pro series switch, which is still in use, and am currently expanding to the Pro Max switches with etherlighting. Given the investment, I would size up a bit if you can spend the money.
• Utility switching. I hard-wire everything I can. It’s more reliable, not subject to (most) interference, and I like to make and run cables. I use a mix of the Flex (PoE++ powered & passthrough), Flex mini (PoE powered), Lite PoE (PoE+), and the new Ultra line. Overall, I prefer PoE powered and passthrough switches so that all of the power comes from the central rack, which is easier to manage in power outages and understand my overall power consumption.
• Wi-FI. The Unifi access points are powerful, so if your in a new-ish home, no need to overdo it, one or two access points will do. If, like me, you are in an old home with plaster and lathe, then you may need a lot more. I’m currently using a mix of the U6 gear and will likely leap to U7 gear at some point. Just know that U7, not only is it very new with little device support, but you’ll also want 2.5G PoE uplinks and at least a 2.5G internet connection to really take advantage. If that is not you, then a U6 Pro or a U6 Long range are great starting points. If that doesn’t cover it, then consider adding more coverage through smaller U6+ APs. If you can’t hardwire and need to Mesh, then I love the U6 Mesh. I use two inside, where ceiling mounting is not an option (still use PoE, but not necessary), and one outside for backyard coverage. Always hardwire the backhaul if you can.
• Cameras. You’ve come this far, so why not go all in? The Protect cameras are amazing, as is the software. Most can be powered via PoE and are managed with your Dream Machine or if you’re like me and want more storage retention and protection from drive failure, a dedicated NVR. My goal was to move away from cloud cameras, so this was an easy choice.

VLANS!

An advanced and sometimes confusing, essential part of your homelab. Most consumer routers typically have one LAN, like 192.168.1.0/24. One LAN means all devices connected to your WiFi will all be on the same network talking to each other. To accomplish my privacy and security goals, I needed multiple LANs and multiple WiFI networks, so it was time to make the leap into virtual local area networks. I say leap because once you start putting devices on different networks that do need to talk to each other, like your Hue hub and your phone for example, it no longer works without some new firewall rules and profiles you will have to create. It’s going to require a little bit of work and trial and error, but it’s worth it. I’m not the best person to walk you through this, so instead, I will point you to the resources I used in setting up my VLANs. Check out VLANs made easy and Secure IoT Network configuration, as you’ll need this knowledge to keep everything working together correctly. Once done, you may want a similar setup to mine:

• Default — the LAN you first set up with your router, is now my trusted device network where all of my family’s personal devices are connected and has a dedicated WiFI SSID.
• IoT — my first VLAN created for all “smart” devices on my network that require internet access and are not personal devices. Devices on this network are not permitted to communicate with any device on the Default network, but are allowed to communicate with other devices on the IoT network. This also has a dedicated SSID, so anything joining that WiFI SSID will be on the IoT network.
• Guest — a network dedicated for people who need temporary access, like house guests, friends, etc. Devices on this network can access the internet, cannot access any other networks, and can not access or see any other device on the guest network (device isolation). A dedicated and unencrypted WiFI SSID controls access to this network with a hotspot landing page, where you enter a password and accept terms, similar to a coffee shop or a hotel. After 24 hours access is automatically removed.
• Secure — a network similar to the Default network, but all internet access flows through an always-on Proton VPN tunnel. Once connected via a dedicated WiFI SSID, all traffic is secure, and no VPN app is required.
• Homelab — a network dedicated to hardware and services that I host within my homelab. Devices on this network have full access to the internet and can talk to other networks. I created this primarily to get a dedicated pool of IP addresses, so I have plenty of room to expand. I’m slightly less concerned about isolation between this and my default and IoT network. For example, Home Assistant lives on Homelab and interacts with select devices in IoT and Default, and that’s what I need it to do. No WiFI SSID is associated with this network, as everything is connected via Cat-6.

VLAN Considerations

• For AirPlay, Chromecast, and similar devices on separate VLANs, enable IGMP Snooping and mDNS (bonjour) to ensure multicast works properly. If you are still having difficulty, you may want to specify LAN IN firewall rules based on the service network/default/settings/security/firewall-rules.
• Sonos with VLANS. Many have tried, many have failed. The tldr; is that Sonos does not play well with VLANs. Check r/sonos and r/UNIFI for the latest; however, I recommend leaving your speakers on Default to save yourself the headache.

Firewall Rules & Profiles

The videos I reference above cover many of the basics, but I’ll cover some of them here as well since they are essential for your initial setup. Once you start putting devices, like your Hue bridge for example, on your IoT network, you’ll still want access from your personal devices in order to maintain the functionality you are used to. This will get you started.

Create a new IP Group Profile called Private Local Networks network/default/settings/profiles/port-ip-groups and add the following:

• 192.168.0.0/16
• 10.0.0.0/8
• 172.16.0.0/12

Create a new LAN in firewall rule called Allow established and related. This rule essentially allows devices on other VLANs to “talk back” if established on the Default network, but devices on the VLAN cannot initiate a connection to the Default network.

Create a new LAN in firewall rule called Allow LAN to anywhere. This rule allows devices on the Default network to communicate with devices on any VLAN.

This is just the start and we’ll cover more rules when I talk about services, like DNS, further down.

Storage

Your personal cloud storage for videos, photos, and backups

Resilient, high capacity, shared storage was at the top of my list, as it’s central to achieving all my homelab goals. There are so many ways to approach this, however I will keep my recommendations simple here. Get a dedicated network-attached storage (NAS) device, add some Western Digitial Red drives, set up some shares, and now you’ve got plenty of storage accessible by any device on your network to store your photos, movies, backups, and more. I highly recommend Synology, as it’s easy to configure, has a full suite of out-of-the-box and community software (photos, video, docker), you can expand your storage over time using their proprietary raid format (saving big money), and they seem to last damn near forever. I have two 4-bay NAS devices from them and my first one is still running on the original drives for 10 years now and counting (still gets security updates but no new features). Going on 4 years for my second NAS. If you don’t want a dedicated appliance and feel like rolling your own, then it’s TrueNAS. Powerful, flexible, and based on the hardware you have or buy, you could run your entire homelab in it with its equally expansive 3rd party app support.

Considerations

• Hard drives can fail, especially if you are not using ones designed for 24/7 operation. Multiple drives in a RAID or ZFS configuration are a must if your data is to survive.
• Backup your must-not-lose data to the cloud on a regular schedule. Synology has an app called Hyper-Backup that allows you to select files and folders, encrypt them, and then send them to a cloud provider like Azure Blob Storage, AWS Glacier, Dropbox, and many others. It’s cost-effective and will provide you with some peace of mind.
• A dedicated appliance can also host services like Plex, Pi-Hole, and Docker, as discussed below. Note that these devices are very constrained in terms of memory and compute power and lack dedicated GPUs for transcoding. Consider what your plans are for this device and shop accordingly. The higher desktop and rack-mounted Synology models pack considerably more computing, have memory expansion and high-speed networking…and are considerably more expensive. For me, it’s storage, backup, light media and containers, and that’s it. It keeps my costs down and gets me exactly what I want from a device like this.

Taking up space

Time to get the tools out and install some stuff

Homelabs come in all shapes and sizes. For me, it started as an old Dell Windows desktop and a Raspberry Pi and then moved to a 42u rack with networking, storage, IoT, and mini-PCs. Budget, space, power, and climate are factors I would consider when approaching this, but this is what’s worked for me.

Rack mounting

Rack everything that can be racked. It’s a universal standard for networking equipment, servers, along with shelves, storage, and so much more. I have two racks in two separate locations. one 42u rack, which I consider the homelab and where the majority of devices are, and I have a 25u rack in my office, which keeps my office networking, receiver, and game consoles (you can rack those).

• StarTech open rack. I rack gear on the front and the back, as you can control the depth, and it’s affordable. It’s also easy to keep cool, and I still have a bit more room for future expansion.
• StarTech shelves. These are for anything you can’t rack, like your NAS, your Starlink router, mini-pc’s, etc. I have many of these and I love them. I recommend the 2u for heavy stuff and the 1u for the small and light stuff. There is no need to take up more space than you need.
• Rack Studs. Forget the nuts and screws, Rack Studs all the way. You will thank me…and them for making such an awesome thing.
• Rack mounted PDUs. I use these, as well as Unifi’s power gear, but they are a cost-effective way to get started with power management.
• Slim Cat-6 patch cables. I LOVE these, and they can also handle PoE (it varies by brand). They are much easier to manipulate and cable manage and come in all sizes. I make a lot of my own cable as well, but I use these on the rack.
• Rack patch panels. You can buy them with the inline keystones or by the panel and keystones separately; it just depends on what you want to do. I have some patch panels with inline keystones and some blank panels. I love the blank ones for putting in a mix of USB, HDMI, and Fiber keystones for easy connectivity to rack-mounted gear.

Metal

You’ll need some metal to run your local data center properly. My current setup relies on mini-PCs and a few Raspberry Pi 4s. They are inexpensive, cool and quiet, and power efficient. I’m not trying to be a data center; I’m just trying to block some ads. There are quite a few choices here, and they do matter based on your plan. I suggest keeping it simple, though I rarely follow my own advice 🤓.

• MINISFORUM PC. I only have one, and it hosts many of my more resource-intensive services. There are lots of sizes and shapes, but if you want a mini-PC with a discrete GPU, more CPU and RAM, and 2.5G networking, then look no further. I love it and will buy more when I need to expand.
• Beelink Mini PC. I bought three of these, primarily to serve as my K3s control-plane nodes. They are very inexpensive, have some expandability, and have dual 2.5G networking-a perfect combo for me. Three of these cost as much as one of the MINISFORUM. For me, these are about introducing some physical High Availability, not about the muscle.
• Rack-mounted Raspberry Pi 4’s, with SSD’s and PoE hats. I love Raspberry Pi’s, they have amazing utility. They aren’t the device to do anything substantial, but for services like DNS, reverse-proxy tunnels, cron jobs, they are perfect. They run on 5W of PoE each and are an indispensable part of my homelab.

Virtualization with Proxmox

Bring the cloud to your homelab

It’s time to get into some software. I will keep this simple. Other than my PIs, I don’t run any services on the metal directly. Server management is hard and can get very enterprizey very quickly. Hardware management is virtual now, we spin up a new VM or service in Azure or AWS and delete it when we’re done. It should still be that easy at home, so let’s discuss how we can get close to that. This will get you started, but there is much more to delve into as you get comfortable.

Other than the Pis, if it’s running in my homelab, then it’s running on Proxmox VE. Proxmox not only makes hardware management easy through its easy-to-use UI and terminal but also supports clustering and high availability out of the box. I won’t list all the features here; know it’s free to use, supports near-native performance VMs and Linux containers, and runs on almost anything. There is an excellent support community, which I contribute to, and has helped me out more than a few times. I’ve used Proxmox VE for many years, and I expect many more years to come…don’t homelab without it.

Proxmox VE helper scripts. An assortment of scripts to help you automate and manage Proxmox. Along with some useful scripts to help you set up your services in Proxmox containers. Thanks for the tip Andy!

Volumes and backup

Using your NAS as a primary storage device for Proxmox is a great way to get started. First, add a volume share to Proxmox using NFS: Datacenter -> Storage -> Add -> NFS. This is now shared with every node in your cluster and can be used to store your virtual disks, backups, and ISO images. It is network-attached storage, so it will be a bit slower (1G fine, 2.5G better). However, you get the full resiliency of your NAS to protect from data loss. Unless disk latency is paramount, consider this as a good option for all of the above. For everything else, a local volume running on an SSD with regular backups to the NAS.

Networking

One of my favorite features of Proxmox is the software-defined network. In these screenshots, you can see that I have two bridge networks defined on the host bound to the physical network devices: vmbr0 (bridge) to enp1s0 (nic) and vmbr1 to enp2s0 and I've given the bridge a static IP on the homelab network. Now see my homebridge container, which has two virtual network interfaces, one on the default VLAN (homelab) and one on a separate VLAN (110 aka IoT). Both interfaces use the vmbr0 bridge, which is assigned to only one physical nic. This allows homebridge to easily discover devices within the IoT network while existing and being managed on the homelab network over a single physical device. I use a similar configuration for Home Assistant. Overall, it is more flexible than using port profiles and attempting this same configuration on my managed switches. Sometimes, what should work doesn't, so this is a clean way to cut through that. I find it best to keep the configuration close to the implementation.

Cloning

This feature can be your best friend when setting up multiple VMs of the same type or having a ready-to-go Ubuntu VM fully updated with your SSH key to save you time. Set up your VM in the usual way and get it all configured, then right-click the VM and select Clone. This is a massive time saver and worth mentioning.

Kubernetes

Containerize your homelab

Proxmox is up and running, managing the metal and some key services, so it’s a solid foundation for the next layer. With Kubernetes, we have a fully managed way to host services that are resilient, auto-scale, and easy to manage and deploy with Infrastructure as Code (IaC) tooling like Terraform and Helm. This is where things really get fun. So let’s set up a cluster and get things ready to deploy some homelab essentials. I highly recommend running k3s in your homelab, as it’s a certified Kubernetes distribution with a single binary and can run on a wide variety of devices.

Rather than repeat myself, I have a good setup guide in another post. I discuss how to get your k3s cluster up and running, along with setting up kube-vip, which I recommend you do as well. For each node in your cluster, I recommend three Proxmox VMs running the latest LTS release of Ubuntu server.

Highly available Pi-hole setup in Kubernetes with secure DNS over HTTPS DoH

Recommended Addons and Tools

• kube-vip — Adds high availability to your cluster through a virtual IP (VIP) and control-plane and service load balancing. Use their Helm chart to deploy or via kubectl to apply directly.
• longhorn — Adds highly available distributed block storage to your cluster. A great way to add persistent storage to your cluster, along with regular volume backups. This has saved me more than a few times and gives me confidence when doing some basic maintenance.
• nginx — k3s ships with traefik, which works well, however some may prefer or be used to nginx. Many helm charts ship with annotations for nginx, so you may just want the option and have both.
• Kubernetes dashboard — A nice web interface for managing your cluster, with your cluster.
• Lens — The best way to manage your cluster. It’s free for personal use and will help you better understand Kubernetes and well as easily maintain your cluster. Absolutely indispensable for me and probably wouldn’t continue running Kubernetes in my homelab without it.
• Warp — The best terminal for Mac, Linux, and now Windows.
• CLI Tools — brew install kubernetes-cli helm

Services

Deploy, configure, get your homelab up and running

We’ve now covered how I organize, host, and run my devices, which is ever-evolving. Now let’s go through what I run in my homelab to bring it all together.

Secure DNS with Pi-Hole

Basic privacy starts with DNS. It is such a simple thing yet it has quite a bit of complexity. DNS is an OG internet protocol and service that has received many privacy-related upgrades over the years; however, backward compatibility remains. By hosting your own, you get the best of both: maximum compatibility with the latest security.

First, decide how you want to run Pi-Hole. There are so many ways, and I’ve probably done all of them. I started with a single Raspberry Pi until the SD card failed…which took down the “internet.” If I was going to do this, then I needed to do this. It should be highly available, to make it hard to kill, along with faster and resilient storage, making it hard to break (sounds like a 90’s Segal or Van Damme movie 🥷). I have several other posts on this as I progressed in my journey; check these out as they cover the majority of my setup. Once back, let’s get into some firewall rules to round things out.

Highly available Pi-hole setup with secure DNS queries to Cloudflare

Highly available Pi-hole setup in Kubernetes with secure DNS over HTTPS DoH

Load balanced and highly available local DNS with DNSDist and Keepalived

Ok, so Pi-Hole is up and running, is highly available, and is resilient. Now I want to ensure every device on my network can only use Pi-Hole to resolve DNS queries. Now this is a little difficult. Devices can set their own DNS servers, even when using DHCP. Certain devices from Amazon, Apple, and others are especially disobedient and will either try to force 1.1.1.1 or even a public DoH address. My solution is a set of firewall rules to drop the DNS requests that misbehave. No Pi-Hole, no internet. It's not perfect, especially with DoH, as they just look like normal 443 traffic, but there are ways, and this will get you started.

VLAN access to Pi-Hole

Make sure your devices on other VLANs can reach your Pi-Hole servers. First create a Profile IP Group Pi-Hole DNS Servers and enter the IP addresses of each server. Then create two additional Port Groups: one to define the DNS Ports called DNS, and one to define DNS DoH ports called TLS-DoH (you’ll use this later). Finally, create the LAN In rule to allow devices on your VLAN to access Pi-Hole DNS on any other VLAN called Allow IoT Pi-Hole DNS.

Block 3rd Party DNS

Now, it’s time to block access to all DNS requests that attempt to circumvent Pi-Hole. As I stated above, these settings can be manually changed; some devices ignore your settings and use their own, and some devices and browsers use DNS over HTTPS or DoH, by default. DoH is great, and how I resolve any queries that come through Pi-Hole, through providers I trust with rules I maintain. Here’s what we can do to block the ones we don’t.

Create two new Profile IP Groups containing the list of public DNS DoH providers, Public-DNS-IPv4 and Public-DNS-IPv6. I’ve created a Gist below to help get you started. This will cover the main public providers, and I provide a few links in the comments of the Gist for lesser-known providers you may want to add for good measure. For reference, I have about 200 IP4 and 55 IP6 addresses in my lists and counting.

Now create some new Internet firewall rules that will allow us to access public DoH servers from our Pi-Holes and not anywhere else. Create two new Internet Out rules to Accept all DNS traffic from Pi-Hole servers and two new Internet Out rules that Drop all other DNS traffic from non-Pi-Hole servers. The Accept rules should be above the Drop rules; order matters.

Remote Access with Cloudflare ZeroTrust

I love Cloudflare ZeroTrust, so much so, that I’ve already written several posts on my journey. Check those out first, then come back for some new tips and changes since then.

Replace your Homelab VPN with Cloudflare Zero Trust

Use your domain with Cloudflare to securely access services on your home network

Load balanced highly available Cloudflare tunnels with Docker Swarm

Through those articles, you’ve seen how to deploy cloudflared tunnels to your Kubernetes cluster, leverage your local Pi-Hole DNS servers via the Warp client split tunnels, and use your own domain with TLS termination to access all of your services remotely and securely-very cool stuff. By now, you’ve guessed that I’m a fan of making my services highly available. Here are some things you can do just to add a bit more resiliency to your homelab.

Run additional cloudflared tunnel containers on your NAS

Maybe your k3s cluster is down, or maybe you’re doing some maintenance, but why not have a few extra tunnels running just in case? Running lightweight containers on your always on NAS is a simple way to add some additional piece of mind. Create a new tunnel in your ZeroTrust dashboard Network -> Tunnels. Once created, you can create as many instances of the tunnel as you want to. For this tunnel, I’m setting up several of my local VLAN routes, to ensure I always have remote, VPN style, access to my network with the Warp client. If my k3s tunnels fail, and I lose public app access, I’ll still have local network access through this set of tunnels running on separate metal.

Terraform your ZeroTrust configuration

Click-ops is a fine practice for getting up and running, however, I prefer the IaC approach. Terraform is easy to use and, with the help of ChatGPT, easy to get started with your configuration. Here is a snapshot of the Terraform to see how straightforward it is using the Cloudflare Terraform provider. If anyone is interested in the code, perhaps I’ll throw it up on Github, let me know.

Home Automation with Home Assistant

The ultimate automation services for everything in your smart home. I integrate my home solar and storage, all of my lighting, locks, Unifi network and camera, and even some custom integrations I created myself. The community for HA is awesome, which will make getting started very easy. I recommend installing via one of the Proxmox scripts here. I’m currently using the VM script, which I find the most flexible as I need to pass through several physical USB devices, like Zigbee, Z-Wave, and Bluetooth antennas. I would recommend a good amount of CPU cores and a healthy amount of RAM if you are a heavy user like me. You’ll also notice that I have several network adapters, to help with device discovery on separate VLANs.

HACS

The Home Assistant Community Store (HACS) is a must-have once you’re up and running. The officially supported add-ons are essential. However, there are a few blind spots. I use some community integrations for my Govee lights and many others.

Homekit integration with Homebridge

If you are a HomePod/Homekit family, then Homebridge is a must-have addition to your homelab. Homebridge acts as an unofficial bridge that can be added as a device to your Apple Home ecosystem and allows you to bring smart devices that are not officially supported to Homekit. This allows me to reliably control Switchbot, Elgato lights, LG TV, and a few others. It is very well suited to host on a lightweight Proxmox LXC container. Here are some snapshots of my Proxmox config, homebridge dashboard, and the Apple Home app on my phone showing the integration.

Cameras with Scrypted

Forget the integrations for Home Assistant and Homebridge for your Unifi, Nest, Ring, etc cameras; this is what you want. Scrypted pulls the RTSPS streams from my cameras, and then rebroadcasts the feeds to Homekit. Once my Protect cameras are integrated with Scrypted via their Unifi plugin (you’ll set up a special local login on your console), I simply enable the Homekit plugin on each Camera, and then I can Scan and add the camera like any other Apple Home accessory. This enables things like Apple TV, phone, and watch popups and video notifications from my G4 Doorbell Pro, as if it was all meant to work together. You can even enable recording for people and package detection, as Unifi’s AI detection does not natively work with Apple. This project is just awesome. They also have an excellent paid NVR service, which if you’re not using a local NVR like me, will give you similar functionality.

Deep cut, Koushik Dutta (koush) is the developer and I used to use his Android ROM’s and tools back in the day. Still killing it!

Hosting with a Proxmox container is the recommended way to run Scrypted, and they provide an install script that will also enable hardware encoding support for your camera streams. This one runs on my MINISFORUM mini PC, with dedicated graphics and it works very well. This will consume a decent amount of CPU, so make sure you run this on something that can handle it.

Media with Plex

Plex needs no introduction. I need a seamless way to stream all of it at home and when I’m away, and there is no better way than Plex. By itself, Plex is pretty great. It will run on an old Windows machine with a big hard drive just fine…which is exactly how I used to do it. As you’ve seen by now, we can do much better than that. First, I don’t need UPNP or port forwarding for Plex, It’s a configured app with Cloudflare ZeroTrust, which is how I access it remotely. Second, I keep all of my media on my two NAS devices, which are locally resilient and backed up to the cloud every night. Finally, I have Proxmox to host my server in an LXC container with full hardware acceleration support.

Install and configure

Start with this handy script to install Plex on one of your Proxmox nodes. Don’t overthink the resource allocation, as you can always just allocate it later. If you need frequent transcoding, then you’ll need to allocate a larger amount of resources. However, if you direct play most of your content, it will use very little CPU. Plex does like RAM, so be more generous there.

Mount your NFS shares to Plex

SSH into your new Plex server or open the Console in the Proxmox web interface. From there install NFS support sudo apt install nfs-common and then edit your /etc/fstab file sudo nano /etc/fstab and add entries to mount your NFS shares.

Conclusion

All posts must end

There’s more, but this post is long enough 😀. It was fun to write, and I hope it helps you with your own homelab or inspires you to start one. Good luck, and feel free to reach out and let me know how it goes!

Originally published at https://chriskirby.net on July 26, 2024.

I hope to convince you that good personal online privacy and security is essential, accessible, and works on any budget. I was inspired by several friends and colleagues of mine who are still not managing their secrets (passwords, pins, account information, etc) securely and often don’t consider how their activity is being logged, tracked, and sold online. I want to help them and you with some great options that I use personally, for work, and for my home network that I believe is accessible to anyone, no matter your technical prowess.

Consider that all of the emails and passwords you’ve used over the years are in dozens, possibly hundreds, of databases available to online marketing companies and to those with less legitimate intentions. These companies are often called data brokers, a business-sounding way of saying they have your information, likely without your knowledge, and it’s for sale. Yes, you can ask them to remove it, and some companies offer to do this for you for a fee; however, whether they comply is voluntary. Even if they remove your data, it will likely reappear. How? past and future data breaches, from banks you’ve used, to retailers you shop at, or to some website you were on ten years ago. Data breaches are unfortunate and beyond our control, but some of the data we provide to each site, company, bank, etc, IS. It’s never too late, so let’s get started.

Upgrade your security; it’s time for a password manager

I’m not talking about the popup in Safari or your browser of choice that offers to save and sometimes generates a password for you. We can do much better than that. The term password manager doesn’t do it justice; it’s a secure vault for all of your secrets, meaning the things that are private or personal to you, an email and password to log in to your bank, a PIN for a debit card, or the actual debit card information itself. Essentially, it is anything you would keep in your wallet, bag, a post-it note, or commit to memory.

1Password — security for everyone

I’m a longtime personal and family customer, and I believe there is no better product on the market. They don’t pay me to say that, though they are welcome to if they read this :) We’re talking $3/month, and you’ll make a giant leap towards better security. My kids have been using 1Password before they had phones because family doesn’t let family use the same password for both Xbox and Discord. They also store their SSN’s, ID’s, and soon credit cards and bank information all in one place. Need a copy of your birth certificate, np, it’s in 1Password. Driver’s license, covered. Your crypto wallet? yeah, I still have a few of those. It’s my digital wallet, and it’s indispensable. You’ll need to create one more new password that you will remember, but that will be the last. I recommend a long phrase, sentence, or several random words; most importantly, make it unique. 1Password will also be secured with your Face ID, Touch ID, Windows Hello, or any biometric system your phone or computer uses, making it even more secure and easier to use at the same time.

Once installed on all of your devices, 1Password can:

• Create new credentials and Fill in your existing ones automatically in any web browser, phone app, or desktop app.
• Manage passwordless sign-in automatically, like passkeys now used by Google, Apple, and others. (passwords are antiquated and will soon be gone for good)
• Manage your 2-factor codes, no more separate apps or losing account access when you get a new phone or forget which app you used.
• Automatically scan and notify you if you have credentials that have been compromised due to a data breach
• Manage your travel, insurance, and identity documents (and more) in one place.
• If you’re a network, software, or platform engineer, it will also manage your SSH keys via its built-in SSH agent.

Upgrade your online privacy; it’s time to part ways with Gmail

You have a Gmail account, an Outlook account, or an iCloud account, just like I do. They are nice services, with nice apps to go along with them. They throw in online file storage and sharing, shared calendars, and other helpful stuff. oh, and they also scan your emails, data, and activity and sell it to advertisers, all outlined in their privacy policy. Google is an ad company, after all. and hey, it’s free, right? Marketers already know enough about me from what I choose to buy and the rewards cards I’m obligated to use lest I pay 30% more at Kroger or CVS…all in the name of data collection. Let’s make it a bit harder for the rest, shall we? Convenience and privacy are not mutually exclusive; there’s a better way.

Proton — digital privacy for everyone

I don’t internet without it! I’ve been a customer since their crowdfunding days many years ago, and it’s only gotten better over time. This is your one-stop shop replacement for many services Google, Microsoft, and Apple provide. And guess what? You can also start for Free, so there is no reason not to. Their services include a very fast and secure VPN, Mail, Calendar, Drive (files), and their new password manager, which would be my second choice after 1Password (perhaps not for long). Moving to paid is worth it, as it gets you more storage, a faster VPN, and more customization and features for each product, all for $10/month. They offer family plans, too…yes, I made my kids use Proton as well 😄. Proton is also based in Switzerland, which has some of the strictest privacy laws in the world.

Mail & Calendar

First, sign up and pick a username, which is your new default email address (username@proton.me). If you decide to pay, you can also use your custom domain (e.g. myname.com). Ok, now the fun part: this is not the email address you will give out! Proton has a built-in ability to create new email aliases in the desktop app or via Proton Pass. What is that? This is a unique email address that will be forwarded to your main address. Why? this allows you to use a unique email for every account, newsletter, and rewards program you have. So? well, those data breaches I mentioned earlier, if your info gets exposed, the email they will get is unique for that service. This does not make it impossible to identify you; it just makes it much harder. If you want to stop spam from a certain site that makes it hard to unsubscribe, kill the alias, and that email address will no longer work. You can’t spam someone with a bad email address. Proton Mail has so many other features that you’ll already be familiar with from other email providers, and some new ones.

Switch checklist:

✅ Forward new Gmail, Outlook, etc. messages to Proton Mail. Login to your email and go to settings / all settings. You’ll find something like Forwarding. Enable that and have it forward all messages to your new email address or alias

✅ Import all existing messages from your current email provider. Proton’s Easy Switch feature makes this easy. Go to your settings in Proton and select import via Easy Switch. Then follow the instructions. Once imported, you can safely delete them from your old provider.

✅ Create your first alias in the Proton Mail app.

Files and Documents

Google Drive is convenient, but you give up a lot for using its free or paid personal services. First and foremost, it scans all of your files, and if you share them publicly, it examines their contents. It also offers encryption; however, like many cloud providers, it has all the keys. Think of it like the landlord in your apartment building. You have a key to your door, but so do they. We have a right to privacy, no matter how innocent or mundane the content is. If I’ve convinced you, the next step is as easy as the first: use Proton Drive. Your files are just as easy to access and share, with one major difference: they are end-to-end encrypted. No one can access those files except you and those you share them with, not even Proton. Something you probably thought was already true, but now you know.

VPN

I’m sure you’ve seen ads for VPNs; they are popular, especially on social media and YouTube. VPNs are an essential part of protecting your online privacy. However, not all VPNs are created equal. You’ll want a VPN that works on every platform, is reliable, has global coverage, and, most importantly, has a strict no-log policy. Proton VPN’s free tier meets all of those criteria, and it just gets better from there as you move to a paid tier. You can use a VPN in many ways, but I think for most people, having it on your phone and your laptop for casual browsing or when using public wifi will cover most of your privacy needs. It also comes in handy for watching streaming content from other countries 💻 . If you opt for the Ultimate sub, you’ll get faster connection options and more privacy through the Secure Core feature (Tor).

Upgrade your WiFi

Your ISP knows you well, very well, in fact, since they often supply the hardware you use to access the Internet along with their own DNS servers, which tell them the sites you visit and the services you use. A few simple steps will enhance your privacy and even speed things up.

Equipment

If you can, buy your own WiFi router. For as little as $50, you can improve your WiFi speeds and gain significantly more control over your internet settings. You don’t have to be an expert; most of these devices are very easy to set up via a phone app.

• The best plug-in-and-go budget option is Eero. You can start with one for less than $50 and add more if you have a large space.
• The best budget feature-rich option that is also easy to set up are TP-Link Wi-Fi routers. This one is $75 and is loaded with goodies, like whole-home VPN support and even faster WiFi with more coverage.
• The best of the best in the budget category is the Unifi Express. It’s just as easy as eero to set up, even more goodies that TP-Link, and the polish of an Apple product. For $149, this is the best home router for most people, and it gets you into one of the best ecosystems for future expansion, like cameras that don’t send your video to Amazon or Google.

DNS

Changing your DNS settings can improve your privacy and speed things up a bit, whether using your equipment or your internet providers. The best way to do this is to modify the settings of your WiFi router, which ensures that all of your devices can benefit. It’s easy to do, and you only have to do it once.

Open the app for your router. If there is no app, you may need to access it from your web browser. If this is the device your internet provider gave you, that website address is usually on the back or bottom of the device, along with the password to login. Once in, look for your DHCP settings. In those settings, you’ll see an option for setting DNS servers. The default for that setting is typically Auto. Change that from Auto to Manual; now you can add your own. If you see existing entries, replace them. There are some great public options here. My recommendation is to use Cloudflare’s servers, as they are not in the business of selling your data and have a good privacy policy.

For most people, use these addresses:

1. 1.1.1.1
2. 1.0.0.1

For those who want to filter dangerous or malware sites:

1. 1.1.1.2
2. 1.0.0.2

For families who want to filter both malware and adult sites:

1. 1.1.1.3
2. 1.0.0.3

Wrapping up

First, I hope you found this helpful. If you’ve come this far, you’re now in more control of your online identities and personal data. Your passwords are random and secure, your emails, files, and web traffic are more private, and your internet is snappier. Nice work!

Originally published at https://chriskirby.net on March 27, 2024.