Experimental software — use with caution and in isolation. mcpproxy is a research prototype provided as-is, with no guarantees of security, stability, or fitness for any particular purpose. It has not undergone a security audit. The web UI has no authentication. Do not expose it to untrusted networks or use it to process sensitive data in production. Run it on a trusted network, preferably in a container or VM you are prepared to reset. See the LICENSE for full MIT terms.

How It Works

mcpproxy exposes two ports: the MCP endpoint on 8888 (http://localhost:8888/mcp) and a web UI on 8889 (http://localhost:8889). The core server (server.py) scans a tools/ directory at startup. Each YAML file there is a provider. A provider either embeds Python async def handler functions directly in a code: block, or delegates to an existing MCP npm package via an npx: block. server.py executes each code block (or spawns the npx process), registers every declared tool automatically, and serves them all through the single MCP endpoint — no changes to server.py ever needed.

A minimal Python provider looks like this:

code: |
  import datetime
  from typing import Any

  async def ping(context: dict[str, Any], message: str = "hello") -> dict[str, Any]:
      return {
          "ok": True,
          "echo": message,
          "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
      }

tools:
  - name: ping
    function: ping
    description: Echo a message back with a server-side UTC timestamp.
    input_schema:
      type: object
      properties:
        message:
          type: string
          default: "hello"
          description: The text to echo back.
      required: []

An npx-based provider is even shorter — just point at the package:

npx:
  command: npx @playwright/mcp@latest --headless --isolated

tools:
  - name: browser_navigate
    description: Navigate to a URL in a browser.
    input_schema:
      type: object
      properties:
        url:
          type: string
      required: [url]

Secret Injection

Secrets are declared in the provider YAML and injected from the environment at call time. The key design property is that secret values are never part of the MCP tool schema — the LLM never sees them:

tools:
  - name: get_weather
    function: get_weather
    ...
    secrets:
      env:
        api_key: WEATHER_API_KEY   # handler arg → env var name

The server reads WEATHER_API_KEY from .env (loaded via Docker Compose env_file) and passes it to the handler as the api_key argument. The LLM’s tool schema only shows the public parameters.

The Web UI

A FastAPI frontend on port 8889 handles the full provider lifecycle.

Tools tab — lists all loaded providers in a left panel. Click any provider to open a form editor with its documentation, code, and per-tool fields (name, description, parameters). Add or remove tools with the + Add Tool / ✕ buttons, save to disk, and restart the MCP server in place — no shell access needed.

+ New Provider wizard — choose between a Python code provider (write async def functions) and an npx package provider (enter an npx command; the UI auto-introspects the MCP server and populates tool definitions). The wizard’s final step lists all required secrets and writes them to .env directly.

🔑 Secrets panel — reads all secrets.env entries from the selected provider, shows which variables are already set in .env, and lets you fill in or update missing values interactively.

🛠 Run Command — runs any shell command inside the server environment and streams output live. Particularly useful for npx-based providers: after adding a Playwright provider, install the Chrome binary with npx playwright install chrome right from the browser panel.

Connecting a Client

The MCP endpoint is http://localhost:8888/mcp. Most major clients support the HTTP transport natively:

# Claude Code
claude mcp add --transport http mcpproxy http://localhost:8888/mcp

For Claude Desktop, Cursor, Cline, Continue, OpenCode, and Windsurf, add a JSON server entry pointing at the same URL. For Ollama (which does not speak MCP natively), the included tests/ollama_agent.py bridges MCP → Ollama tool-calling automatically:

python3 tests/ollama_agent.py "List the tools you have available"

Docker

A pre-built image is published to the GitHub Container Registry on every push to main:

docker pull ghcr.io/billjr99/mcpproxy:latest
docker run -d --rm \
  -p 8888:8888 -p 8889:8889 \
  --env-file .env \
  -v "$(pwd)/tools":/app/tools \
  --name mcpproxy \
  ghcr.io/billjr99/mcpproxy:latest

The tools/ directory is gitignored and never baked into the image — it is always mounted at runtime so your provider files stay outside the container. For a persistent home directory setup that also lets the web UI’s Secrets panel read and write .env, bind-mount ~/.mcpproxy/.env into the container and pass -e MCP_ENV_FILE=/app/.env.

A docker-compose.override.yml is provided for local development with bind mounts; the base docker-compose.yml uses named volumes for production/CI.

Getting Started

The fastest path is run_local.sh:

git clone https://github.com/BillJr99/mcpproxy
cd mcpproxy
./run_local.sh

The script generates .env.example from any existing tool YAMLs, prompts for missing secret values, creates a virtualenv, installs dependencies, and starts both the MCP server and the web UI. Then open http://localhost:8889, click + New Provider, and add your first tool.

The unit test suite covers server.py helpers and all frontend/app.py endpoints and runs on every push via GitHub Actions:

pip install -r requirements.txt -r requirements-dev.txt
pytest tests/ -v

Source code and further documentation are at https://github.com/BillJr99/mcpproxy.

Experimental software — use at your own risk. AutoGUI is a research prototype. It is not intended for, and has not been evaluated or deemed suitable for, any particular purpose, production use, or critical workload. No warranty is provided, express or implied. The agent operates at OS level and can run shell commands, click anything, type anywhere, read and write files, and take screenshots. Run it only in a sandbox, VM, or container that you are willing to reset. Restrict the REST API to loopback (AUTOGUI_API_HOST=127.0.0.1) and consider disabling shell access ("allowed_shell": false) if you do not fully trust the task or the model driving it.

Two Delivery Modes

AutoGUI ships in two forms. The standalone Python CLI/TUI agent connects any OpenWebUI instance (or any OpenAI-compatible endpoint) to your desktop. The native TypeScript Pi extension brings the same tools into the Pi terminal harness behind a single /autogui command, with no dependency on the Python agent or OpenWebUI.

Both share the same tool surface — shell execution, filesystem access, pixel and accessibility-tree clicking, Playwright browser automation — but they differ in how the LLM loop is owned. The standalone agent runs its own ReAct loop; the Pi extension delegates loop ownership to Pi.

Architecture

The standalone Python agent is organized around five main components.

main.py             Entry point — validation, component wiring, TUI/CLI dispatch
│
├── agent.py        ReAct loop + typed-plan controller
│   └─ controller   Preflight, predicate checks, replan-on-block, budget ceilings
│
├── tools.py        Tool registry
│   ├─ shell_run / fs_read / fs_write / fs_list
│   ├─ desktop_screenshot / click / type / hotkey / scroll / launch
│   ├─ desktop_click_element   (a11y-first: UIAutomation / AT-SPI)
│   ├─ desktop_click_mark      (Set-of-Mark grounding)
│   ├─ browser_navigate / click / fill / eval   (Playwright)
│   ├─ skill_save / skill_list / skill_run
│   └─ memory_get / memory_note
│
├── backends/       Platform-specific automation backends
│   ├─ windows.py   UIAutomation + SendInput (user32)
│   ├─ macos.py     screencapture + osascript
│   ├─ linux_x11.py xdotool + wmctrl
│   └─ linux_wayland.py  grim + ydotool + swaymsg
│
├── api.py          FastAPI REST server (auto-started in background)
│   ├─ POST /api/task          Submit task
│   ├─ GET  /api/task/{id}/stream  SSE live event stream
│   └─ GET  /api/healthz
│
└── tui.py          Textual TUI (status bar, model picker, tool visibility toggle)

The agentic loop in agent.py follows a standard ReAct pattern — append the user message to history, POST the history and tool schemas to the LLM, receive either a tool call or a stop response, execute the tool, append the result, and repeat. On top of that loop sits the controller, which adds:

• Planner — one extra LLM call up front that produces a numbered, high-level plan injected as a [PLAN] block into the executor’s context
• Plan critique — a second LLM call that reviews the plan and returns a revised version when issues are found
• Preflight — before the first state-changing action, verifies that apps are on PATH, files exist, URLs are TCP-reachable, and named tools are registered
• Predicate checks — when a plan step declares a typed post-condition (window_title_contains, file_exists, text_visible, etc.), the controller verifies it deterministically after each step completes
• Replan-on-block — when a step is classified as BLOCKED, the controller re-invokes the planner with the failure reason as context
• Visual diff — perceptual hash of pre/post screenshots flags silent no-ops where a state-changing action left the screen unchanged
• Watchdog — detects when the loop is stuck by hashing the per-iteration signature and routing repeated matches through the BLOCKED path

Platform Support

The correct backend is detected automatically at startup via platform_detect.detect(). No configuration is required.

On Windows, click and type operations go through user32.SendInput directly via ctypes, producing real INPUT events indistinguishable from a physical keyboard and mouse, with correct per-monitor DPI handling and full Unicode support. On Linux, the desktop_click_element tool talks to the accessibility tree via AT-SPI, letting the agent click real UI controls by name and role rather than guessing pixel positions.

A11y-First Clicking and Set-of-Mark Grounding

AutoGUI implements two layers above raw pixel clicking.

desktop_click_element(name, control_type) resolves the target UI control through the OS accessibility API and clicks it by logical identity rather than screen position. This survives window moves, DPI scaling, and async UI redraws that would break a coordinate-based click.

For cases where the accessibility tree is sparse or unavailable, Set-of-Mark grounding overlays numbered boxes on detected UI elements in a screenshot. The model selects an element by ID via desktop_click_mark(mark_id) rather than guessing coordinates. The fallback ladder is: desktop_click_element → desktop_click_text (OCR anchor) → desktop_click_mark → desktop_click(x, y).

Skill Library and App Memory

Two optional persistence layers accumulate knowledge across tasks.

The skill library records successful tool sequences with skill_save and retruns them by keyword with skill_list and skill_run. At the start of each task the planner receives the top-3 matching skills as few-shot exemplars, so recurring workflows get faster and more reliable over time. Skill creation is gated by agent.skills_enabled (default false); reads always work.

The app-memory store records per-app quirks, failure counts, and free-form notes via memory_note. At the start of each task the planner receives app memory hints for any visible applications, biasing plans toward strategies that worked before. Memory creation is gated by agent.memory.enabled (default false); reads always work.

REST API and TUI

The FastAPI REST server starts automatically in the background whenever you run main.py. It exposes task submission, SSE live event streaming, and a liveness probe, making AutoGUI accessible to web UIs, scripts, and CI pipelines without the terminal UI.

The Textual TUI provides a scrollable conversation pane with a status bar showing the current model name, conversation length, and tool visibility state. The live model picker (Ctrl+P → “Change Model”) fetches the current model list from the server; selecting a model takes effect immediately and can optionally be persisted to config.json.

Experimental Nature and Safety Considerations

AutoGUI is a research prototype, not a production tool. A few properties of the current design are worth understanding before running it.

The destructive command guard in shell_run blocks patterns like rm -rf, DROP TABLE, and dd if=, but it is a regex filter, not a sandbox. For untrusted tasks, set "allowed_shell": false or run the agent inside a container with a disposable filesystem.

The REST API has no authentication and binds to 0.0.0.0 by default. Set AUTOGUI_API_HOST=127.0.0.1 for loopback-only access or AUTOGUI_DISABLE_API=1 to disable the background API entirely.

The agent operates at OS level. It can click anything, type anywhere, read and write files, and take screenshots. The safety countdown (safety.command_confirm_delay_seconds, default 5 seconds) gives a visible window before each tool dispatch, with Escape-to-cancel, but it is not a substitute for running in an environment you are prepared to reset.

For the same reason, AutoGUI should not be pointed at tasks that involve sensitive data or credentials unless the environment is appropriately isolated. Screen content captured during observation passes through the model’s context window; if you are using a cloud-hosted model, treat everything visible on screen as potentially logged.

Getting Started

Clone the repository from https://github.com/BillJr99/AutoGUI, install the Python dependencies, copy config.json.example to config.json, and set your OpenWebUI URL, API key, and model. Run python main.py --check to verify connectivity before launching the TUI or issuing single-command tasks.

The optional install script at scripts/install-dependencies.sh (or .cmd/.ps1 on Windows) adds Tesseract for OCR-anchored clicking, Playwright for browser automation, AT-SPI on Linux for accessibility-tree element clicking, and ImageMagick for Set-of-Mark overlays and failure GIF recording.

A pytest suite under tests/ exercises the controller, predicates, budget ceilings, preflight, and visual diff modules with no live model and no desktop required — useful for validating changes to the orchestration logic without burning real API calls.

Experimental software — use at your own risk. BetterWebUI is a research prototype. It is not intended for, and has not been evaluated or deemed suitable for, any particular purpose, production use, or critical workload. No warranty is provided, express or implied. Shell commands approved in the chat interface execute directly on the host machine; integrated services (CLK, AutoGUI, OSScreenObserver) may take real actions on your desktop. Run this software only in an isolated, sandboxed environment and review every command before approving it. By using this software you accept all associated risks.

Contributions, bug reports, and ideas are very welcome — feel free to open an issue or pull request!

The Problem

OpenWebUI is an excellent self-hosted model interface with a wide feature set, but its feature set is also its complexity. A faculty member who wants to run a grading assistant, attach a course rubric to every conversation in that context, switch to a research assistant context, and then have the assistant read a file from the local filesystem is navigating four separate configuration surfaces. BetterWebUI reduces that to a single workspace dropdown and a file picker, while keeping all data local.

A second problem is tooling reach. An AI assistant that can only generate text is useful; one that can run a pandoc conversion, call a GitHub API, fetch a web page, read the current screen state, or orchestrate a multi-step research workflow is qualitatively more useful for the kinds of tasks faculty actually do. BetterWebUI provides a unified approval-gated interface for all of these capabilities.

Architecture

BetterWebUI is organized around three layers: a FastAPI backend that manages state and proxies model requests; a zero-build-step HTML/CSS/JS frontend that communicates with the backend over localhost REST calls; and an integration layer that wraps three sibling agentic services behind a common /api/services/* routing namespace.

betterwebui/
├── app.py              # FastAPI backend — model proxy, MCP manager, approval flow
├── static/             # HTML/CSS/JS frontend
├── skills/             # skill markdown files (loaded on demand)
├── services/           # integration clients (CLK, AutoGUI, OSSO)
└── data/               # config.json, conversations, workspaces, uploads

There is no external state. All persistent data — settings, conversations, workspaces, skill files, and uploaded attachments — lives in the data/ directory on the local machine. The only network traffic is outbound to the configured OpenWebUI instance (which may itself be local) and, optionally, to the three sibling services.

Frontend

The frontend is intentionally dependency-free from a build perspective. There is no npm build step, no webpack, and no framework. Every feature is plain HTML, CSS, and vanilla JavaScript, loaded directly from the static/ directory. KaTeX is loaded from a CDN for math rendering. This makes the frontend trivially auditable and deployable: docker compose up or ./start.sh is sufficient, and the UI is available immediately at http://localhost:8765.

Backend

The FastAPI backend handles five primary concerns:

• Model proxying: BetterWebUI auto-detects which API path OpenWebUI exposes (/api, /v1, /openai/v1, etc.) and forwards requests transparently, enriching them with the active workspace’s system prompt, skill content, and any persistent files attached to the workspace.
• MCP server management: MCP servers are spawned as subprocesses (via npx or uvx) and managed over stdio. The backend tracks process health and surfaces startup errors in the UI.
• Skill loading: When the assistant calls load_skill, the backend reads the requested skill markdown file and injects its content into the conversation context.
• CLI tool dispatch: The cli_call tool constructs a command from a registered template and the assistant’s arguments, presents it for user approval, and executes it on approval.
• Service integration: The /api/services/* namespace routes requests to CLK, AutoGUI, or OSSO, enforces the per-service enable/disable state, and handles graceful degradation when a service is unreachable.

Approval Flow

Every action that touches the host machine is gated. Shell commands (from cli_call or a raw run block) display a dialog showing the exact command and the assistant’s stated reason before execution. File saves show a filename preview. File reads open a native file picker so the assistant only ever sees what the user explicitly selects. Side-effect calls to CLK (clk_research), AutoGUI (autogui_task), and OSSO (screen_action) are similarly gated. Read-only service calls (screen_windows, screen_description, screen_screenshot) run without an approval prompt.

Shell execution can be disabled entirely from Settings, in which case cli_call and raw shell blocks return a descriptive error rather than presenting an approval dialog.

Workspaces

A workspace is a saved bundle of context: a system prompt, a chosen subset of skills, a chosen subset of MCP servers, a chosen subset of CLI shortcuts, persistent files that are attached to every new chat in that workspace, and an optional default model. The workspace dropdown at the top of the chat interface switches between them with a single click, reloading the entire context.

The workspace model reflects how faculty actually work. A “Grading” workspace has the grading-rubric skill loaded, a PDF of the current rubric attached, and a system prompt that frames the assistant as a grading helper. A “Research” workspace has the research-citations skill, the Fetch and Brave Search MCP servers enabled, and a system prompt oriented toward literature review. Switching contexts does not require re-configuring anything; the workspace carries all of that state.

Skills

Skills are markdown files in the skills/ directory, each with a YAML frontmatter header:

---
name: Grading Rubric Helper
description: When the user wants to evaluate student work against a rubric
---

When this skill is loaded, apply the attached rubric to the student submission...

The assistant sees a list of available skills and their descriptions. When a user request matches a skill’s description, the assistant calls load_skill to read the full instructions and follow them. Skills are loaded on demand rather than injected into every conversation, which keeps the context window efficient.

Three example skills ship with the repository: a rubric helper, a citation helper, and a computer helper. New skills can be added from the Skills sidebar or by dropping a .md file into the skills/ folder.

MCP Servers

BetterWebUI manages MCP server subprocesses directly and presents them through a curated registry in the Tools sidebar:

Custom entries can be registered with an arbitrary command and argument list. If a server fails to start, the error message from the subprocess is surfaced in the server’s UI row so the prerequisite (typically a missing npx or uvx) is immediately visible.

Service Integrations

BetterWebUI exposes three sibling agentic services through a unified /api/services/* routing namespace. Each service can be enabled or disabled independently from Settings → Services. Disabled services return HTTP 503 immediately. Enabled but unreachable services return a descriptive HTTP 503 rather than crashing.

CognitiveLoopKernel (CLK)

CLK is a local-first multi-agent development harness that takes a natural-language idea and iterates it toward a working implementation through dynamic agent casting, YAML workflow orchestration, and automatic git commits. Through BetterWebUI, the /research <topic> slash command starts a CLK workflow, and the clk_research tool allows the assistant to initiate, monitor, and retrieve artifacts from research loops. Every invocation requires a one-click approval showing the workflow and command before anything executes.

AutoGUI

AutoGUI provides desktop GUI automation via a ReAct-style loop. The /automate <task> slash command sends a task description to AutoGUI. The autogui_task tool surfaces the task for approval before execution. AutoGUI runs in dry-run mode by default, which reports what it would do without taking real actions.

OSScreenObserver (OSSO)

OSScreenObserver exposes the operating system’s UI accessibility tree, OCR text, and ASCII spatial sketches through an MCP interface. Through BetterWebUI, the /observe slash command returns a description of the current screen. Read-only tools (screen_windows, screen_description, screen_screenshot) run without an approval prompt; the screen_action tool, which can click, type, and press keys on real OS controls, requires explicit approval.

Math and Markdown

The frontend renders the assistant’s responses as full markdown — headings, lists, tables, code blocks, and links — and passes mathematical expressions through KaTeX for display-quality typesetting. Both inline ($...$, \(...\)) and display ($$...$$, \[...\]) delimiters are supported. The assistant is explicitly told in its system context that these delimiters are available, so it uses them naturally when the conversation calls for mathematical notation.

Safety Considerations

BetterWebUI’s approval flow is a usability safeguard, not a security boundary. Shell commands execute on the host machine with the permissions of the user running the server. The approval dialog makes every proposed command visible and requires an explicit click before execution, but it does not sandbox or restrict what an approved command can do. Similarly, AutoGUI and OSScreenObserver can take real actions on the desktop once approved.

This means BetterWebUI should be run in a controlled, sandboxed environment — a dedicated virtual machine or container with limited access to sensitive files and services is the appropriate deployment context for any non-trivial use. Multi-user deployment is not supported in the current prototype; the data/ directory is a flat, single-user store with no access controls.

Shell execution can be disabled entirely from Settings. When disabled, cli_call and any raw shell blocks return a descriptive error rather than presenting an approval dialog, which reduces the tool surface to model inference, skill loading, MCP tool calls, and read-only service queries.

Getting Started

The fastest path is Docker:

docker compose up
# open http://localhost:8765

Or directly with Python:

# macOS/Linux
./start.sh

# Windows
start.bat

On first run, open Settings, paste your OpenWebUI URL and API key, click Save & test, and pick a default model. If you have CLK, AutoGUI, or OSScreenObserver running on their default ports, enable them from Settings → Services. Everything else — workspaces, skills, MCP servers — can be configured from the sidebar without a restart.

The source and full documentation are available on GitHub under the MIT License.

Experimental software — use at your own risk. This is a research prototype. It is not intended for, and has not been evaluated or deemed suitable for, any particular purpose, production use, or critical workload. No warranty is provided, express or implied. By using this software you accept all associated risks. In particular, I sandbox this software and use it only with local AI to isolate the environment and to reduce the risk of leaking sensitive information from the desktop environment.

Contributions, bug reports, and ideas are very welcome — feel free to open an issue or pull request!

The Problem: Agents Without Peripheral Vision

The practical limitation that motivated this project is easy to state. You are running an AI agent that is supposed to help you complete a task in a desktop application. The agent can reason about what to do. It can call tools. But it cannot see the application. It cannot verify that a dialog appeared after it clicked a button. It cannot read the text that is currently visible on screen. It cannot detect that the application has changed state between one observation and the next. Without that feedback loop, agentic workflows that involve desktop applications either require the human to narrate the screen state continuously or break silently when an unexpected dialog or error appears.

The two standard approaches to this problem, taking screenshots and reading them with a vision model, and using the operating system’s accessibility API to read the UI element tree, are complementary rather than competing. Screenshots capture everything visible but require a model call to interpret. Accessibility trees give structured, queryable information about UI elements but miss applications that do not instrument the accessibility API. OCR bridges the gap for applications that are neither fully instrumented nor processed by a vision model. OSScreenObserver supports all three modalities and lets the calling agent choose which one to use, or use all three in combination.

Architecture: Two Interfaces, One Observer

The architecture follows a principle that turns out to matter a great deal in practice: any new capability must land simultaneously on both the REST API and the MCP server, backed by shared logic. There is no divergence between what you can do from a browser and what an agent can do over MCP.

┌─────────────────────────────────────────────────────────────────────────┐
│  main.py                                                                │
│  ┌──────────────────────┐      ┌───────────────────────────────────┐    │
│  │  Flask web inspector │      │  MCP stdio server                 │    │
│  │  (background thread) │      │  (main thread, stdin/stdout)      │    │
│  └──────────┬───────────┘      └──────────────────┬────────────────┘    │
│             │                                     │                     │
│             └──────────────┬──────────────────────┘                     │
│                            ▼                                            │
│                    ScreenObserver                                       │
│                   /      │       \                                      │
│          Accessibility  ASCII    Description                            │
│             Tree      Renderer   Generator                              │
│           (observer)             (description)                          │
│                                  ┌──── accessibility (tree prose)       │
│                                  ├──── ocr (Tesseract)                  │
│                                  └──── vlm (Claude Vision)              │
└─────────────────────────────────────────────────────────────────────────┘

The ScreenObserver facade sits below both interfaces and provides three types of observation: the accessibility element tree (structured JSON that describes every visible UI element, its role, name, value, bounds, and parent-child relationships), a textual description generated from the tree, from OCR, or from a vision language model, and an ASCII spatial sketch that renders the layout of the screen as a character grid using Unicode box-drawing characters. The sketch is more useful than it sounds: it gives an agent a token-efficient representation of the spatial arrangement of UI elements without requiring image processing.

Observation Modalities

Accessibility Tree

On Windows, the accessibility tree is populated using the UI Automation API, which gives full element-level information for any application that instruments UIA. This includes most standard Windows applications: browsers, Office applications, system dialogs, and many third-party tools. The tree traversal respects a configurable maximum depth to avoid excessive latency on complex windows such as a browser with many DOM-mapped UIA nodes.

On macOS and Linux, window enumeration and screenshot capture are fully functional. Full accessibility tree support requires additional platform libraries (pyobjc on macOS for the AX API, pyatspi on Linux for AT-SPI), and the adapter stubs in observer.py provide the correct extension points for anyone who wants to contribute those implementations.

OCR

Tesseract-backed OCR runs on a screenshot of the target window and extracts text with per-word confidence scores. Words below a configurable confidence threshold are discarded. OCR is the most broadly applicable modality: it works on any application regardless of accessibility instrumentation, though it obviously captures only visible text and not the structural relationships between elements.

Vision Language Model Descriptions

When vlm.enabled is set to true in config.json and an Anthropic API key is present, the server can send a screenshot to Claude and request a structured description of what is visible. The VLM description is the richest of the three modalities in terms of semantic content, and the most expensive in terms of latency and token cost. It is best reserved for situations where the accessibility tree is sparse (applications that do not instrument UIA), OCR is insufficient (images, icons, non-text UI elements), or the agent needs a holistic interpretation of what is happening on screen rather than a list of element properties.

MCP Integration

The MCP server speaks JSON-RPC 2.0 over stdin/stdout and is compatible with Claude Desktop and Claude Code. Adding it to the Claude Desktop configuration exposes a set of tools that an agent can call to observe and interact with the desktop:

{
  "mcpServers": {
    "os-screen-observer": {
      "command": "python",
      "args": [
        "/absolute/path/to/screen_observer/main.py",
        "--mode", "both"
      ]
    }
  }
}

The tool surface covers observation and interaction:

The get_full_screenshot tool is particularly useful for agentic workflows because it combines a screenshot with an ASCII sketch in a single call, giving the agent both a pixel-level image and a token-efficient structural representation without two round-trips.

Agentic Features

The current codebase is a working prototype. A parallel design document, agentic_features_design.md, specifies a production-grade feature set organized into six implementation phases. The decisions in that document reflect what it actually takes to build a reliable agentic observation loop rather than a demo.

Stable window identity

The prototype uses positional window indices, which break silently when windows open, close, or reorder between tool calls. The agentic design introduces window_uid, a stable opaque identifier that persists until the window closes. On Windows it is win:{pid}:{hwnd}; on macOS, mac:{cg_window_number}; on Linux, x11:{wmctrl_id}. Every tool that accepts a window index also accepts a window UID, and a stale UID returns a typed WindowGone error rather than silently operating on the wrong window.

Element selectors

Clicking at pixel coordinates is brittle. The agentic design specifies a selector grammar, both XPath-ish and CSS-ish, both compiling to the same AST, that lets an agent refer to elements by their role, name, value, or ancestry path through the tree. Window[name=”Notepad”]/Pane/Button[name=”OK”] is stable across window moves and size changes in a way that a pixel coordinate is not.

ActionReceipt

Every input action, click, type, key press, scroll, returns a structured receipt that includes the before and after tree hashes, whether the tree changed as a result of the action, and whether any new dialogs appeared. This gives an agent the feedback it needs to decide what to do next without a separate observation call.

Observe with diff

Full tree snapshots are expensive in tokens. The agentic design specifies that every tree-producing tool returns a tree_token, and that passing since= returns only a diff against the previous observation. The diff format is a custom structure by default, with an option to request RFC 6902 JSON Patch instead.

Wait and synchronize

Agents cannot reliably click a button and immediately check the result, because the result may not be visible yet. The wait_for tool takes a list of conditions, element appears, element disappears, text becomes visible, window appears, tree changes, and polls until one of them is satisfied or a timeout is reached. The response includes which condition matched and how many polls it took.

Typed error taxonomy

Rather than returning a generic error string, every failure returns a structured object with a code, a recoverable flag, and a suggested_next_tool. ElementNotFound suggests find_element. ElementOccluded suggests bring_to_foreground. ConfirmationRequired suggests propose_action. An agent that branches on error.code can recover from most transient failures without human intervention.

Record, replay, and evaluation

Building an evaluation substrate for desktop agents requires the ability to record what an agent did and replay it against a consistent environment. The design specifies a tracing format (JSONL with per-step screenshots), a replay engine with per-tool comparison rules that know which fields are deterministic and which are not, and a YAML scenario DSL for scripting mock environments with state-machine reactions. An agent can be evaluated against a scripted scenario, its trace replayed in verify mode, and the divergences surfaced as structured data.

Confirmation tokens

Some actions are destructive. The confirmation token flow lets an agent propose an action and receive a token bound to the target element’s position and identity. The actual action only proceeds if the agent presents a valid, unexpired token and the element has not moved by more than a configurable pixel tolerance. This is a lightweight safeguard against the category of error where an agent clicks the wrong thing because the UI shifted between the proposal and the execution.

Redaction

Screen content may contain sensitive information: passwords, PINs, SSNs, anything that should not appear in a trace or in the context window of a cloud-hosted model. The redaction system matches element names, values, OCR text, and window titles against configurable patterns and replaces matches with a replacement string before they appear in any tool response or trace entry. Screenshot blur is available as an opt-in for visual redaction.

The Web Inspector

The web inspector at localhost:5001 provides five tabs for human-facing observation.

The STRUCTURE tab renders the accessibility element hierarchy as an interactive collapsible JSON tree. This is the fastest way to understand what elements a particular application exposes and how they are organized.

The DESCRIPTION tab shows a prose description of the selected window, with a mode selector that switches between accessibility tree prose, OCR output, VLM output, and a combined view.

The SKETCH tab renders the ASCII spatial diagram of the window layout, the same output that the get_screen_sketch MCP tool returns.

The SCREENSHOT tab shows the pixel screenshot alongside visible-area bounding boxes and the ASCII sketch in a single panel.

The ACTIONS tab provides a UI for clicking at coordinates, typing text, and pressing key combinations, which is useful for testing input flows interactively before encoding them in an agent script.

The sidebar lists all visible windows. Clicking one selects it, and all tabs update to reflect the selected window. Auto-refresh polls every three seconds.

Mock Mode and Testing

A persistent problem with tools that depend on a running desktop is that they are difficult to test in CI. OSScreenObserver includes a mock adapter that returns scripted window and tree data without requiring any OS access. Tests run under –mock or via direct module imports and never need a desktop session. The CI workflow runs ruff for linting and pytest for the test suite, with no Docker or virtual display required.

The agentic feature design extends mock mode with the scenario DSL, which lets you script a realistic application environment with state-machine reactions: set a username field and the element’s value changes; click the login button with the right credentials and the application transitions to the welcome screen. This is the substrate on which agent evaluation becomes reproducible rather than dependent on whatever application happens to be running.

Conclusion

Running OSScreenObserver against real applications quickly reveals which applications are well-instrumented for accessibility and which are not. Standard Windows applications, system dialogs, and browsers expose rich trees. Electron applications with custom renderers, games, and some creative tools produce sparse trees where OCR and VLM descriptions carry most of the weight. The three-modality design is not over-engineering; it reflects the actual distribution of desktop applications that an agent might encounter.

The prompt injection risk is worth naming explicitly: screen content is included verbatim in tool results, which means that malicious content visible on screen, a web page with injected text, a document with embedded instructions, could attempt to influence the agent’s behavior. The same trust boundaries that apply to any tool that reads external content apply here. The redaction system is a partial mitigation, but the appropriate response to this risk depends on the deployment context.

The setup cost is low for Windows users who want full functionality. Python, Tesseract for OCR, an Anthropic API key for VLM descriptions if desired, and the package from the repository (https://github.com/BillJr99/OSScreenObserver). The mock mode means you can explore the API and the web inspector without any platform-specific setup at all.

What OSScreenObserver ultimately provides is a bridge between the textual nature of large language models and the inherently visual, event-driven world of desktop applications. Rather than forcing agents to reason about pixel coordinates or raw images, the accessibility tree, OCR output, and ASCII spatial sketches give them structured, token-efficient representations of the desktop that align naturally with how LLMs process information. An agent that can read the UI as text, act on it through typed tool calls, and receive structured feedback about what changed is operating in a modality much closer to its native one — and that alignment is what makes reliable agentic desktop interaction tractable rather than brittle.

Motivation: Context as a First-Class Artifact

The practical problem is straightforward. Suppose you work with five or six AI tools on a regular basis: a web-based assistant with a custom instructions field, a local agentic coding CLI with a project context file, a GitHub-hosted agent that runs on repository events, and a few others. Each of these tools has its own mechanism for persistent context, and none of them are the same. You end up with five slightly different versions of your professional profile, your project list, and your working preferences, stored in five incompatible formats in five different places. When something changes, such as a new role, a new project, or a preference update, you update one and forget the others.

The deeper problem is that these tools are increasingly doing things that matter: drafting documents, running code, making commits, composing correspondence. Inconsistent context means inconsistent decisions about what to include, what to assume, and how to frame outputs. Getting this right is worth the architectural investment.

The solution is to store context in a Git repository, maintain it with the same discipline you would apply to any other codebase, and give every AI system a well-specified path to read from and write to it. Obsidian provides the human-readable and human-editable interface. GitHub provides the hosting, versioning, and webhook surface that agents need. The Gitless Sync plugin provides the bridge between the two, and the key insight of the design is that this bridge works in both directions: agents can push changes to GitHub and those changes will appear in Obsidian on the next sync, as long as they follow the metadata protocol described in AGENTS.md.

Hardware and Local Setup

The vault lives on my primary workstation. Obsidian is installed and runs against a directory in the home filesystem. This placement is intentional: on machines that also run local agentic tools, the vault directory is on the same filesystem as the agent workspace, so local agents can read from or write to it without any network call by bind-mounting the directory into their container.

The GitHub repository that backs the vault is a standard private repository. The local Obsidian directory and the GitHub repository are not connected through standard Git tooling on the workstation. There is no .git directory in the vault folder, no git pull or git push in any shell script, and no SSH key configured for this purpose. Synchronization is handled entirely by the Obsidian plugin described in the next section. This is a deliberate choice: it removes any risk of a merge conflict or detached HEAD state caused by operations outside of Obsidian, and it means the sync mechanism is consistent regardless of whether I am running Obsidian on a desktop, a laptop, or the mobile app.

GitHub Gitless Sync: Plugin Setup

Obsidian Gitless Sync is a community plugin that synchronizes an Obsidian vault directly with a GitHub repository using the GitHub REST API, without requiring Git to be installed locally and without creating a .git directory. Each file operation, create, modify, rename, delete, is translated into the corresponding GitHub API call, and the plugin tracks the synchronization state of every file in a local metadata file at .obsidian/github-sync-metadata.json.

Installation follows the standard community plugin path in Obsidian Settings: disable safe mode, browse community plugins, search for Gitless Sync, install, and enable. Configuration requires four values: a GitHub Personal Access Token with repo scope, the repository owner, the repository name, and the branch to synchronize against.

After configuration, the plugin performs an initial sync that either pushes the local vault to the empty repository or pulls a pre-existing repository into the local vault. Subsequent syncs are triggered manually through the command palette or automatically on a configurable interval. The sync direction is bidirectional: local changes are pushed to GitHub, and remote changes, including those made by agents or GitHub Actions, are pulled to the local vault.

The operational requirement worth emphasizing is that the GitHub PAT must have repo scope and must not expire during active use. A token expiration silently breaks sync in a way that is not immediately obvious: Obsidian continues to operate against the local files, and the failure only becomes apparent when an agent’s changes from two days ago have not appeared.

The Key Insight: Agents Can Write, Not Just Read

A common misunderstanding about this setup is that it is read-only from the agent’s perspective, with agents merely consuming context and humans maintaining the vault. The actual design is the opposite. Agents are the primary authors of /wiki/. Their job is to read source material from /raw/, synthesize it into structured Markdown, and write the results into /wiki/ through the GitHub REST API. Those writes propagate to Obsidian on the next sync, and the result appears in the local vault as fully navigable, cross-linked notes.

The mechanism that makes this work is the metadata file. Any process that creates or modifies vault files through GitHub must also update .obsidian/github-sync-metadata.json in the same atomic commit. Without that update, Obsidian’s sync plugin has no record of the change and will not pull it on the next sync. The entire agent write protocol is designed around maintaining this invariant. The full specification of how agents must behave is documented in AGENTS.md, linked and described in detail below.

The SHA Computation Protocol

The sha field in the sync metadata is not a plain SHA-1 of the file’s bytes. It is a Git blob SHA, which Git computes by prepending a header to the raw file content before hashing. Any agent writing to the repository and updating the metadata must implement this correctly, or the sync plugin will treat the file as modified on the next pull.

The algorithm is:

1. Read the raw bytes of the file. Use the byte length, not the character count; this distinction matters for any file containing multi-byte Unicode characters.
2. Construct the header string blob {N}\0, where {N} is the ASCII decimal representation of the byte length and \0 is a literal null byte (0x00).
3. Concatenate the header bytes and the raw file bytes.
4. Apply SHA-1 to the concatenated byte stream.
5. Encode the result as a 40-character lowercase hexadecimal string. This is exactly what git hash-object produces and what the GitHub REST API returns in the sha field of blob responses. A common mistake is to hash the string representation of the content rather than the raw bytes, or to apply SHA-1 without the header. Both produce incorrect values that will not match what GitHub stores.

In practice, there is a simpler path for most agent use cases: set sha to null and dirty to true in the metadata entry after creating or modifying a file. The sync plugin will upload the file on the next sync and replace the null with the API-confirmed SHA. The full SHA computation is only necessary when you want to pre-cache the expected value and avoid a redundant upload. Each metadata entry follows this schema:

{
  "path": "relative/path/from/vault/root/to/file.md",
  "sha": "<40-char hex string or null>",
  "dirty": true,
  "justDownloaded": false,
  "lastModified": 1234567890000
}

After creating or modifying a file, set dirty: true and lastModified to Date.now() in milliseconds. The file and the metadata update must be committed together, atomically. Splitting them across separate commits will cause the sync plugin to mis-handle the change.

For deletions, the entry must include deleted: true and deletedAt alongside the path. The deleted file and the metadata update must again be committed in a single atomic operation.

Vault Structure: The Three-Zone Design

The three-zone structure closely follows the layered architecture Andrej Karpathy described in his April 2026 LLM Wiki gist (gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): immutable raw sources that the LLM reads but never modifies, a wiki layer of structured Markdown that the LLM writes and maintains, and a schema file (his term for what this vault calls AGENTS.md) that specifies conventions and workflows.

The vault is organized into three functional zones with strictly enforced read/write boundaries.

vault/
├── AGENTS.md           # Agent instructions (authoritative)
├── LLMMEMORIES.md      # Persistent user context for AI systems
├── SYSTEMPROMPT.md     # Standing system prompt and interaction preferences
├── raw/                # READ-ONLY source material inbox
│   └── *.md, *.pdf     # Unprocessed documents; never modified by agents
├── wiki/               # Curated, cross-linked knowledge base
│   ├── index.md        # Hub: overview and active work
│   └── */              # Subdirectories organized by domain
└── .obsidian/
    └── github-sync-metadata.json   # Sync state (managed by plugin + agents)

The raw/ directory is a one-way inbox. Documents are dropped there and never touched again by anyone, human or agent. Agents read from raw/ and write exclusively to wiki/. This separation means that the curated knowledge base in wiki/ is never contaminated by unprocessed source material, and source documents are never accidentally overwritten by agent activity.

The root-level canonical files (AGENTS.md, LLMMEMORIES.md, SYSTEMPROMPT.md) are the only files that belong at the repository root. All authored content, every wiki page, every topic note, every hub index, belongs inside wiki/ under an appropriate subdirectory. The root is intentionally clean. If a change appears to require a new root-level file or directory, the right answer is almost certainly that it belongs inside wiki/ instead.

AGENTS.md: The Complete Agent Specification

The AGENTS.md file is the single most important document in the repository. It is the file that GitHub-hosted agents, agentic CLI tools, GitHub Actions workflows, and any other automated process reads first when it encounters this repository.

The file opens with a non-negotiable preamble that instructs any agent encountering the repository to stop and read the file completely before taking any action. This is the architectural guarantee that makes the system self-documenting: the repository itself carries the complete specification for how to operate on it.

Repository Role and Core Mandate

The opening section establishes the conceptual model precisely. /raw/ is the unprocessed source-material inbox. /wiki/ is the curated knowledge base. The agent’s responsibility is to transform material from /raw/ into a structured, cross-linked, maintainable Markdown knowledge base in /wiki/. The core mandate is stated as a numbered list: open and inspect the repository; read relevant materials in /raw/; build, maintain, and improve a coherent knowledge base in /wiki/; create, update, reorganize, and cross-link Markdown notes in /wiki/; commit and push changes back to the repository when changes are made; and when asked questions, answer using /wiki/ first.

Boundary Rules: What Agents Must Never Touch

AGENTS.md specifies three zones that are completely off-limits to agents, and the specificity of these prohibitions is what makes them enforceable.

/raw/ is strictly read-only. Agents must never modify, delete, rename, move, or create files in /raw/. All synthesis, editing, organization, and authored content must go into /wiki/. The source inbox is preserved exactly as it was received.

.obsidian/ is managed exclusively by Obsidian and must not be modified by agents, with one precisely stated exception: .obsidian/github-sync-metadata.json must be updated whenever an agent creates, modifies, renames, or deletes any file outside of Obsidian. No other file inside .obsidian/ may be touched under any circumstances.

/.trash/ is managed exclusively by Obsidian offline and must be left entirely alone. Agents must not read, modify, delete, or create files in /.trash/, and must ignore its contents entirely during all operations. This directory accumulates files that Obsidian has soft-deleted, and any agent interaction with it could corrupt Obsidian’s delete state.

Quick Start Workflow

For any agent starting a session against this repository, AGENTS.md provides a numbered quick-start workflow that specifies exactly what to do and in what order. Open the repository; read AGENTS.md completely; inspect the current structure and contents of /wiki/; inspect relevant material in /raw/; decide what should be created, updated, merged, linked, or reorganized in /wiki/; apply changes in /wiki/ only; commit and push the changes; and if a question was asked, answer it using the curated knowledge in /wiki/.

The sequencing is intentional. Reading the existing wiki structure before making any changes prevents agents from creating duplicate pages, overwriting useful content, or restructuring areas that are already well-organized.

Operational Rules: Synthesis, Not Mirroring

A critical section of AGENTS.md specifies how agents should treat source material. The wiki is a curated layer, not a verbatim mirror of /raw/. Agents are expected to synthesize, summarize, normalize, deduplicate, and organize source material rather than transcribing it. They should prefer updating existing canonical notes over creating duplicates, and should create new notes when a topic clearly deserves its own page. Existing wiki content should be preserved unless it is redundant, obsolete, inaccurate, or clearly inferior to better source material.

The rules also require maintaining factual nuance and uncertainty. Agents must not overstate claims found in source materials. If source materials conflict, the disagreement must be explicitly noted rather than silently resolved. If a source is incomplete, fragmented, or ambiguous, the uncertainty must be marked in the resulting wiki page rather than smoothed over.

Organization Requirements

AGENTS.md specifies that /wiki/ must be organized into clear, intuitive, scalable topical categories expressed as high-level directories with meaningful subdirectories. The wiki must never be a flat dump of loose notes at its top level. Related notes must be grouped under shared parent directories, with finer topics nested beneath broader domains. New top-level categories should be introduced when they have earned their place, and subdirectories should be split further as a topic grows.

The file explicitly names the page types that should be maintained where appropriate: overview pages, topic pages, concept and reference pages, project pages, people pages, hub and index pages, and chronology or notes pages. Category and hub pages should be created when they improve navigation. Filenames should be stable and human-readable. The guiding principle is a small number of well-maintained canonical pages over many fragmented or overlapping notes.

Reorganization is permitted and encouraged when it improves hierarchy, clarity, or navigability, but specifically prohibited when it is cosmetic or churns structure for its own sake. The instruction is direct: do not degrade a well-organized area with unnecessary restructuring.

Linking and Navigation

AGENTS.md requires that agents use Obsidian wikilinks extensively and meaningfully:

[[Page Name]]

Every wiki note should connect related ideas across the vault. “Related” or “See also” sections should be added where useful. Large blocks of content should be linked rather than duplicated. Each page should fit meaningfully into the larger structure, and hub pages should be created when they improve discoverability.

Formatting Expectations

All authored content must be Markdown only, clearly titled, readable and well-structured, concise but sufficiently specific, and polished rather than raw. Headings should be used when they improve structure, bullet points when they improve clarity, and tables only when they are genuinely useful. Pages should begin with a short summary when appropriate. Generic filler summaries that erase important details are explicitly prohibited.

Document Ingestion Protocol

When a new document appears in /raw/ or an agent is asked to ingest a document, AGENTS.md specifies a complete ingestion protocol. Read the document fully before making any changes. Identify content that maps to existing wiki pages and merge or enrich those pages rather than duplicating them. Create new wiki pages when a topic is substantial enough to deserve its own page. Reorganize files and directory structures when the new content warrants it, for example by introducing a new subdirectory if a category of content has grown, or renaming pages, or moving pages between directories. Update all hub and index pages to reflect any new pages created or any structural changes made. Cross-link newly created or updated pages into related pages using Obsidian wikilinks. Update .obsidian/github-sync-metadata.json for every file created or modified, following the SHA computation protocol. Commit and push all changes atomically when the ingestion is complete.

Wiki Linter: A Built-In Maintenance Agent Task

One of the more distinctive features of AGENTS.md is a detailed specification for a wiki linter, a maintenance agent task that audits and repairs the vault’s structural integrity, link validity, and metadata completeness. The linter is described as a seven-step workflow that any agent can execute.

Step 1 identifies the vault metadata JSON file by checking the standard locations for community plugins before proceeding. Step 2 recursively enumerates all vault files, including those in .trash/, building complete lists of markdown files and non-markdown assets. Step 3 scans every markdown file for internal Obsidian wikilinks and standard relative markdown links, resolves each link against the full file list using Obsidian’s resolution rules (case-insensitive match on filename without extension, shortest-path-wins for ambiguous names), and classifies each as valid, broken due to file not found, broken due to ambiguity, or broken due to a missing heading. Broken links are repaired according to a precisely specified strategy: links with no plausible near-match have their syntax removed with an inline comment; links with a near-match (edit distance of 2 or less on the base filename) have the target corrected with an inline comment; broken heading links have the fragment removed while the file link is preserved.

Step 4 audits the metadata JSON for completeness, verifying that every markdown file has a corresponding entry with all required fields. Missing entries are synthesized using the existing schema as a template, populated from the file’s YAML frontmatter and filesystem timestamps where available. Step 5 validates the metadata JSON for well-formedness: valid JSON with no trailing commas or comments, all path keys using forward slashes, all date fields in ISO 8601 format, no raw newlines within string values, and UTF-8 encoding without BOM.

Step 6 updates AGENTS.md itself and its metadata entry to reflect the current UTC datetime, so that Obsidian Sync recognizes the file as modified and pulls the updated version on the next sync. Step 7 writes a linting report file to the repository root with a full summary of findings, broken links, metadata gaps, items requiring manual review, and files modified during the run.

The linter’s execution rules are notable for their conservatism: every file write is preceded by a diff against the current content, and the file is not written if the diff is empty. Ambiguous or destructive repairs, such as removing more than a link fragment, are flagged for manual review rather than applied automatically. The linter never modifies any file in .obsidian/ except the metadata JSON, and if running in an environment without write access it produces a dry-run diff report instead of writing files.

Question-Answering Mode

AGENTS.md specifies how agents should behave when asked a question and told to use the vault. They must open the repository and read /wiki/ first as the primary and authoritative curated knowledge source. /raw/ is consulted only to fill gaps, verify details, or incorporate newly added material not yet reflected in /wiki/. If /wiki/ is incomplete or outdated relative to /raw/, the agent should update /wiki/ first when appropriate, before answering the question.

This sequencing, wiki first and raw as a fallback rather than a primary source, is what makes the curated knowledge base progressively more valuable over time. Each question that exposes a gap is an opportunity to improve the wiki before answering.

LLMMEMORIES.md: Cross-Platform Persistent Memory

LLMMEMORIES.md is the canonical record of persistent user context. It is structured as a Markdown document with clearly delineated sections covering identity and roles, academic credentials, teaching responsibilities, research background, active funded projects, collaborators, and working preferences.

The key design principle, stated explicitly in AGENTS.md, is that this file is bidirectionally synchronized. When an AI system forms a more accurate or more detailed picture of some aspect of your context through extended interaction, that updated understanding should be written back into LLMMEMORIES.md. When LLMMEMORIES.md is updated in the repository, any agent starting a new session should read the new version and treat it as authoritative. The file is, in effect, an externalized, version-controlled memory store that persists across tools, sessions, and platforms.

When starting any session, AGENTS.md instructs agents to read both LLMMEMORIES.md and SYSTEMPROMPT.md and treat them as authoritative context alongside AGENTS.md itself.

SYSTEMPROMPT.md: Twelve Sections of Standing Instructions

SYSTEMPROMPT.md captures the behavioral and stylistic instructions that would otherwise need to be pasted into the system prompt or custom instructions field of each tool individually. It is organized into twelve numbered sections.

Section 1: Identity and Role Context establishes professional identity and secondary identities relevant to task framing, including domain-specific calibration instructions. The purpose is not to describe the person to themselves but to give AI tools enough context to calibrate depth, vocabulary, and framing automatically without requiring re-explanation each session.

Section 2: Communication and Output Style covers prose and academic writing, email and correspondence, and document formatting. Academic writing uses complex and compound-complex sentences with commas, a challenges-first structure, first-person plural (“we”) for academic contexts, hedging by scope condition rather than weakened claims, precise technical vocabulary, and lists framed by prose. The prohibition on em dashes is explicit: they must be replaced with commas, subordinate clauses, or restructured sentences. Email style is short, direct, and warm, opening with “Hi [Name]!” and closing with “Bill”, committing rather than hedging, and appropriate for mild humor in familiar professional contexts.

Section 3: Technical and Coding Preferences specifies exception handling conventions (print with a location-specific prefix string plus traceback.print_exc(), never silently swallow exceptions), a requirement to provide complete revised function definitions rather than partial snippets or ellipsis-truncated fragments, a preference for externalizing all configuration into JSON files with configurable logging levels, a preferred technical stack for ML and pipeline work, and instructional code conventions that interleave mathematical derivations and conceptual explanations with implementation.

Section 4: Task Execution Behavior covers three sub-protocols. Before starting any task, an agent must read any context/ or ABOUT-ME/ directory, any SYSTEM-RULES.md or HOW-I-WORK.md file, and any project-specific subfolder or template that applies to the task. The clarification protocol prohibits beginning execution if the goal, intended audience, output format, or scope is ambiguous in ways that would materially affect the output. Output discipline requires stating assumptions explicitly and flagging uncertainty inline rather than omitting it.

Section 5: Domain-Specific Standing Instructions covers machine learning and AI (maintaining precision with probabilistic claims and applying existing pipeline architecture by default), computer science education and SoTL (grounding pedagogical recommendations in literature and noting evidentiary basis), grant and sponsored research writing (active voice, outcome-oriented framing, explicit distinctions between completed and proposed work), aviation and drone operations (applying FAA regulatory context from 14 CFR Parts 61, 91, and 107 as appropriate), and amateur radio (applying ITU and FCC Part 97 context, distinguishing between amateur and emergency communication contexts).

Section 6: Memory and Context Hygiene addresses the stateless nature of many AI sessions. Workspace folder context files are the authoritative persistent memory, not inferred prior session context. If a task produces information that should persist across sessions, the instruction is to suggest saving it to the appropriate context file and offer to do so.

Section 7: General Constraints includes an absolute prohibition on hallucinating citations, a requirement to prefer depth and accuracy over speed, and a constraint against producing outputs that could be mistaken for official institutional communication without explicit authorization.

Section 8: Confirmation Gates is the section with the most direct operational consequence for agentic use. It defines six categories of action that require explicit affirmative confirmation before execution, and specifies precisely what information must be displayed when requesting that confirmation. A general instruction to “go ahead and handle everything” explicitly does not constitute confirmation for any of these categories.

Gate 8.1 covers destructive or significant file system alterations: deleting any file or directory, overwriting any existing file (with a requirement to propose a versioned backup first), renaming or moving more than three files in bulk, modifying any file outside the active workspace folder, or clearing a database. Gate 8.2 covers external communications: sending any email or message via any connected service. Drafting is permitted without confirmation; sending is not. Gate 8.3 covers version control actions: committing to any repository, pushing to any branch including feature branches, creating or deleting or merging branches, tagging a release, or force-pushing (the last of which is additionally flagged as high-risk). Gate 8.4 covers web and cloud publishing: deploying web content, updating live pages or API endpoints, uploading to publicly accessible cloud storage, submitting forms or proposals, or modifying DNS or SSL configuration. Gate 8.5 covers financial, administrative, and credentialed actions: financial transactions, institutional system access, grant portal submissions, or anything generating a binding commitment on the user’s behalf. Gate 8.6 establishes a threshold for batch operations: any automated operation affecting more than five files, records, or API calls in a single execution requires confirmation before the batch runs, with a display of the first two or three operations so the pattern can be verified.

Section 9: Plan-First Protocol requires that for any task involving more than three discrete steps, or touching more than one confirmation gate category, a written execution plan must be presented before any action is taken. The plan must include a numbered list of all steps in sequence, the tool or method and expected output for each step, an explicit list of any confirmation gates that will be triggered and at which step, and an explicit request for approval before Step 1 executes.

Section 10: Sensitive Data Handling establishes FERPA-based handling requirements for student data (no transmission, caching, or summarization of student records outside the local workspace without explicit authorization), IRB-based handling requirements for human subjects research data (flag any task appearing to involve such data and request confirmation of the applicable IRB protocol before proceeding), and a general prohibition on logging or outputting API keys, passwords, OAuth tokens, or unpublished grant narratives.

Section 11: Task Logging and Audit Trail requires appending a session log to logs/session_log.md at the conclusion of any session in which files were created, modified, sent, or published. The log entry must include the date and time, a one-paragraph plain-English summary of what was accomplished, a list of files created or modified with their paths, a list of any external actions taken with confirmation that each was explicitly authorized, and any open items or follow-up tasks identified during the session.

Section 12: Escalation and Uncertainty Protocol is the most operationally important safety instruction for autonomous use. If at any point during execution an agent encounters a situation not covered by the instructions, a conflict between two instructions, an unexpected error or permission failure or ambiguous system state, or a result that does not match the expected output, the instruction is to stop execution immediately, report the situation clearly, and wait for guidance. Autonomous recovery from unexpected states by taking additional actions is explicitly prohibited. The protocol frames this as a cost-benefit argument: the cost of pausing is always lower than the cost of an unintended irreversible action.

Connecting AI Systems to the Vault

The practical integration pattern differs by tool type, but the underlying idea is the same in every case: give the tool a path to AGENTS.md, LLMMEMORIES.md, and SYSTEMPROMPT.md, and let those files do the context-setting work.

For agentic CLI tools like Claude Code and OpenCode, the integration is a CLAUDE.md or AGENTS.md file at the root of each project that begins with a fetch-and-read instruction pointing at the vault repository:

## Context
 
Before beginning any task, fetch and read the following files from the
knowledge repository:
 
- https://raw.githubusercontent.com/YOUR_GITHUB_USERNAME/Obsidian-Vault/main/AGENTS.md
- https://raw.githubusercontent.com/YOUR_GITHUB_USERNAME/Obsidian-Vault/main/LLMMEMORIES.md
- https://raw.githubusercontent.com/YOUR_GITHUB_USERNAME/Obsidian-Vault/main/SYSTEMPROMPT.md
 
Treat the contents of those files as authoritative context for all decisions
in this session.

For GitHub Actions workflows, the vault repository is checked out as a secondary input in the workflow definition:

- name: Checkout knowledge vault
  uses: actions/checkout@v4
  with:
    repository: YOUR_GITHUB_USERNAME/Obsidian-Vault
    token: $
    path: vault
 
- name: Build context
  run: |
    cat vault/AGENTS.md vault/LLMMEMORIES.md vault/SYSTEMPROMPT.md > /tmp/context.md

For web-based assistants with a custom instructions field, I maintain a condensed version of SYSTEMPROMPT.md in that field, with a reference to the full repository for agents that can fetch URLs. The condensed version covers the highest-impact sections: identity, writing style, confirmation gates, and the location of the canonical files.

For local containerized agents, the vault directory is bind-mounted directly into the container’s filesystem:

docker run --rm -it \
  -v "$HOME/obsidian-vault:/vault:ro" \
  -v "$HOME/projects/current:/workspace" \
  my-agent:latest

The :ro flag applies when the local agent is consuming context rather than writing wiki content. For agents whose primary job is to write to /wiki/, the mount is read-write, and the agent commits its changes through the GitHub REST API so that the metadata protocol is satisfied correctly. Thanks to the system prompt details about updating the Github Gitless Sync plugin metadata json file, this is optional, and agents can also modify the repository to be synchronized back to Obsidian. In this way, I really only use Obsidian as a convenient viewer.

A Concrete Example: Your CV as a Raw Source

The most direct way to see how the write path works is to walk through the simplest possible workflow: drop a document into raw/, point an agent at the repository, and watch it process the document into wiki/.

Suppose you drop a PDF CV into raw/:

raw/
└── my-cv.pdf

You then give an agentic tool the following instruction, which is all it needs because the rest is specified in AGENTS.md:

Clone https://github.com/YOUR_GITHUB_USERNAME/Obsidian-Vault, read AGENTS.md,
and follow the instructions to process any unprocessed documents in raw/.

The agent reads AGENTS.md, which tells it that raw/ is a read-only inbox, that processed content belongs in wiki/, and that it must update .obsidian/github-sync-metadata.json for every file it creates. It then reads the CV, extracts the relevant structured information, and builds out the wiki accordingly, creating pages for education, positions held, publications, funded projects, skills, and service roles, cross-linking them to each other and to an index.md hub. It commits the new wiki files and the updated metadata back to the repository in a single atomic commit.

The next time you open Obsidian and trigger a sync, those wiki pages appear in your vault as fully navigable, cross-linked notes. The CV has been processed exactly once, its information now lives in a structured and queryable form, and the original PDF is preserved untouched in raw/.

The same workflow applies to any source material: a conference paper, a project brief, a set of meeting notes exported from another application, a transcript, a published technical document. Whatever arrives in raw/ becomes an input to the next agent run, which extends the wiki without touching anything that already exists. Over time, the wiki accumulates a comprehensive, cross-linked knowledge base built from actual documents, maintained by agents that follow the same explicit instructions every time.

The Wiki as a Queryable Knowledge Base

The wiki/ directory is the output of the system, the structured knowledge base that gets built and maintained over time. Its organization should reflect the categories of information it needs to represent. AGENTS.md specifies that the wiki must be organized into clear, intuitive, scalable topical categories with high-level directories and meaningful subdirectories, never left as a flat dump of loose notes at its top level.

The wiki/index.md serves as the hub for the entire knowledge base. When an agent is asked a question and instructed to use the vault, AGENTS.md specifies that it starts at wiki/index.md, identifies the relevant area, navigates to the appropriate subdirectory, reads the relevant files, and synthesizes an answer, updating the wiki first if it is incomplete or outdated relative to available source material in raw/.

This sequence, hub to subdirectory to relevant pages to synthesis, is the same workflow a human would follow when using Obsidian, which makes the agent behavior predictable and auditable. The wiki is structured for both human navigation and machine traversal, because those two requirements are compatible when the underlying format is plain Markdown with explicit cross-links.

The raw/ Inbox and Reference Cataloging

The raw/ directory handles a problem that anyone who works across multiple document formats encounters regularly: you receive a PDF, or an exported summary, or a transcript, and you need to incorporate the information into your knowledge base without losing the original source. The raw/ inbox holds originals in whatever format they arrive, and they are never modified.

The non-destructive contract of raw/ means that the inbox can grow without risk. A new document dropped into raw/ will be picked up on the next agent run and incorporated into the wiki, while the original is preserved for future reference or re-processing. When an agent creates a wiki note from a source document, it links back to the original in raw/ using a relative wikilink:

*Source: [[../raw/my_cv.pdf]]*

Obsidian renders this as a clickable link that opens the original document; an agent resolves it as a vault-relative path. This citation chain means that every wiki page can be traced back to its source, and the source can be re-processed with a better agent or a different prompt without losing either the original document or the previously generated wiki content.

Synchronization in Practice

The full synchronization cycle, from a local Obsidian edit to an agent seeing the change, involves three steps: edit in Obsidian, trigger a sync via the Gitless Sync plugin, and have the agent pull from the GitHub API or clone the repository fresh. The reverse cycle, from an agent commit to Obsidian seeing the change, is: agent writes to GitHub via the REST API, updating metadata correctly in the same atomic commit; Obsidian pulls on the next sync; and the new or modified file appears in the vault.

The metadata protocol is what makes the reverse cycle work reliably. An agent that creates files without updating the metadata will find that those files appear to Obsidian as if they were created outside the sync system and may not be pulled on the next sync. An agent that updates metadata with incorrect SHA values will trigger a spurious re-download of files that have not changed. The atomic commit requirement, where the file change and the metadata update land in the same commit, prevents a state where one exists without the other.

Practical Takeaways

Running this system for the past year has produced a clear picture of what works and what requires ongoing attention. The three-file root structure (AGENTS.md, LLMMEMORIES.md, SYSTEMPROMPT.md) has proven to be the right level of granularity: enough separation to allow selective reading, not so much fragmentation that agents need to synthesize across many files to get a complete picture. The raw/ read-only constraint has been invaluable; on two occasions, agents attempted to modify source documents, and the explicit prohibition in AGENTS.md was what stopped them. The bidirectional memory update convention for LLMMEMORIES.md is theoretically correct but requires discipline in practice: it is easy to accept a session’s refined understanding and forget to write it back to the file.

The confirmation gate protocol in SYSTEMPROMPT.md has proven its value in agentic contexts most sharply. Having the protocol specified in a canonical file rather than per-tool configuration means that a GitHub Actions workflow, a local container running Claude Code, and a web-based assistant all inherit the same safety constraints automatically. The cost of reading the file is negligible; the cost of not having the protocol is an agent that commits, pushes, or deploys without checking first.

The setup cost is low. The vault structure requires perhaps two hours of initial authoring: writing AGENTS.md, writing an initial LLMMEMORIES.md from whatever context you already maintain elsewhere, and writing an initial SYSTEMPROMPT.md from the instructions you already paste into various tools. The return, in terms of consistent and well-calibrated AI assistance across tools and sessions, scales with the quality of those three files. The vault has become the single source of truth for the context that every AI tool I use draws from, and the discipline of maintaining it in one place is considerably less costly than the alternative of maintaining five inconsistent versions of the same information in five incompatible formats.

This article provides a detailed walkthrough of CLK’s architecture, its principal subsystems, and the design decisions that distinguish it from similar tools.

Experimental software — use at your own risk. CLK is a research prototype. It is not intended for, and has not been evaluated or deemed suitable for, any particular purpose, production use, or critical workload. No warranty is provided, express or implied. By using this software you accept all associated risks.

Contributions, bug reports, and ideas are very welcome — feel free to open an issue or pull request!

Why a Local-First Harness?

The core motivation for CLK is reproducibility and ownership. Everything the harness produces, including agent prompts, provider configurations, per-run logs, intermediate file states, and git history, lives under a single .clk/ directory inside a project folder on your local disk. There is no external orchestration service, no account required, and no state stored elsewhere. If you want to inspect what a particular agent said in iteration four of last Tuesday’s engineering loop, you look at .clk/runs/. If you want to understand why the chief cast a security_auditor role, you read .clk/state/casting.log. The harness treats transparency as a first-class property of the system.

A second motivation is provider agnosticism. CLK supports Claude Code, OpenAI Codex, Google Gemini, any OpenAI-compatible HTTP server (via OpenWebUI), local Ollama models, Pi, and a built-in shell dummy provider for testing and CI. Switching providers requires a single configuration change, and different agents within the same workflow can be bound to different providers, so you can route heavy reasoning tasks to a cloud model while keeping low-stakes validation steps on a local Ollama instance.

High-Level Architecture

CLK is organized around three principal concerns: state management, agent orchestration, and provider abstraction. The package layout reflects this separation.

clk_harness/
  cli.py                 # argparse entrypoint and command dispatch
  config.py              # paths, default configs, JSON load/save helpers
  git_ops.py             # init, commit, revert, and status wrappers
  providers/             # claude, codex, gemini, ollama, openwebui, pi, shell
  orchestration/         # agent runner, workflow runner, ralph/autoresearch loops
  templates/             # bundled prompts and default workflow YAML
  utils/                 # structured logging and activity tracking

The harness state, written by clk init and extended by every subsequent command, is isolated under .clk/ in the project root:

.clk/
  config/
    clk.config.json      # project-wide configuration
    providers.json       # provider registry and active selection
    agents.json          # agent-to-prompt-and-provider mapping
    workflows/*.yaml     # Archon-style workflow definitions
  prompts/               # per-agent system prompt templates
  state/
    idea.json            # the captured project idea
    system_brief.md      # initial brief
    prd.json             # product manager output
    progress.md          # human-readable development timeline
    decisions.md         # log of architectural decisions
    experiments.jsonl    # per-iteration outcome records
    agent_memory.jsonl   # all agent invocations with token usage
    casting.log          # JSONL of every roster change
    done.md              # written when completion criteria are met
  blackboard/            # cross-agent shared scratchpad (POST blocks)
  logs/                  # session and per-command logs
  runs/                  # per-invocation prompt and response capture
  backups/               # safety copies of files before mutation

This layout means that deleting .clk/ resets the harness entirely without touching anything the agents actually built. The project source, tests, documentation, and configuration live in the project root proper and are managed by an ordinary git repository.

Dynamic Agent Casting

The most distinctive architectural decision in CLK is dynamic team assembly. Rather than shipping a fixed roster of roles, the harness ships three baseline agents that cannot be removed, and then lets the chief agent invent and register project-specific specialists on the fly.

The three baseline agents are chief, which decomposes objectives, casts the team, and authors workflow YAML; ralph, which drives both the iterative refinement loop and Karpathy-style autoresearch cycles; and qa, which validates stage outputs. Every other agent, including engineer, is a dynamic role that the chief creates by emitting a structured PROPOSE_ROLE block in its response text:

PROPOSE_ROLE: data_steward
ROLE: ensure data integrity and schema versioning
PROVIDER: claude
PROMPT:
You are the **Data Steward** agent.
Objective: $objective
State: $state_summary
...
END_ROLE

The harness parses this block, writes the generated prompt to .clk/prompts/data_steward.md, registers the role in .clk/config/agents.json, and makes it available to subsequent stages in the same workflow cycle, all without pausing execution. Every roster decision is appended as a JSONL entry to .clk/state/casting.log, giving you a complete provenance record of how the team evolved over the project’s lifetime.

The chief can also propose custom workflows:

PROPOSE_WORKFLOW: engineering
YAML:
name: engineering
stages:
  - id: decompose
    agent: chief
    objective: Decompose the current top-level objective.
  - id: implement
    agent: data_steward
    depends_on: [decompose]
    validation: "pytest -q"
    commit: true
END_WORKFLOW

The harness validates the YAML (both via PyYAML when available and a built-in mini-parser for environments where ensurepip is unavailable), writes the file to .clk/config/workflows/, and routes the next clk run invocation through the new stage graph. This architecture means the project workflow is not hardcoded into the harness; it is a first-class artifact that the chief authors and evolves as it learns more about the project’s requirements.

The name engineer is reserved and protected. The harness rejects attempts to create aliases such as engineering, coder, or developer, and feeds the rejection back into the chief’s context as casting feedback so it learns to use the canonical name directly. A cap from clk.config.json::casting.max_dynamic_roles (default 12) prevents unbounded role proliferation.

The Action Protocol

Agents drive real changes by emitting structured ACTION: blocks. A response that merely describes what should happen but emits no ACTION blocks has no side effects, which is a deliberate design choice: the harness makes it impossible for an agent to accidentally mutate the project simply by describing a plan.

The supported action types are:

• ACTION: write creates or overwrites a file at the specified path.
• ACTION: edit applies a targeted textual replacement within an existing file, analogous to a very simple diff application.
• ACTION: append adds content to the end of an existing file.
• ACTION: delete removes a file.
• ACTION: run executes a shell command from the project root with output captured to the log.
• ACTION: done writes .clk/state/done.md and signals all loops to terminate.

All paths are validated against the project root before execution. Any path that resolves into .clk/ is rejected outright (with the single exception of .clk/blackboard/, which agents may write to via POST blocks). Attempted path traversal outside the project root is similarly rejected. Before any file is mutated, the original is backed up to .clk/backups/<run_id>/, so every overwrite is recoverable. A per-response cap of 25 file actions prevents runaway agents from restructuring the entire project in a single cycle.

Following each successful batch of action applications, the harness generates a structured git commit with the agent name, objective, files changed, commands run, and token totals embedded in the commit body. The git log thus becomes a faithful narrative of the project’s development, authored by the agents themselves.

Blackboard: Cross-Agent Communication

Agents in a multi-stage workflow often need to share findings without routing everything through the chief as a relay. CLK provides a structured shared scratchpad called the blackboard, which lives at .clk/blackboard/ as a collection of JSON files.

Rather than writing to the blackboard directly via ACTION blocks (which the harness would reject as .clk/ access), agents emit POST blocks:

POST: finding
TITLE: Database schema analysis complete
PRODUCES: schema_contract
BODY:
Three tables identified: users, sessions, events.
The sessions table lacks a foreign key constraint.
Recommend adding: ALTER TABLE sessions ADD FOREIGN KEY ...
END_POST

The harness parses this block, adds metadata (timestamp, author, stage ID, workflow name), and writes the post as a JSON file under .clk/blackboard/. When the next stage runs, the workflow runner injects a filtered digest of relevant posts into each agent’s prompt via the $blackboard_digest placeholder. Stage definitions can declare inputs to specify which posts they want to consume and outputs to specify which contract keys they are expected to produce, enabling the workflow runner to verify that inter-agent contracts are satisfied before committing a stage.

Posts are immutable. To revise a finding, an agent writes a new post with the original post ID listed in the CONSUMES field, creating an auditable revision chain rather than silent overwriting.

Workflow Execution and Dependency Resolution

Workflows are YAML files describing a directed acyclic graph of stages, each bound to an agent and an objective:

name: engineering
description: Single development cycle.
stages:
  - id: decompose
    agent: chief
    objective: Decompose the current top-level objective.
  - id: implement
    agent: engineer
    objective: Implement the smallest vertical slice.
    depends_on: [decompose]
    validation: "pytest -q"
    commit: true
  - id: validate
    agent: qa
    objective: Audit implementation and confirm test passage.
    depends_on: [implement]

The workflow runner (orchestration/workflow.py) topologically sorts stages by their depends_on declarations and executes stages that share no dependencies in parallel using a ThreadPoolExecutor. Each stage may declare a validation shell command; the command must exit 0 before the harness will commit the stage’s changes. Failed validations leave the working tree untouched. The parallel execution design means that a large workflow with independent research and implementation tracks can run those tracks concurrently rather than serially.

The default engineering.yaml workflow ends with a supervise stage, where the chief evaluates whether the user’s original prompt has been fully addressed. The chief either emits an ACTION: done block (writing done.md and terminating the loop) or emits a PROPOSE_WORKFLOW block describing the next iteration’s stages, upon which the runner picks them up and executes another cycle. This supervisor loop is capped at clk.config.json::supervise.max_cycles (default 5) to prevent runaway iteration.

Self-Healing on Unmet Dependencies

When a workflow stage’s declared dependencies fail, the harness does not silently skip the stage or crash. Instead, it dispatches the chief agent in recovery mode, providing the exact failure reasons (agent error text, validation command output, QA report) and asking the chief to either re-cast the workflow, emit ACTION blocks that fix the upstream failure directly, or propose a specialist agent that can resolve the issue. This recovery dispatch is capped at three passes per stage (configurable via clk.config.json::recovery.max_per_stage) to prevent infinite recovery loops. The design treats agent and validation failures as information that the system can reason about, rather than hard stops requiring human intervention.

Iterative Improvement Loops

CLK ships two distinct iterative loop modes, both driven through the ralph agent.

The Ralph Refinement Loop

The Ralph loop (/loop ralph N in the TUI, or clk loop --max-iterations N on the CLI) implements a simple but effective iterative improvement cycle. In each iteration, Ralph reads the current state files and git log, identifies one measurable improvement, and produces a plan. The engineer implements the plan, QA validates it, and the harness runs any configured validation commands. If all checks pass and the working tree has changed, the harness commits the iteration with full metadata. If validation fails, git reset --hard reverts the working tree to the pre-iteration HEAD, and the outcome is recorded in experiments.jsonl so subsequent iterations can learn from the failure without contaminating the committed project state. The loop terminates when done.md is created or max_iterations is reached.

The Autoresearch Loop

The autoresearch loop (/loop autoresearch N) implements a Karpathy-style research cycle oriented toward hypothesis generation and experimental learning rather than feature delivery. Each iteration, Ralph surveys the current state to identify the highest-value open question (recorded in the project’s decisions.md or blackboard), designs a small targeted experiment to address it, runs the experiment via ACTION blocks, and records the outcome in experiments.jsonl regardless of whether the experiment succeeded or failed. The philosophy is that failed experiments are useful data, and the loop accumulates a structured research log that informs subsequent iterations. Both loop modes respect the done.md termination condition and can be stopped gracefully via the TUI’s /stop command, which signals the loop to halt after the current iteration completes rather than aborting mid-iteration.

The Provider System

All agent invocations flow through a provider abstraction defined in providers/base.py. Each provider implements invoke(request: AgentRequest) -> AgentResponse, where the request carries the rendered prompt and metadata, and the response carries the text output, token counts, and a success flag. The harness ships seven provider implementations.

For the CLI-driven providers (claude, codex, gemini), CLK supports two authentication modes. The cli mode (default) spawns the provider’s local CLI as a subprocess and trusts whatever session authentication that CLI already has. The apikey mode bypasses the local CLI entirely and calls the upstream HTTP API directly, using standard environment variables (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY). This separation makes CLK usable in both developer workstation contexts (where a persistent CLI session is already authenticated) and CI/CD environments (where API keys are injected as secrets). Per-agent provider binding in agents.json means you can route different agents to different providers within the same workflow cycle, which is useful when you want cloud reasoning for the chief and local generation for lower-stakes implementation stages.

The TUI Dashboard

For interactive use, CLK ships a terminal user interface (TUI, implemented in clk_harness/tui.py using curses) that provides live visibility into the multi-agent execution. The TUI displays a card for each active agent showing its current state (idle, working, done, or failed), a scrollable status log that mirrors the session log file, a live heartbeat indicating whether a running agent subprocess is actively streaming or silent, and a command input field styled after Claude Code’s > prompt. A bottom band reports running totals: agent count, total tokens consumed (input and output separately), peak concurrent runs, and files written.

The TUI also supports interactive steering via typed commands:

The heartbeat mechanism deserves specific mention. CLI providers stream their subprocess’s stdout and stderr live to the status pane, so every line the CLI prints (authentication status messages, connection attempts, retry notices) appears within milliseconds. The heartbeat fires approximately every 15 seconds while an agent is working and distinguishes between an agent that is processing slowly and one that is genuinely hung. If a subprocess has been silent for more than two minutes, the TUI suggests typing /abort. This real-time observability is a significant quality-of-life improvement over systems that present a spinner with no indication of underlying activity.

Getting Started

The fastest path is the kickoff script, which copies the harness into a fresh timestamped directory, initializes a git repository, and launches the TUI:

# Optional: set defaults non-interactively by copying .env.example to .env
./kickoff.sh "A local-first journaling app that summarizes my week"

# Or omit the prompt and type your idea into the TUI:
./kickoff.sh

The kickoff directory is intentionally isolated: .clk/ holds all harness state, the project tree receives the agents’ output, and the original CLK source directory is never modified.

If you prefer the command-line interface without the TUI:

./scripts/install_local.sh           # creates .clk/venv and installs PyYAML
./scripts/clk init
./scripts/clk idea "A local-first journaling app that summarizes my week"
./scripts/clk plan
./scripts/clk run
./scripts/clk loop --max-iterations 10

Setting CLK_NO_TUI=true in your environment makes kickoff.sh fall back to the non-interactive pipeline automatically, which is the appropriate mode for CI/CD use.

Docker Deployment

CLK ships a Dockerfile for containerized use. The default mode is the interactive TUI, so you launch with -it. Kickoff directories are created under workspace/ inside the container; mounting a volume there preserves them across runs.

docker build -t clk .
docker volume create clk-workspace

# Interactive TUI, with your idea passed as an argument:
docker run --rm -it \
  -v clk-workspace:/app/workspace \
  clk "A local-first journaling app that summarizes my week"

# Non-interactive CI mode with Claude API key:
docker run --rm \
  -v clk-workspace:/app/workspace \
  -e CLK_NO_TUI=true \
  -e CLK_PROVIDER=claude \
  -e CLK_AUTH_MODE=apikey \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  clk "A local-first journaling app that summarizes my week"

A setup wizard (--setup) walks through every configuration option and writes the results to a bind-mounted .env file, which is appropriate for first-run configuration in both local and container contexts.

Safety and Reliability Mechanisms

CLK incorporates several safeguards designed to make autonomous operation safer without sacrificing the ability to take real action.

Failed work is never silently discarded. The Ralph loop uses git reset --hard <pre-iteration-sha> to revert failed iterations, and the pre-revert state is preserved in .clk/runs/ for inspection. The backup system in .clk/backups/ provides per-overwrite copies of every file the harness mutates, with backup filenames keyed to the run ID so you can trace a backup to the specific agent invocation that produced it.

Operations touching more than five files are logged with a warning before execution, and operations exceeding twenty-five files in a single response batch are refused entirely (the cap is configurable). This provides a meaningful check against an agent that attempts to restructure the entire project in one pass. The run action sanitizes shell commands before execution, rejecting sudo and recognizable destructive patterns.

All exceptions are caught and logged with a location-specific prefix string and a full traceback, consistent with the project’s exception-handling convention: print(f"[module:function] {e}") followed by traceback.print_exc(). This means that a provider failure, a YAML parse error, or a filesystem permission issue is always surfaced with enough context to diagnose the problem without reading the full run log.

Completion Criteria

CLK considers the project “done” when .clk/state/done.md exists. By convention, the harness creates this file only when the chief determines that the MVP runs locally, the test suite passes, the README explains setup, a deployment plan and checklist exist, and at least one user-facing interaction path has been implemented. These criteria are not enforced programmatically; they are encoded in the chief’s system prompt as the completion standard it reasons about when deciding whether to emit ACTION: done or propose another workflow cycle.

Customization

CLK is designed to be customized at every layer. Editing .clk/prompts/ changes individual agent behavior without touching harness code. Editing .clk/config/agents.json rebinds specific agents to specific providers, for example routing the engineer agent to claude while keeping researcher on a local ollama model. Adding new YAML files to .clk/config/workflows/ introduces new execution modes, accessible via clk run --workflow NAME or /run workflow_name in the TUI. Project-wide parameters including the supervise cycle cap, the recovery pass limit, the maximum dynamic role count, and the file-action batch limit are all configurable via clk configure --set key=value, which updates clk.config.json in place.

pi.dev Extension

CLK exposes /clk <idea> and /clk-abort commands if run with pi -e pi-extension/src/index.ts which starts a similar dispatch loop as that described here for the standalone tool.

Summary

The Cognitive Loop Kernel addresses a practical gap in the current landscape of agentic development tools: the need for a local-first, inspectable, provider-agnostic harness that can assemble a project-specific multi-agent team, execute real file operations under safety constraints, iterate toward completion through structured loops, and maintain a complete, human-readable audit trail throughout. By treating the workflow definition, agent roster, blackboard contents, and git history as first-class project artifacts, CLK makes the behavior of the multi-agent system legible and modifiable without requiring changes to the harness itself. The source is available on GitHub under the MIT License.

Motivation: Why Self-Host?

The short answer is control. When I work on grant-funded AI research, on student data in the context of my courses, or on institutional planning, I want to know exactly where inference is happening and what data is leaving my environment. The longer answer is pedagogical: I cannot credibly teach AI literacy, AI ethics, and responsible deployment if I have not made serious, hands-on architectural decisions myself. Running your own stack is humbling in the right ways.

There is also a strategic argument. As the open-source AI agent framework ecosystem matured through early 2026, it became clear that the layered architecture of these systems, separating the model layer, the orchestration layer, the tool-access layer, and the user-interface layer, was stabilizing into recognizable patterns. A well-designed self-hosted stack can plug into any of these layers without being locked to a single vendor. That flexibility is worth the setup cost.

Hardware: The Mini PC

The physical foundation of the stack is a mini PC running Linux Mint, which gives me a clean Debian-lineage environment with full access to the upstream Docker Engine repository and no virtualization layer between the container workloads and the host kernel. Everything runs directly on the host, which simplifies networking, volume permissions, and service lifecycle management considerably compared to hypervisor-based setups.

Installing Docker Engine

Linux Mint ships an older Docker build from the distribution mirror, so I install from the upstream Docker repository instead. The setup sequence is:

# Remove any distribution-packaged versions
sudo apt-get remove docker docker-engine docker.io containerd runc
 
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg lsb-release
 
# Add Docker's official GPG key
sudo mkdir -m 0755 -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
 
# Point the apt source at the Ubuntu codename that Mint is based on
echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo $UBUNTU_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
 
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
 
sudo docker run hello-world
sudo usermod -aG docker $USER
newgrp docker

The UBUNTU_CODENAME variable in the source line is the key detail for Mint: it resolves to the underlying Ubuntu release name rather than the Mint release name, which is what the Docker repository actually indexes.

Installing Ollama

Ollama runs as a native Linux service, not inside a container, which keeps model-weight I/O off the Docker networking path and avoids bind-mount overhead for the weight files:

curl -fsSL https://ollama.com/install.sh | sh
systemctl status ollama

Ollama listens on http://localhost:11434 by default and is reachable from within containers via --add-host=host.docker.internal:host-gateway, which every container in the stack declares. This flag is required on Linux Docker Engine; unlike Docker Desktop, the Linux engine does not inject host.docker.internal automatically.

Workspace Layout

All agent state lives under a single root in the home directory:

$HOME/agents/
├── workspace/              # Shared project files (all TUI tools mount here)
├── skills/core/            # Read-only skills package (mounted :ro)
├── litellm/                # LiteLLM config and Compose files
├── kilocode/home/          # KiloCode identity
├── opencode/home/          # opencode.ai identity
├── pi/home/                # pi.dev identity, models.json, settings.json
├── hermes/home/            # Hermes agent identity
├── gnhf/                   # Good Night Have Fun harness
├── open-design/            # Open Design app data and pi identity
├── commercial/             # Claude Code, Codex, Gemini CLI, Copilot, CCR, bash
├── mastra/data/            # Mastra SQLite database
├── a0/data/                # Agent Zero persistent user data
├── archon/data/            # Archon workflow state
├── ollama/data/            # Downloaded model weights (~/.ollama)
├── localai/                # LocalAI models/, backends/, config/
├── googleworkspacecli/     # Google Workspace CLI (gcloud/)
├── googleagentscli/        # Google ADK CLI
└── openwebui/data/         # Open WebUI persistent data

Creating the full tree is a one-liner drawn from the deploy script:

BASE="$HOME/agents"
mkdir -p \
  "$BASE/workspace" "$BASE/skills/core" "$BASE/litellm" \
  "$BASE/kilocode/home" "$BASE/opencode/home" "$BASE/pi/home" \
  "$BASE/hermes/home" "$BASE/ollama/data" \
  "$BASE/localai/models" "$BASE/localai/backends" "$BASE/localai/config" \
  "$BASE/mastra/data" "$BASE/openwebui/data" \
  "$BASE/commercial/claude/workspace" "$BASE/commercial/claude/home" \
  "$BASE/commercial/claude/npm" "$BASE/commercial/claude/config" \
  "$BASE/commercial/claude/cache" \
  "$BASE/googleworkspacecli/gcloud" \
  "$BASE/googleagentscli/data" "$BASE/googleagentscli/config" \
  "$BASE/googleagentscli/cache/uv" "$BASE/googleagentscli/cache/npm" \
  "$BASE/googleagentscli/evals" "$BASE/googleagentscli/logs" \
  "$BASE/archon/data" "$BASE/a0/data" \
  "$BASE/gnhf/home" "$BASE/gnhf/npm" "$BASE/gnhf/config" "$BASE/gnhf/cache" \
  "$BASE/open-design/data" "$BASE/open-design/pi"
echo "Directory tree created under $BASE"

The Core Design Principle: A Unified Model Gateway

The single most important architectural decision I made was to route all LLM inference through a single OpenAI-compatible endpoint rather than having each tool reach out to Ollama, Anthropic, or OpenRouter independently. I use LiteLLM for this. Every service in the stack sends its requests to http://localhost:4000/v1 with the bearer token sk-litellm-local. LiteLLM translates those requests to whatever backend is appropriate, whether a local Ollama model, a LocalAI GGUF endpoint, or an OpenRouter free-tier model, according to a YAML routing configuration.

model_list:
  - model_name: llama3
    litellm_params:
      model: ollama/llama3
      api_base: http://host.docker.internal:11434
 
  - model_name: qwen2.5-3b
    litellm_params:
      model: ollama/qwen2.5:3b
      api_base: http://host.docker.internal:11434
 
  - model_name: hermes3
    litellm_params:
      model: ollama/hermes3:8b
      api_base: http://host.docker.internal:11434
 
  - model_name: openrouter/auto
    litellm_params:
      model: openrouter/auto
      api_key: ${OPENROUTER_API_KEY}
      api_base: https://openrouter.ai/api/v1

The practical consequence is that changing a model, adding a provider, or adjusting routing requires editing one YAML file and restarting one service. No other container needs to know that anything changed. This is the same composability principle I teach in software engineering: minimize coupling, maximize cohesion.

Connecting a commercial CLI tool like Claude Code to the local stack requires only two environment variable exports:

export ANTHROPIC_BASE_URL=http://localhost:4000
export ANTHROPIC_API_KEY=sk-litellm-local

LiteLLM Deployment

LiteLLM runs as a Docker Compose service. The docker-compose.yml pulls the pre-built image; everything else is bind-mounted configuration.

# litellm/docker-compose.yml
version: "3.9"
services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm-${USER}
    restart: unless-stopped
    ports:
      - "4000:4000"
    volumes:
      - ./litellm_config.yaml:/app/config.yaml:ro
    env_file:
      - .env
    command: ["--config", "/app/config.yaml", "--port", "4000", "--num_workers", "2"]
    extra_hosts:
      - "host.docker.internal:host-gateway"

The .env file holds the master key and any cloud provider keys:

# litellm/.env
LITELLM_MASTER_KEY=sk-litellm-local
OPENROUTER_API_KEY=YOUR_OPENROUTER_API_KEY

Build and run scripts are minimal wrappers around Compose:

# litellm/build.sh — pull image, start, verify endpoint
cd "$HOME/agents/litellm"
docker compose pull
docker compose up -d
sleep 20
curl -s http://localhost:4000/models \
  -H "Authorization: Bearer sk-litellm-local" | python3 -m json.tool | head -20
 
# litellm/run.sh — start after reboot
cd "$HOME/agents/litellm" && docker compose up -d
 
# litellm/attach.sh — tail live logs
cd "$HOME/agents/litellm" && docker compose logs --tail=30 -f litellm-${USER}

Restart after a config change: cd $HOME/agents/litellm && docker compose down && docker compose up -d.

The Full Stack: Services and Ports

Local Inference: Ollama and LocalAI

The stack runs two local inference backends with distinct tradeoffs, and LiteLLM routes between them transparently based on model alias.

Ollama is the primary inference backend. Its systemd service model keeps it available before Docker is fully up, its model management CLI is clean, and its HTTP API is stable. The models I maintain are selected for RAM footprint first: phi4-mini, smollm2, gemma4:e2b, qwen2.5:1.5b, qwen2.5:3b, llama3, and hermes3:8b.

# ollama/run.sh
docker run -d \
  --name ollama-${USER} \
  --restart no \
  --add-host=host.docker.internal:host-gateway \
  -p 11434:11434 \
  -v "$HOME/agents/ollama/data:/root/.ollama" \
  ollama/ollama:latest
 
# Pull models after starting
for model in phi4-mini smollm2 "gemma4:e2b" "qwen2.5:1.5b" "qwen2.5:3b" llama3 "hermes3:8b"; do
  docker exec ollama-${USER} ollama pull "$model"
done

LocalAI (github.com/mudler/LocalAI) is the secondary inference backend, running on port 8080 behind an OpenAI-compatible API surface. It supports llama.cpp for text generation, whisper.cpp for speech transcription, and stable diffusion for image generation, all behind the same endpoint. LocalAI is organized around three bind-mounted directories: models/ holds GGUF weight files, backends/ holds compiled backend binaries, and config/ holds per-model YAML configuration. Note that the host directory is named config/ while the container mount path is /configuration; this asymmetry is intentional and must be preserved.

# localai/run.sh
docker run -d \
  --name localai-${USER} \
  --restart no \
  --add-host=host.docker.internal:host-gateway \
  -p 8080:8080 \
  -v "$HOME/agents/localai/models:/models" \
  -v "$HOME/agents/localai/backends:/backends" \
  -v "$HOME/agents/localai/config:/configuration" \
  localai/localai:latest

A per-model YAML config controls backend selection and context length:

# localai/config/phi4-mini.yaml
name: phi4-mini
backend: llama
parameters:
  model: phi-4-mini-instruct.Q4_K_M.gguf
  context_size: 8192
  threads: 8

Browser Frontend: Open WebUI

Open WebUI is the browser-based interface for direct LLM interaction, running on port 3000. It connects to Ollama directly and enumerates available models automatically. Its native MCP tool-calling support (version 0.4 and later) intercepts tool-call responses, dispatches them to registered MCP servers, and injects results back into the conversation.

# openwebui/run.sh
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v "$HOME/agents/openwebui/data:/app/backend/data" \
  --name open-webui-${USER} \
  ghcr.io/open-webui/open-webui:main

After launch, connect to LiteLLM via Admin Settings → Connections → OpenAI: set the URL to http://host.docker.internal:4000/v1 and the API key to sk-litellm-local. Models confirmed to work reliably with Open WebUI tool calling include hermes3:8b, llama3.1:8b, qwen2.5:7b, qwen2.5:14b, and mistral-nemo:12b.

Agentic CLI Tools: A Comparative Survey

By April 2026, a mature set of agentic coding CLI tools has emerged with distinct architectural philosophies, and I run all of them through the unified LiteLLM gateway. Each tool runs inside a dedicated Docker container with an identity bind mount, a shared workspace mount, and an optional skills mount. The sections below show the Dockerfile, build script, and run script for each.

Claude Code (Anthropic, Node.js) is the most fully featured in terms of built-in subagent support, MCP integration, and permission gate granularity. It uses CLAUDE.md files for project context and .claude/agents/ Markdown files for custom subagent definitions.

OpenAI Codex CLI (Rust) supports native multi-provider configuration through a TOML config file. Custom providers are defined as named sections:

model = "llama3.3:70b"
model_provider = "openwebui"
 
[model_providers.openwebui]
name = "Open WebUI"
base_url = "http://localhost:3000/openai"
env_key = "OPENWEBUI_API_KEY"

Gemini CLI (Google, Node.js) uses GEMINI.md files for project context and a three-tier discovery hierarchy for skills. Routing it through an OpenAI-compatible endpoint requires the open-gemini-cli fork, which injects an adapter layer that translates Gemini’s internal message format.

OpenCode (opencode.ai, Go) is the most flexible in terms of provider support, relying on the @ai-sdk/openai-compatible adapter to connect to any OpenAI-compatible backend:

{
  "provider": {
    "litellm": {
      "npm": "@ai-sdk/openai-compatible",
      "options": { "baseURL": "http://localhost:4000/v1" },
      "models": { "llama3": {}, "qwen2.5-3b": {}, "hermes3": {} }
    }
  }
}

Commercial Tools Deployment (Claude Code, Codex, Gemini CLI, Copilot, CCR, bash)

Claude Code, Codex, Gemini CLI, GitHub Copilot, the Claude Code Router, and a plain bash shell all share a single Docker image. The tool to launch is selected at runtime as an argument to run.sh. The bash option is a deliberately included escape hatch: it drops into an interactive shell inside the commercial-ai container with all identity and workspace volumes mounted, but without launching any AI tool. This is useful for inspecting the container environment, running scripts manually, debugging mount layouts, or staging files before invoking an AI tool in a separate session.

# commercial/Dockerfile
FROM node:22-bookworm
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    git curl ca-certificates ripgrep less nano vim \
    && rm -rf /var/lib/apt/lists/*
 
RUN npm install -g \
    @anthropic-ai/claude-code \
    @openai/codex \
    @google/gemini-cli \
    @github/copilot \
    @musistudio/claude-code-router
 
RUN mkdir -p /root/.claude-code-router
WORKDIR /workspace
CMD ["/bin/bash"]

The build.sh creates per-tool identity directories for all six options, including bash, so the directory layout is consistent regardless of which tool is invoked:

#!/usr/bin/env bash
set -euo pipefail
 
docker build -t commercial-ai:latest .
 
BASE_DIR="/home/bill/agents/commercial"
mkdir -p "${BASE_DIR}/workspace"
 
for tool in claude codex gemini copilot ccr bash; do
  mkdir -p \
    "${BASE_DIR}/${tool}/home" \
    "${BASE_DIR}/${tool}/npm" \
    "${BASE_DIR}/${tool}/config" \
    "${BASE_DIR}/${tool}/cache"
done

The run.sh dispatches on the tool name to set the API variable and CLI command. The bash case sets no API variable and uses /bin/bash as the command, so no credential prompt is issued and the container simply provides an interactive shell:

#!/usr/bin/env bash
set -euo pipefail
 
IMAGE="commercial-ai:latest"
BASE_DIR="/home/bill/agents/commercial"
CCR_CONFIG="${BASE_DIR}/ccr/config.json"
 
if [[ $# -ne 1 ]]; then
  echo "[run.sh] Usage: $0 {bash|claude|codex|gemini|copilot|ccr}"
  exit 1
fi
 
TOOL="$1"
EXTRA_ARGS=()
ENV_ARGS=()
 
case "$TOOL" in
  bash)
    API_VAR=""
    CLI_CMD="/bin/bash"
    ;;
  claude)
    API_VAR="ANTHROPIC_API_KEY"
    CLI_CMD="claude"
    ;;
  ccr)
    API_VAR="ANTHROPIC_API_KEY"
    CLI_CMD="ccr code"
    if [[ ! -f "${CCR_CONFIG}" ]]; then
      echo "[run.sh] CCR config not found at ${CCR_CONFIG}"
      echo "[run.sh] Create it before running with the ccr option."
      exit 1
    fi
    EXTRA_ARGS+=(-v "${CCR_CONFIG}:/home/agent/.claude-code-router/config.json:ro")
    ;;
  codex)
    API_VAR="OPENAI_API_KEY"
    CLI_CMD="codex"
    ;;
  gemini)
    API_VAR="GEMINI_API_KEY"
    CLI_CMD="gemini"
    ;;
  copilot)
    API_VAR="GITHUB_TOKEN"
    CLI_CMD="copilot"
    ;;
  *)
    echo "[run.sh] Invalid tool: $TOOL"
    echo "[run.sh] Valid options: bash | claude | codex | gemini | copilot | ccr"
    exit 1
    ;;
esac
 
TOOL_DIR="${BASE_DIR}/${TOOL}"
mkdir -p \
  "${BASE_DIR}/workspace" \
  "${TOOL_DIR}/home" \
  "${TOOL_DIR}/npm" \
  "${TOOL_DIR}/config" \
  "${TOOL_DIR}/cache"
 
if [[ -n "${API_VAR}" ]]; then
  if [[ -z "${!API_VAR:-}" ]]; then
    echo "[run.sh] ${API_VAR} is not set. Please enter it:"
    read -rsp ">>> " USER_KEY
    echo ""
    export "${API_VAR}=${USER_KEY}"
  fi
  ENV_ARGS+=("-e" "${API_VAR}=${!API_VAR}")
fi
 
docker run --rm -it \
  --name "commercial-${TOOL}-bill" \
  -e HOME="/home/agent" \
  "${ENV_ARGS[@]}" \
  -v "${BASE_DIR}/workspace:/workspace" \
  -v "${TOOL_DIR}/home:/home/agent" \
  -v "${TOOL_DIR}/npm:/home/agent/.npm" \
  -v "${TOOL_DIR}/config:/home/agent/.config" \
  -v "${TOOL_DIR}/cache:/home/agent/.cache" \
  "${EXTRA_ARGS[@]}" \
  -w /workspace \
  "${IMAGE}" ${CLI_CMD}

Invoking ./run.sh bash thus drops into the container with the full commercial identity environment present but no tool running, which makes it straightforward to inspect installed package versions, verify that volume mounts resolved correctly, or stage configuration files before running a tool. Because the bash identity directory (commercial/bash/home) is separate from all other tool identity directories, any modifications made in a shell session cannot bleed into a Claude Code or Codex session.

The ccr (Claude Code Router) variant additionally mounts its routing config read-only:

// commercial/ccr/config.json — routing table
{
  "Router": {
    "default":          "ollama,llama3:latest",
    "background":       "ollama,qwen2.5:1.5b",
    "think":            "ollama,gemma4:e2b",
    "longContext":      "openrouter,google/gemini-2.5-pro-exp-03-25:free",
    "longContextThreshold": 60000,
    "webSearch":        "openrouter,google/gemini-2.5-pro-exp-03-25:online"
  }
}

Switching the active model within a running Claude Code session is a single slash command: /model ollama,llama3:latest.

OpenCode Deployment

# opencode/Dockerfile
FROM node:20-bookworm-slim
 
RUN apt-get update \
    && apt-get install -y --no-install-recommends \
        curl ca-certificates git bash findutils \
    && rm -rf /var/lib/apt/lists/*
 
RUN curl -fsSL https://opencode.ai/install | bash \
    && mkdir -p /opt/opencode/bin \
    && cp "$(find /root -type f -name opencode | head -n 1)" /opt/opencode/bin/opencode \
    && chmod 755 /opt/opencode/bin/opencode
 
ENV PATH="/opt/opencode/bin:${PATH}"
ENV HOME=/home/opencode
VOLUME ["/workspace"]
WORKDIR /workspace
ENTRYPOINT ["/opt/opencode/bin/opencode"]

# opencode/build.sh
docker build -t opencode:local "$HOME/agents/opencode"
mkdir -p "$HOME/agents/opencode/home"
 
# opencode/run.sh
docker run --restart no -it \
  --name opencode-${USER} \
  --add-host=host.docker.internal:host-gateway \
  -v "$HOME/agents/opencode/home:/home/opencode" \
  -v "$HOME/agents/workspace:/workspace" \
  -v "$HOME/agents/skills/core:/app/skills/core:ro" \
  opencode:local
 
# opencode/attach.sh
docker start -ai opencode-${USER}

KiloCode (VS Code extension, Node.js) is the VS Code-native member of the survey. It brings the agentic loop into the editor rather than the terminal, with direct access to the VS Code language server for diagnostics, symbol navigation, and refactoring. Connecting it to LiteLLM is a one-field change in its settings JSON.

KiloCode Deployment

# kilocode/Dockerfile
FROM debian:bookworm-slim
 
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        ca-certificates git bash wget curl && \
    rm -rf /var/lib/apt/lists/*
 
ARG TARGETARCH=amd64
 
RUN ARCH=${TARGETARCH} && \
    if [ "$ARCH" = "arm64" ]; then ARCH="arm64"; else ARCH="x64"; fi && \
    wget -qO /tmp/kilo.tar.gz \
        "https://github.com/Kilo-Org/kilocode/releases/latest/download/kilo-linux-${ARCH}.tar.gz" && \
    tar -xzf /tmp/kilo.tar.gz -C /usr/local/bin && \
    chmod +x /usr/local/bin/kilo && \
    rm /tmp/kilo.tar.gz
 
VOLUME ["/workspace"]
WORKDIR /workspace
ENTRYPOINT ["kilo"]

# kilocode/build.sh
docker build -t kilocode:local "$HOME/agents/kilocode"
mkdir -p "$HOME/agents/kilocode/home"
chown -R $(id -u):$(id -g) "$HOME/agents/kilocode/home"
chmod -R u+rwX "$HOME/agents/kilocode/home"
 
# kilocode/run.sh
docker run --restart no -it \
  --user $(id -u):$(id -g) \
  --add-host=host.docker.internal:host-gateway \
  -e HOME=/home/kilo \
  -e XDG_CONFIG_HOME=/home/kilo/.config \
  -e XDG_DATA_HOME=/home/kilo/.local/share \
  -e XDG_CACHE_HOME=/home/kilo/.cache \
  --name kilocode-${USER} \
  -e TERM=xterm-256color \
  -v "$HOME/agents/kilocode/home:/home/kilo" \
  -v "$HOME/agents/workspace:/workspace" \
  -v "$HOME/agents/skills/core:/app/skills/core:ro" \
  kilocode:local
 
# kilocode/attach.sh
docker start -ai kilocode-${USER}

pi (pi.dev, Node.js) takes a deliberately minimal stance, omitting built-in MCP, plan mode, and permission gates in favor of a package-based extensibility model. It supports OpenRouter directly through a provider block in models.json, and NVIDIA NIM endpoints are equally accessible through the same mechanism. I reach for pi primarily for rapid exploratory work precisely because it does not impose an opinionated workflow.

Pi Deployment

# pi/Dockerfile
FROM node:22-bookworm-slim
 
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
    bash ca-certificates curl git openssh-client \
 && rm -rf /var/lib/apt/lists/*
 
RUN npm install -g @mariozechner/pi-coding-agent
 
ENV HOME=/home/pi-agent
VOLUME ["/workspace"]
WORKDIR /workspace
ENTRYPOINT ["pi"]

# pi/build.sh
docker build -t pi:local "$HOME/agents/pi"
mkdir -p "$HOME/agents/pi/home/.pi/agent"
 
# Write default models.json pointing at Ollama
cat > "$HOME/agents/pi/home/.pi/agent/models.json" << 'EOF'
{
  "providers": {
    "ollama": {
      "baseUrl": "http://host.docker.internal:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "qwen2.5:7b",
          "name": "Qwen 2.5 7B (Local)",
          "contextWindow": 32768,
          "maxTokens": 8192,
          "cost": { "input": 0, "output": 0 }
        }
      ]
    },
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "${OPENROUTER_API_KEY}",
      "models": [
        { "id": "google/gemini-2.5-pro-exp-03-25:free", "contextWindow": 1000000 },
        { "id": "meta-llama/llama-4-maverick:free",      "contextWindow": 128000  }
      ]
    }
  }
}
EOF
 
# pi/run.sh
docker run --restart no -it \
  --name pi-${USER} \
  --add-host=host.docker.internal:host-gateway \
  -e TERM=xterm-256color \
  -e OLLAMA_HOST="http://host.docker.internal:11434" \
  -e OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-YOUR_OPENROUTER_API_KEY}" \
  -v "$HOME/agents/pi/home:/home/pi-agent" \
  -v "$HOME/agents/workspace:/workspace" \
  -v "$HOME/agents/skills/core:/app/skills/core:ro" \
  pi:local
 
# pi/attach.sh
docker start -ai pi-${USER}

Hermes is a named agent identity maintained around Nous Research’s Hermes 3 model family. The hermes/home/ directory holds a configuration and prompt library tuned for Hermes 3’s specific instruction format and function-calling conventions. Because Hermes 3 handles structured output and tool-use with uncommon consistency, I route all tool-calling-heavy workloads to this identity.

Hermes Agent Deployment

# hermes/build.sh — probe first, then run
# Confirm the image's runtime user and home directory before committing a mount path:
docker pull nousresearch/hermes-agent:latest
docker run --rm --entrypoint sh nousresearch/hermes-agent:latest \
  -c 'id && echo HOME=$HOME'
 
mkdir -p "$HOME/agents/hermes/home"
 
# hermes/run.sh
# Always launch with -it — running detached causes immediate exit
docker run --restart no -it \
  --name hermes-${USER} \
  --add-host=host.docker.internal:host-gateway \
  -e TERM=xterm-256color \
  -v "$HOME/agents/hermes/home:/home/hermes/.hermes" \
  -v "$HOME/agents/workspace:/workspace" \
  nousresearch/hermes-agent:latest
 
# hermes/attach.sh
docker start -ai hermes-${USER}

GNHF (Good Night Have Fun) is the task-bounded harness I use when I want a single-purpose agent that executes a defined workflow, reports results, and stops. The name is a ham radio sign-off, which fits its character: polite, brief, and does exactly what it was asked to do. Unlike Claude Code or pi, which are interactive and session-oriented, GNHF takes a task description and a workspace path as inputs, executes against the LiteLLM gateway, writes its outputs to the workspace, and exits.

GNHF Deployment

GNHF requires a Dockerfile placed at $HOME/agents/gnhf/Dockerfile before build.sh can execute, because the gnhf binary distribution mechanism is external to this stack. A representative starting point:

# gnhf/Dockerfile — adapt to your gnhf binary distribution
FROM node:22-bookworm
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    git curl ca-certificates ripgrep less \
    && rm -rf /var/lib/apt/lists/*
 
# Install the agent CLIs that gnhf wraps
RUN npm install -g \
    @anthropic-ai/claude-code \
    @openai/codex \
    @github/copilot
 
# Install gnhf — adapt to your distribution method:
# RUN npm install -g gnhf
# or: COPY gnhf /usr/local/bin/gnhf && chmod +x /usr/local/bin/gnhf
 
WORKDIR /workspace
CMD ["/bin/bash"]

# gnhf/build.sh
if [[ ! -f "$HOME/agents/gnhf/Dockerfile" ]]; then
  echo "ERROR: place Dockerfile in $HOME/agents/gnhf/ first"; exit 1
fi
docker build -t gnhf:latest "$HOME/agents/gnhf"
 
# gnhf/run.sh — key arguments shown; full script handles key resolution per agent
# Usage: ./run.sh --agent <codex|claude|copilot> --repo <path> \
#                 [--max-iterations N] [--max-tokens N] "task description"
docker run --rm -it \
  --name "gnhf-${AGENT}-${USER}" \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-YOUR_ANTHROPIC_API_KEY}" \
  -e HOME="/home/agent" \
  -v "$HOME/agents/workspace:/workspace" \
  -v "$HOME/agents/gnhf/home:/home/agent" \
  -v "$HOME/agents/gnhf/npm:/home/agent/.npm" \
  -v "$HOME/agents/gnhf/config:/home/agent/.config" \
  -v "$HOME/agents/gnhf/cache:/home/agent/.cache" \
  gnhf:latest \
  bash -lc '
    cd "$1" &&
    git config --global --add safe.directory "$1" &&
    shift && exec "$@"
  ' _ "${REPO_PATH}" gnhf --agent "${AGENT}" "${PROMPT}"

All six tools use project context files (CLAUDE.md, AGENTS.md, GEMINI.md) to provide persistent project instructions without consuming prompt tokens on every turn, and all six are converging on MCP as the standard for tool integration.

The Google Ecosystem: Agents CLI and Workspace CLI

Two Google-specific tools occupy their own tier in the stack, with independent container identities and a shared philosophy of treating Google’s API surface as a set of agent-accessible tools.

Google Agents CLI is the command-line interface for Google’s Agent Development Kit (ADK), a Python framework for building multi-agent systems that run on Google’s infrastructure and interact with Gemini models. The uv cache indicates a Python-heavy dependency footprint, the evals/ directory holds evaluation datasets and result logs, and the container runs as a non-root user to match the bind-mounted volume permissions.

Google Agents CLI Deployment

# googleagentscli/Dockerfile
FROM python:3.12-slim
 
RUN apt-get update && apt-get install -y --no-install-recommends \
        ca-certificates curl git gnupg lsb-release unzip wget \
        jq vim less procps build-essential \
    && rm -rf /var/lib/apt/lists/*
 
RUN curl -fsSL https://deb.nodesource.com/setup_lts.x | bash - \
    && apt-get install -y --no-install-recommends nodejs \
    && rm -rf /var/lib/apt/lists/*
 
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
 
# Google Cloud SDK
RUN echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] \
        https://packages.cloud.google.com/apt cloud-sdk main" \
        | tee /etc/apt/sources.list.d/google-cloud-sdk.list \
    && curl -fsSL https://packages.cloud.google.com/apt/doc/apt-key.gpg \
        | gpg --dearmor -o /usr/share/keyrings/cloud.google.gpg \
    && apt-get update && apt-get install -y --no-install-recommends google-cloud-cli \
    && rm -rf /var/lib/apt/lists/*
 
RUN groupadd -g 1000 agent && useradd -m -u 1000 -g agent -s /bin/bash agent
 
ENV UV_TOOL_DIR=/usr/local/uv-tools
ENV PATH="${UV_TOOL_DIR}/bin:${PATH}"
 
RUN uv tool install google-agents-cli && chown -R agent:agent "${UV_TOOL_DIR}"
 
RUN mkdir -p /workspace /home/agent/.config/agents-cli /home/agent/.config/gcloud \
        /home/agent/.cache/uv /home/agent/.cache/npm /home/agent/evals /home/agent/logs \
    && chown -R agent:agent /workspace /home/agent/.config /home/agent/.cache \
        /home/agent/evals /home/agent/logs
 
USER agent
WORKDIR /workspace
CMD ["sleep", "infinity"]

# googleagentscli/build.sh
docker build --progress=plain -t google-agents-cli:local \
  "$HOME/agents/googleagentscli"
 
# googleagentscli/run.sh — starts detached; exec in with attach.sh
GCLOUD_MOUNT=()
[[ -d "$HOME/.config/gcloud" ]] && \
  GCLOUD_MOUNT=(-v "$HOME/.config/gcloud:/home/agent/.config/gcloud:ro")
 
docker run \
  --detach \
  --name "googleagentscli-${USER}" \
  --restart unless-stopped \
  --add-host=host.docker.internal:host-gateway \
  -v "$HOME/agents/googleagentscli/data:/workspace" \
  -v "$HOME/agents/googleagentscli/config:/home/agent/.config/agents-cli" \
  -v "$HOME/agents/googleagentscli/cache/uv:/home/agent/.cache/uv" \
  -v "$HOME/agents/googleagentscli/cache/npm:/home/agent/.cache/npm" \
  -v "$HOME/agents/googleagentscli/evals:/home/agent/evals" \
  -v "$HOME/agents/googleagentscli/logs:/home/agent/logs" \
  "${GCLOUD_MOUNT[@]}" \
  -e GOOGLE_API_KEY="${GOOGLE_API_KEY:-YOUR_GOOGLE_API_KEY}" \
  --workdir /workspace \
  google-agents-cli:local
 
# googleagentscli/attach.sh
docker exec -it --user agent --workdir /workspace \
  "googleagentscli-${USER}" bash --login

Post-launch authentication: Option A (AI Studio key, no Cloud billing) is docker exec -it googleagentscli-${USER} agents-cli login. Option B (Google Cloud ADC for production workloads) requires running gcloud auth application-default login on the host machine; the run.sh mounts ~/.config/gcloud read-only into the container automatically.

Google Workspace CLI is a containerized gcloud environment configured with the scopes necessary to drive the Google Workspace APIs programmatically: Gmail, Drive, Calendar, Sheets, and Docs. Authenticate once inside the container; the bind-mounted credentials directory persists across container recreations.

Google Workspace CLI Deployment

# googleworkspacecli/run.sh
docker run --restart no -it \
  --name gworkspace-${USER} \
  --add-host=host.docker.internal:host-gateway \
  -v "$HOME/agents/googleworkspacecli/gcloud:/root/.config/gcloud" \
  -v "$HOME/agents/workspace:/workspace" \
  google/cloud-sdk:slim \
  bash
 
# Inside container (first time only):
# gcloud auth login
# gcloud config set project YOUR_PROJECT_ID
 
# googleworkspacecli/attach.sh
docker start -ai gworkspace-${USER}

The authentication separation between the Workspace CLI container and the rest of the stack is intentional: the container that holds the Google credentials never has access to the project workspace or to any other agent’s identity directory. Data flows through the workspace volume only.

Agent Frameworks: Agent Zero, Archon, and Mastra

The stack runs three agent frameworks that occupy distinct positions on the spectrum from fully autonomous to fully programmable.

Agent Zero

Agent Zero is the most autonomous framework in the stack, designed around the premise that the agent should be able to self-improve its own instructions and tools over the course of a session. It runs as a web UI on port 8081 and exposes a chat interface backed by a hierarchical agent system where the primary agent can spawn specialized subagents. The persistent state in a0/data/ includes the agent’s memory bank, its accumulated tool library, and its evolving system prompt, all of which carry forward across container restarts.

# a0/build.sh
docker pull agent0ai/agent-zero
mkdir -p "$HOME/agents/a0/data"
 
# a0/run.sh
docker run -d \
  --name "a0-${USER}" \
  --restart no \
  --add-host=host.docker.internal:host-gateway \
  -p 8081:80 \
  -v "$HOME/agents/a0/data:/a0/usr" \
  agent0ai/agent-zero
 
# a0/attach.sh — tail live logs (Ctrl+C safe; container keeps running)
docker logs --follow --timestamps "a0-${USER}"

Open http://localhost:8081 in a browser after the container starts.

Archon

Archon occupies a meta-level in the stack: it is an agent framework whose purpose is to help build other agent frameworks. Its Streamlit-based UI presents a development environment where I describe the agent I want to build in natural language, and Archon generates the scaffolding, tool definitions, system prompt, and evaluation harness for that agent. Archon-generated agents are configured at generation time to use the LiteLLM endpoint, so they enter the stack already wired to the unified gateway without any post-generation modification.

# archon/build.sh
docker pull ghcr.io/coleam00/archon:latest
mkdir -p "$HOME/agents/archon/data/workflows"
 
# archon/data/config.yaml — default model routing
cat > "$HOME/agents/archon/data/config.yaml" << 'EOF'
assistant: pi
assistants:
  pi:
    provider: openrouter
    model: openrouter/openrouter/free
EOF
 
# archon/run.sh — ephemeral (--rm); exits after task
[[ -z "${OPENROUTER_API_KEY:-}" ]] && \
  { echo "ERROR: OPENROUTER_API_KEY not set"; exit 1; }
 
docker run --rm \
  --name "archon-${USER}" \
  --user "$(id -u):$(id -g)" \
  -v "$HOME/agents/workspace:/home/bun/.archon/workspaces" \
  -v "$HOME/agents/archon/data:/home/bun/.archon" \
  -p 3090:3090 \
  -e OPENROUTER_API_KEY="${OPENROUTER_API_KEY}" \
  -e DEFAULT_AI_ASSISTANT=pi \
  ghcr.io/coleam00/archon:latest workflow list

Mastra

Mastra is a TypeScript-based AI agent framework that runs as a Docker Compose service exposing a REST API and a Studio UI on port 4111. It uses LibSQL for persistent conversation history, meaning that agent memory survives container restarts. Mastra occupies the programmable end of the spectrum: rather than autonomous self-direction, it provides a typed API for defining agents, tools, workflows, and memory retrievers in TypeScript.

The Mastra image is a multi-stage build. Critically, it handles the instrumentation.mjs file conditionally, since its presence varies across Mastra version upgrades.

# mastra/Dockerfile (multi-stage)
FROM node:22-alpine AS builder
WORKDIR /app
RUN apk add --no-cache gcompat
COPY package*.json ./
RUN npm install
COPY tsconfig*.json ./
COPY src ./src
RUN npx mastra build
 
FROM node:22-alpine AS runner
WORKDIR /app
RUN apk add --no-cache gcompat wget
RUN addgroup -g 1001 -S nodejs && adduser -S mastra -u 1001
COPY --from=builder --chown=mastra:nodejs /app/.mastra/output ./.mastra/output
COPY --from=builder --chown=mastra:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=mastra:nodejs /app/package.json ./package.json
RUN mkdir -p /app/data && chown mastra:nodejs /app/data
USER mastra
ENV PORT=4111
ENV NODE_ENV=production
ENV DATABASE_URL="file:/app/data/mastra.db"
EXPOSE 4111
HEALTHCHECK --interval=30s --timeout=10s --start-period=20s --retries=3 \
    CMD wget -qO- http://localhost:4111/api > /dev/null || exit 1
# Conditional instrumentation: works across Mastra versions
CMD ["sh", "-c", "if [ -f .mastra/output/instrumentation.mjs ]; then \
  node --import=./.mastra/output/instrumentation.mjs .mastra/output/index.mjs; \
  else node .mastra/output/index.mjs; fi"]

The agent definition is deliberately minimal:

// src/mastra/agents/assistant.ts
import { Agent } from "@mastra/core/agent";
 
export const assistant = new Agent({
  name: "assistant",
  instructions: "You are a helpful, concise, and accurate assistant.",
  model: "openrouter/meta-llama/llama-3.1-8b-instruct:free",
  // Other free-tier options:
  // openrouter/mistralai/mistral-7b-instruct:free
  // openrouter/google/gemma-3-12b-it:free
});

# mastra/docker-compose.yml
services:
  mastra:
    build:
      context: .
      dockerfile: Dockerfile
    container_name: mastra-${USER}
    ports:
      - "4111:4111"
    environment:
      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
      NODE_ENV: production
      DATABASE_URL: "file:/app/data/mastra.db"
    volumes:
      - /home/${USER}/agents/mastra/data:/app/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:4111/api"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 20s

# mastra/build.sh — self-contained; creates src files if absent, prompts for key
cd "$HOME/agents/mastra"
docker compose up --build -d
 
# mastra/run.sh — start after reboot without rebuild
cd "$HOME/agents/mastra" && docker compose up -d
 
# mastra/attach.sh — tail live logs
docker logs --follow --timestamps "mastra-${USER}"

The agent server exposes a standard REST endpoint:

curl -X POST http://localhost:4111/api/agents/assistant/generate \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Summarize this document."}]}'

Open Design: Collaborative Canvas with Embedded Agent

Open Design is a web-based collaborative design canvas with an embedded pi coding agent, running on port 5173. It is the visual layer of the stack, useful for design work where the agent can read and modify the canvas state directly. The pi identity directory is separate from the main pi tool identity, so Open Design’s agent configuration does not interfere with standalone pi sessions.

Open Design Deployment

# open-design/Dockerfile
FROM node:24-bookworm
 
ARG OPEN_DESIGN_REPO=https://github.com/nexu-io/open-design.git
ARG OPEN_DESIGN_REF=main
 
ENV APP_DIR=/opt/open-design
ENV PNPM_HOME=/root/.local/share/pnpm
ENV PATH=/root/.local/share/pnpm:/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin:/bin
ENV PORT=5173
ENV HOST=0.0.0.0
ENV OD_HOST=0.0.0.0
ENV OD_ALLOWED_DEV_ORIGINS=127.0.0.1,localhost
 
RUN apt-get update && apt-get install -y --no-install-recommends \
    git ca-certificates curl bash python3 \
    && rm -rf /var/lib/apt/lists/*
 
RUN corepack enable
RUN npm install -g @mariozechner/pi-coding-agent
 
RUN git clone --branch "${OPEN_DESIGN_REF}" --depth 1 \
    "${OPEN_DESIGN_REPO}" "${APP_DIR}"
 
WORKDIR ${APP_DIR}
 
# Patch next.config.ts to accept OD_ALLOWED_DEV_ORIGINS from environment
RUN python3 - << 'PY'
from pathlib import Path
p = Path("apps/web/next.config.ts")
s = p.read_text()
old = "allowedDevOrigins: ['127.0.0.1'],"
new = """allowedDevOrigins: (
    process.env.OD_ALLOWED_DEV_ORIGINS
      ? process.env.OD_ALLOWED_DEV_ORIGINS.split(',').map((s) => s.trim()).filter(Boolean)
      : ['127.0.0.1']
  ),"""
if old not in s:
    raise SystemExit("Could not find allowedDevOrigins line")
p.write_text(s.replace(old, new))
PY
 
RUN corepack pnpm --version && pnpm install
 
EXPOSE 5173
CMD ["pnpm", "tools-dev", "run", "web", "--web-port", "5173"]

# open-design/build.sh
docker build -t open-design-pi "$HOME/agents/open-design"
mkdir -p "$HOME/agents/open-design/data"
mkdir -p "$HOME/agents/open-design/pi"
 
# First-time pi setup (run once to authenticate)
docker run --rm -it \
  -v "$HOME/agents/open-design/pi:/root/.pi" \
  open-design-pi \
  pi
# Inside pi session: /login
 
# open-design/run.sh
# OD_ALLOWED_DEV_ORIGINS must match the IP the browser uses to reach the container
docker run --rm -it \
  --name open-design-${USER} \
  -e "OD_ALLOWED_DEV_ORIGINS=YOUR_HOST_IP" \
  -p 5173:5173 \
  -v "$HOME/agents/open-design/data:/opt/open-design/.od" \
  -v "$HOME/agents/open-design/pi:/root/.pi" \
  open-design-pi

Open the canvas at http://YOUR_HOST_IP:5173. OD_ALLOWED_DEV_ORIGINS must match the IP address the browser uses to reach the container. To detect it automatically, substitute $(hostname -I | awk '{print $1}') for the hardcoded value.

Docker Volume Architecture: Identity, Workspace, Skills

One of the more carefully considered design decisions in this stack is the separation of Docker bind mounts into four independent tiers, which I call identity, workspace, skills, and tool data. This separation means that swapping a user identity, adding a skills package, or destroying an experimental container affects only its own tier; the other three are untouched.

The identity hot-swap pattern is simple enough to describe in three commands: stop the container, remove it (volumes are untouched), and rerun with a different home/ path. The workspace and skills mount points are identical in both invocations. This makes it straightforward to work on the same project files under different API key contexts or with different tool configurations.

Permission repair across containers with differing internal UID/GID values is handled by a disposable Alpine container:

docker run --rm \
  -v "$HOME/agents/some-tool/home:/mnt/target" \
  alpine \
  chown -R 1000:1000 /mnt/target

Container-Isolated Tool Invocation

One of the more practically useful habits I have developed with this stack is running agentic CLI tools inside dedicated Docker containers rather than installing them to my host user environment. The motivation is threefold: environment isolation, workspace scope control, and plugin sandboxing.

Workspace scope control is where the bind-mount architecture pays its most direct dividend. Rather than giving a tool access to the entire home filesystem, I mount only the specific project directories I want it to operate on:

docker run --rm -it \
  --add-host=host.docker.internal:host-gateway \
  -e ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-YOUR_ANTHROPIC_API_KEY}" \
  -v "$HOME/agents/commercial/claude/home:/home/agent" \
  -v "$HOME/projects/project-alpha:/workspace/project-alpha" \
  -v "$HOME/projects/project-beta:/workspace/project-beta" \
  -w /workspace/project-alpha \
  commercial-ai:latest claude

From inside the container, the agent sees exactly two project directories and nothing else. For work involving student data or grant-sensitive materials, this mount-scoping discipline is not optional; it is the architectural enforcement of the data minimization principle.

Plugin sandboxing makes it practical to evaluate new tools without risk. I can install an untrusted npm package, register a new MCP server, or try an experimental integration inside an ephemeral container with a scratch identity directory, observe its behavior against a scoped workspace mount, and discard the container entirely if I decide against it. The two-stage pattern, scratch evaluation followed by deliberate promotion to the production identity directory, is something the tiered bind-mount architecture makes nearly effortless.

The Extended Ecosystem: Containerized Evaluation of AI Tools

The stack described above is not a closed list. One of the structural advantages of the containerized, mount-scoped architecture is that any new AI tool can be evaluated, and subsequently adopted or discarded, without touching host state, leaking credentials, or requiring destructive cleanup. The evaluation pattern is consistent: build a throw-away image that installs the candidate tool and any dependencies it requires; run a container with a scratch identity directory and a scoped workspace mount containing only the project data relevant to the evaluation task; observe behavior against a free or low-cost model routed through LiteLLM; and either promote the configuration to a named identity directory or docker rmi the image and move on. What follows is a survey of tools I use or actively monitor, each of which fits neatly into this workflow.

Fabric

Fabric (Go) is an AI augmentation framework built around the concept of patterns, which are markdown-formatted system prompt templates stored in ~/.config/fabric/patterns/. Rather than a conversational agent, Fabric is a UNIX-pipeline-oriented tool: it reads from stdin or a file, applies a named pattern as the system prompt, and writes the model’s response to stdout. This makes it composable with every other shell tool by design. Because Fabric speaks to any OpenAI-compatible endpoint, it integrates with the LiteLLM gateway through a single environment variable, OPENAI_BASE_URL=http://localhost:4000/v1, and is well-suited to free-model operation for batch summarization, extraction, and classification tasks. The container footprint is minimal: the Go binary, the patterns directory bind-mounted from ~/.config/fabric/patterns, and a workspace volume.

AnythingLLM

AnythingLLM is a full-stack application that provides document ingestion, vector storage, and retrieval-augmented generation through a browser-based interface, all self-hostable and all pointing at whatever OpenAI-compatible endpoint you configure. Unlike Open WebUI, which is primarily a chat interface to models you have already pulled, AnythingLLM is organized around workspaces that each maintain their own document corpus and retrieval context. This makes it the most natural comparison point for evaluating RAG pipeline quality, including chunking strategies and retrieval configurations, against the same local models without committing to a production indexing infrastructure. It runs as a single Docker container and connects to LiteLLM without modification.

AutoGPT

AutoGPT is one of the original autonomous agent frameworks, now significantly matured into a platform with a visual workflow builder and a marketplace of pre-built agents. Its architectural evolution mirrors the broader field: the early single-agent loop has been replaced by a multi-agent orchestration model where specialized agents collaborate on subtasks. AutoGPT’s containerized deployment is well-documented, and its use of a PostgreSQL backend for persistent agent state means that evaluation sessions survive container restarts. I evaluate AutoGPT primarily for its workflow builder, which provides a visual alternative to writing agent orchestration code by hand, and because its agent marketplace offers a useful inventory of community-developed task patterns.

CLI-Anything

CLI-Anything is a natural-language shell interface that translates plain-English task descriptions into shell command sequences, explains the commands it generates before executing them, and allows interactive refinement. The evaluation pattern is particularly straightforward: mount a scratch workspace, describe a file manipulation or build task in natural language, and assess the fidelity of the generated commands against the intent. Because CLI-Anything operates at the shell command level rather than the source code level, it is usable with substantially smaller models than coding-focused tools, which makes it a good candidate for free-tier or small local model evaluation.

Google Antigravity

Google Antigravity is an experimental framework for rapid agent prototyping that provides a higher-level abstraction layer over the Google Agent Development Kit described above. It is oriented toward fast iteration on multi-agent system designs, with an emphasis on making architectural experiments cheap to run and discard, which maps naturally onto the containerized evaluation philosophy of this stack. I use it alongside the Google Agents CLI container, sharing the same workspace volume but maintaining a separate identity directory so that Antigravity’s experimental state does not contaminate the production ADK configuration.

T3 Code

T3 Code is a code generation tool that applies Theo Browne’s T3 stack architectural preferences (TypeScript, tRPC, Tailwind, Prisma) to AI-assisted scaffolding. Its opinionated output is both a strength and a constraint: the generated code is immediately coherent within the T3 ecosystem but requires deliberate adaptation outside it. I evaluate it in a container against a workspace containing a greenfield TypeScript project, routed through LiteLLM, and find it most useful as a rapid scaffolding baseline rather than a continuous coding companion.

Paperclip

Paperclip is a document-aware coding assistant that maintains a live index of a project’s files and surfaces relevant context into the model’s prompt automatically as the conversation evolves. The document-indexing architecture distinguishes it from tools that rely on the user to provide context explicitly: Paperclip’s retrieval layer operates continuously in the background, which makes it well-suited to exploration of unfamiliar codebases. Containerized evaluation against a read-only mount of a target codebase is a clean pattern: the index lives in the scratch identity directory, the codebase is mounted read-only, and the entire evaluation state is discardable.

Open-Source Cowork Alternatives in the Ecosystem

The tools already described in dedicated sections below, including OpenWork, OpenCoworkAI, and Multica, represent the most directly Cowork-comparable options in the ecosystem, but several adjacent tools occupy related positions.

Accomplish takes a “BYO-AI” stance, functioning as the orchestration layer (hands and eyes) while allowing model selection, supporting OpenAI, Anthropic, Google, and Ollama backends without lock-in.

Kuse Cowork implements the agent runtime in Rust with Docker-based sandboxing built into the design, which makes its security boundary properties particularly legible from the perspective of this stack’s threat model.

The Containerization Argument

The tooling landscape I have described, spanning fabric, AnythingLLM, AutoGPT, CLI-Anything, Antigravity, T3 Code, Paperclip, and the Cowork-adjacent frameworks, shares a property that makes the containerized evaluation pattern especially productive: nearly all of them support connection to a popular API-compatible backend (OpenAI, Anthropic, or a generic OpenAI-compatible endpoint), and nearly all of them can be pointed at free-tier models on OpenRouter or at local Ollama models with no modification beyond a base URL. This means that a feasibility evaluation of any tool in the list, assessing whether its interaction model, output quality, and integration characteristics are worth the effort of a production deployment, can be conducted at near-zero cost: no paid API usage, no host-level installation, no persistent state that requires cleanup. The directory structure is created by build.sh, the container runs against a scoped workspace mount, the evaluation task executes against a free model, and the result determines whether to invest in a full identity directory configuration or to docker rmi and move on. This evaluation-first discipline is, I would argue, the appropriate epistemological stance toward a tool ecosystem that is evolving faster than any individual practitioner can track.

Open-Source Cowork Alternatives

Anthropic’s Claude Cowork launch in January 2026 triggered a vigorous open-source response. I track several of the resulting projects.

OpenWork is the most actively developed, functioning as a control surface for agentic workflows with hot-reloadable skills, session management, and SSE event stream subscriptions. It is ejectable to OpenCode, which provides a meaningful portability guarantee.

OpenWork Deployment

# openwork/Dockerfile
FROM node:22-bookworm-slim
 
ARG OPENWORK_ORCHESTRATOR_VERSION=latest
 
RUN apt-get update \
 && apt-get install -y --no-install-recommends \
    ca-certificates curl git tar unzip \
 && rm -rf /var/lib/apt/lists/*
 
RUN npm install -g "openwork-orchestrator@${OPENWORK_ORCHESTRATOR_VERSION}"
 
ENV OPENWORK_DATA_DIR=/data/openwork-orchestrator
ENV OPENWORK_SIDECAR_DIR=/data/sidecars
ENV OPENWORK_WORKSPACE=/workspace
 
EXPOSE 8787
VOLUME ["/workspace", "/data"]
 
CMD ["openwork", "serve", "--workspace", "/workspace", "--remote-access", \
     "--openwork-port", "8787", "--opencode-host", "127.0.0.1", \
     "--opencode-port", "4096", "--connect-host", "127.0.0.1", \
     "--cors", "*", "--approval", "manual", "--no-opencode-router"]

# openwork/build.sh
docker build -t openwork:local "$HOME/agents/openwork"
mkdir -p "$HOME/agents/openwork/workspace" "$HOME/agents/openwork/data"
 
# openwork/run.sh
docker run -it \
  --restart no \
  --add-host=host.docker.internal:host-gateway \
  -p 8787:8787 \
  -v "$HOME/agents/openwork/workspace:/workspace" \
  -v "$HOME/agents/openwork/data:/data" \
  -e OPENWORK_TOKEN=dev-token \
  -e OPENWORK_HOST_TOKEN=dev-host-token \
  --name openwork-${USER} \
  openwork:local
 
# openwork/attach.sh
docker start -ai openwork-${USER}

Accomplish takes a “BYO-AI” stance, functioning as the orchestration layer (hands and eyes) while allowing model selection, supporting OpenAI, Anthropic, Google, and Ollama backends without lock-in. Kuse Cowork implements the agent runtime in Rust with Docker-based sandboxing. OpenCoworkAI explicitly commits to VM/bwrap isolation and checkpoint-rollback capability.

Multica occupies a different conceptual position as a managed agents platform rather than a desktop agent. It assigns issues to AI agents as you would assign them to human teammates, and it implements skill compounding: when an agent completes a task successfully, the solution is saved as a reusable skill that future tasks can leverage. This maps interestingly onto organizational learning theory, though a thoughtful critique in the project’s issue tracker notes that the human-management metaphor may be insufficient for genuinely autonomous AI orchestration at scale. I find this a productive tension worth thinking about seriously.

MCP Servers: Extending the Stack with Custom Tools

The Model Context Protocol (MCP), introduced by Anthropic in late 2024, defines how AI assistants communicate with external tools through four primitive types: tools (callable functions), resources (readable data streams), prompts (reusable templates), and sampling (delegated inference requests). Running MCP servers in Docker and connecting them to the local stack over a shared external network is straightforward.

docker network create mcp-shared

With this network in place, any container that declares mcp-shared as an external network can reach an MCP server at its container DNS name, such as http://mcp-bibliography:8000/mcp, without host port exposure. For backends that use OpenAI function-calling format rather than MCP’s JSON-RPC protocol, a thin Flask adapter service translates between the two on startup:

def mcp_post(method: str, params: dict, req_id: int = 1) -> dict:
    payload = json.dumps({
        "jsonrpc": "2.0", "id": req_id,
        "method": method, "params": params
    }).encode()
    req = urllib.request.Request(
        MCP_URL, data=payload,
        headers={"Content-Type": "application/json"}, method="POST"
    )
    with urllib.request.urlopen(req, timeout=10) as r:
        return json.loads(r.read())

OpenRouter: A Cloud Model Interface

OpenRouter serves as the cloud model interface for tasks I route away from local inference. It exposes multiple model providers through an OpenAI-compatible API surface, so the same client code that talks to the local LiteLLM gateway can talk to OpenRouter without modification. Model identifiers follow a provider-qualified format:

anthropic/claude-3-opus
openai/gpt-4o
mistralai/mixtral-8x7b
meta-llama/llama-3-70b-instruct

The free-tier model list changes, but as of early 2026 includes Gemini 2.5 Pro, DeepSeek Chat v3.5, and LLaMA 4 Maverick. I use OpenRouter as a fallback in the Mastra agent server, as the primary cloud provider for pi, and as the escalation path from GNHF when a batch task exceeds local model capability. All API key management is handled through environment variables; no key is ever written into a container image.

Reproducibility: The One-Shot Deploy Script

The entire stack, including all Dockerfiles, helper scripts, LiteLLM configuration, Mastra project files, and the directory tree, is generated by a single bash script called deploy-agents.sh. Running this script on a new machine, after providing the necessary API keys, produces a fully functional environment covering all the services described above with no manual steps (except placing a Dockerfile in gnhf/ for the task-bounded harness).

The script follows a fixed sequence: create the directory tree; write Dockerfiles for each custom image; write LiteLLM, LocalAI, and CCR configs; write Mastra project files; write GNHF task modules; write Agent Zero and Archon startup scripts; build custom images; clone and build OpenClaude; pull pre-built images; and finally start all daemon containers. This design means the script itself is the documentation, and any configuration drift between machines is detected by diffing the generated files against a known-good reference.

Publishing a custom Docker image to GitHub Container Registry follows the same minimal GitHub Actions pattern:

- uses: docker/login-action@v3
  with:
    registry: ghcr.io
    username: $
    password: $
 
- uses: docker/build-push-action@v6
  with:
    context: .
    push: true
    tags: $

After the workflow runs, making the resulting package public in the GitHub package settings allows anyone to docker pull ghcr.io/yourusername/yourrepo:main without further configuration.

Model Selection Notes

A few observations on local model selection from operational experience. For the think-heavy routing slot I use gemma4:e2b; for lightweight background tasks such as file summarization and classification I use qwen2.5:1.5b; for tool-calling workflows in Open WebUI and via the Hermes agent identity I use hermes3:8b; for general interactive sessions I use llama3. The selection criteria are principally RAM footprint and whether the model’s function-calling format is well-supported by the tool in question.

I took the following steps for this setup:

1. Obtain and use a 44net IP allocation via 44net Connect
2. Set up a Raspberry Pi Zero 2 W as a WireGuard gateway router, including NAT and iptables firewall with fail2ban
3. Connect AREDN node (e.g., hAp2) via the 44Net tunnel
4. Write a script to configure the routing table on the AREDN node, in case it is not peristed on router reboot

Set up a 44net Allocation and Tunnel from 44net Connect

This step could be replaced with your existing 44net allocation, but, as I mentioned, I chose to work through the 44net Connect tunnel service and network allocation generously offered by their service. Although I have traditional 44net subnets allocated for fixed use, I felt that the tunneled approach would give me some versatility in the deployment behind a variety of WAN connections. Because I have an interest in computing and networking education, the ability to pack up and redeploy this setup in a mobile environment was advantageous for me.

Go to https://44net Connect and create an account

Request a routed subnet (e.g., 44.x.y.z/29) and a WireGuard tunnel

You’ll receive a:

• Tunnel endpoint (e.g., a.b.c.d:44000)
• Allocated IP (e.g., 44.i.j.k/32)
• Route for your subnet via that tunnel by editing the tunnel allocation and specifying static routing to the subnet

Configure a Raspberry Pi as a Gateway to 44net Connect for the AREDN Router

Although the router should generally support it, the AREDN firmware does not allow making a non-AREDN Wireguard connection such as the one I am using to connect to 44net Connect in order to route this network allocation (at least as far as I’m aware at the time of this writing!). Instead, I’ve set up a Raspberry Pi Zero 2W to serve this purpose. I’ll connect the pi to the AREDN router via its WiFI LAN Hotspot connection, and give the pi an IP address on the 44net subnet allocation alongside the router, and will set it up for IPv4 forwarding.

Configure the Wireguard Tunnel

Install WireGuard

Here, we create the Wireguard tunnel connection to 44net Connect from the Raspberry Pi, and configure the IP routes on the pi to send 44net traffic out via this Wireguard interface. In addition, we route our local 44net subnet out via our LAN connection, so that it goes directly to the AREDN router. In my case, I’m connected to the AREDN router via a wifi Part 15 connection, so I use wlan0 for this interface. If you plug the pi into the AREDN router via Ethernet, you might use eth0 here instead.

sudo apt update
sudo apt install wireguard netfilter-persistent iptables-persistent resolvconf sshpass

Create /etc/wireguard/wg0.conf, using your 44net subnet allocation for 44.x.y.z/29, your 44net Connect Wireguard tunnel keys, and substituting wlan0 for the LAN interface you’re using from the pi to the AREDN node, as well as 44.a.b.c for your wireguard tunnel client address and a.b.c.d:44000 for your tunnel endpoint:

[Interface]
PrivateKey = <local private key>
Address = 44.a.b.c
DNS = 1.1.1.1,1.0.0.1

PostUp = ip route add 44.x.y.z/29 dev wlan0
PostDown = ip route del 44.x.y.z/29 dev wlan0

[Peer]
PublicKey = <peer public key>
PresharedKey = <preshared key>
Endpoint = a.b.c.d:44000
AllowedIPs = 44.0.0.0/9, 44.128.0.0/10
PersistentKeepalive = 20

Enable and Start WireGuard

Create /etc/systemd/system/wg-44net-client.service:

[Unit]
Description=WireGuard Client to 44net (wg0)
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/wg-quick up wg0
ExecStop=/usr/bin/wg-quick down wg0
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Enable the Service for Automatic Startup

sudo systemctl enable wg-44net-client
sudo systemctl start wg-44net-client

Set Static IP, Enable IP Forwarding, and Disable RP Filtering

Set the AREDN router (hap2) to give a static IP to the pi. For example, if your 44net subnet is 44.a.b.32/29, then the AREDN router might take 44.a.b.33/29 and the pi could be assigned 44.a.b.34/29 as a DHCP reservation from the AREDN router.

To enable IPv4 forwarding, edit /etc/sysctl.conf and add or uncomment the following line:

net.ipv4.ip_forward=1

Apply the changes:

sudo sysctl -p

If you find that ip_forward is still 1 when you execute cat /proc/sys/net/ipv4/ip_forward on the AREDN node or on the Pi, update them by running: echo 1 > /proc/sys/net/ipv4/ip_forward.

On both the AREDN router, and on the Pi, ensure that IPv4 forwarding is enabled, and that RP filtering is disabled, by running:

cd /proc/sys/net/ipv4/conf
find . -iname 'rp_filter' -exec cat {} \;

If you find any that are set to 1 or 2, update them via: echo 0 > /proc/sys/net/ipv4/conf/<name>/rp_filter.

Set up NAT and Firewall on the Pi

Note that this is a minimal configuration of the firewall to enable the functionality, and should be hardened to filter traffic from the Internet. This firewall is configured to allow all traffic from AREDN (10.0.0.0/8) and 44net (44.0.0.0/9 and 44.128.0.0/10), as well as bidirectional AREDN Wireguard tunnels on UDP port 5525. We also allow ICMP ping packets, and any established connection packets. Finally, we masquerade traffic on the 44net Connect tunnel Wireguard interface wg0. I do not explicitly allow TCP port 22 SSH traffic from the Internet, but rather allow ssh connections via the AREDN and 44net subnets (this is also overly permissive, but is presented this way to demonstrate the functionality).

Edit /etc/iptables/rules.v4, substituting your 44net subnet allocation for 44.x.y.z/29:

*nat
:PREROUTING ACCEPT [0:0]
:INPUT ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]
:POSTROUTING ACCEPT [0:0]

-A POSTROUTING -s 44.x.y.z/29 -o wg0 -j MASQUERADE
COMMIT

*filter
:INPUT DROP [0:0]
:FORWARD ACCEPT [0:0]
:OUTPUT ACCEPT [0:0]

# Allow loopback
-A INPUT -i lo -j ACCEPT

# Allow established and related
-A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# Allow ALL traffic from 44.0.0.0/9
-A INPUT -s 44.0.0.0/9 -j ACCEPT

# Allow ALL traffic from 44.128.0.0/10
-A INPUT -s 44.128.0.0/10 -j ACCEPT

# Allow ALL traffic from 10.0.0.0/8
-A INPUT -s 10.0.0.0/8 -j ACCEPT

# Allow AREDN tunnels
-A INPUT -p udp --dport 5525 -j ACCEPT
-A INPUT -p udp --sport 5525 -j ACCEPT

# Optional: Allow ICMP for ping and diagnostics
-A INPUT -p icmp -j ACCEPT

# Forwarding rules: Send AREDN Wireguard traffic from 44net Connect to the AREDN router
-A FORWARD -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
COMMIT

Load and save these rules:

sudo iptables-restore < /etc/iptables/rules.v4
sudo netfilter-persistent save

Implement fail2ban on SSH

Install fail2ban:

sudo apt install fail2ban

Create /etc/fail2ban/jail.local:

[sshd]
enabled = true
backend = systemd
logpath = journal
port = ssh
maxretry = 5
findtime = 600
bantime = 86400

Start and Enable fail2ban:

sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Configure the AREDN Node Router

Configure the node as with a 44net allocation for its local LAN, and specify its IP address (for example, 44.x.y.33/29 for an allocation of 44.x.y.32/29). I used wan0 as a LAN hotspot so that my devices could connect to this router wirelessly over 2.4 ghz, and wlan1 as a WAN client to my home wireless internet connection.

I also created a tunnel server on my home AREDN router node, to which this new 44net AREDN node connects. Because my home AREDN node is exposed with a 44net IP address on a different subnet, the two are able to reach each other via the 44net Connect Wireguard tunnel via the Raspberry pi. So, I used the 44net address of my home AREDN router as the public IP from which this new node connects.

Finally, I allow WAN access to my LAN nodes (and provide a default route) through the network settings on the main page of the GUI.

Configure the Routing Table on the AREDN Router

Now, we will configure the AREDN router to route 44net traffic out via the Raspberry Pi, since the pi has a Wireguard connection to the 44net Connect tunnel.

Custom routes on the AREDN router are overwritten on reboot (as far as I can tell). In addition, the home directory is /tmp, so I was unable to use ssh key login to script the creation of these routes via ssh when the Raspberry pi boots up.

But, for good measure, I created the following startup script on the AREDN node after logging in via ssh root@localnode.local.mesh -p 2222 and creating a file /etc/init.d/customroutes (substitute 44.x.y.z/29 for your 44net subnet allocation, and 44.x.y.A for the reserved DHCP address of your Raspberry Pi that you assigned earlier from your AREDN node out of your 44net subnet allocation, in addition to a route for your tunnel endpoint 44.a.b.c in case it is within one of the routing blocks like 44.0.0.0/9 (so that it doesn’t go out over the same interface, but instead over your WAN default route gateway (which we will detect with the get_wlan1_gw function below) and wlan1 (use your WAN interface for wlan1 everywhere here):

#!/bin/sh /etc/rc.common

START=95
STOP=10

get_wlan1_gw() {
    # Output gateway for default route on wlan1, or empty string if not found
    set -- $(ip -4 route show default dev wlan1 2>/dev/null)
    [ "$1" = "default" ] && [ "$2" = "via" ] && echo "$3"
}

start() {
    logger -t customroutes "Adding custom IP routes"
    sleep 5
    ip rule add to 44.0.0.0/9 lookup main priority 5 
    ip rule add to 44.128.0.0/10 lookup main priority 6 
    ip route add 44.0.0.0/9 via 44.x.y.A
    ip route add 44.128.0.0/10 via 44.x.y.A
    ip route add 44.x.y.z/29 dev br-lan
    
    gw="$(get_wlan1_gw)"
    ip route add 44.a.b.c via "$gw" dev wlan1 
    
    logger -t customroutes "Custom IP routes added"
}

stop() {
    logger -t customroutes "Removing custom IP routes"
    ip rule del to 44.0.0.0/9 lookup main priority 5 
    ip rule del to 44.128.0.0/10 lookup main priority 6     
    ip route del 44.0.0.0/9 via 44.x.y.A
    ip route del 44.128.0.0/10 via 44.x.y.A
    ip route del 44.x.y.z/29 dev br-lan
    
    gw="$(get_wlan1_gw)"
    ip route del 44.a.b.c via "$gw" dev wlan1 
    
    logger -t customroutes "Custom IP routes removed"
}

Inside the start() function, add these lines as needed from the IP forwarding and RP filtering step above:

echo 0 > /proc/sys/net/ipv4/conf/<name>/rp_filter
echo 1 > /proc/sys/net/ipv4/ip_forward 

Enable the service to run at startup on the AREDN node (although the node might not respect it):

chmod +x /etc/init.d/customroutes
/etc/init.d/customroutes enable

Scripting This from the Rasperry Pi

In case the AREDN router fails to execute this on startup, I also made a script on the Raspberry Pi to execute these ip route commands via ssh.

On the pi, create a file /usr/local/bin/setup-mesh-routes.sh with the same commands and addresses as above:

#!/bin/bash

# Define remote host and port
REMOTE_HOST="root@localnode.local.mesh"
REMOTE_PORT=2222

# Run the routing commands over SSH
ssh -p $REMOTE_PORT $REMOTE_HOST << 'EOF'
ip rule add to 44.0.0.0/9 lookup main priority 5 || true
ip rule add to 44.128.0.0/10 lookup main priority 6 || true
ip route add 44.0.0.0/9 via 44.x.y.A || true
ip route add 44.128.0.0/10 via 44.x.y.A || true
ip route add 44.x.y.z/29 dev br-lan || true

set -- $(ip -4 route show default dev wlan1)
gw="$3"
ip route add 44.a.b.c via "$gw" dev wlan1 || true
EOF

Similarly, add these lines as needed for the IP forwarding and RP filtering steps from earlier:

echo 0 > /proc/sys/net/ipv4/conf/<name>/rp_filter
echo 1 > /proc/sys/net/ipv4/ip_forward 

Executing /usr/local/bin/setup-mesh-routes.sh from the raspberry pi will set up the routes. The || true clause at each line allows the script to continue and exit successfully even if the routes already exist on the router.

Automating the Script to Run at Startup

If the AREDN mesh could retain ssh keys for logging in, I could fully automate this by enabling an init.d service on the raspberry pi to execute this script whenever the wireless LAN becomes available. However, since this requires a password, I ssh into the pi and run this script myself. If you are willing to store your AREDN root password on your pi, you could pass it through the script to call ssh. The sshpass program does exactly this, and you can replace the line ssh -p $REMOTE_PORT $REMOTE_HOST << 'EOF' with:

sshpass -p "$PASSWORD" ssh -o StrictHostKeyChecking=no -p $REMOTE_PORT $REMOTE_HOST << 'EOF' 

Assuming you’ve set the PASSWORD environment variable in the script, from a file, or from the outside environment.

In that case, this can be established as a startup service on the pi:

Create the file /etc/system/system/aredn-routing.service:

[Unit]
Description=Configure IP routes for AREDN on boot
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/setup-mesh-routes.sh
RemainAfterExit=yes

[Install]
WantedBy=multi-user.target

Enable it to run at startup via:

sudo systemctl daemon-reexec
sudo systemctl daemon-reload
sudo systemctl enable aredn-routing.service
sudo systemctl start aredn-routing.service

Configure 44net.cloud and 44net network

On the AMPR portal, request a subnet, and on 44net.cloud, request a tunnel.

Once you receive the tunnel, go back to the AMPR portal, and under Networks - My Gateways, click Create a Gateway. Fill in the 44net public IP address of your 44net.cloud tunnel as well as the DNS record for that IP address. You can use nslookup to determine if a DNS entry exists, or create your own with a third party service and use that domain name here.

Link this gateway to your 44net subnet allocation.

Configure AMPR Portal DNS Record for your Mikrotik gateway

On the AMPR portal, and under DNS - My Subdomains, select your subdomain (or create one if needed). Click Add a resource record and give a hostname like gw that points to an A record of your gateway IP address (the first usable address within your 44net subdomain; so 44.x.y.1 if your network is 44.x.y.0/29.

Configuring the Mikrotik

Log into your Mikrotik device.

Establishing Wireguard Connection to 44net.cloud

Execute the following commands in terminal mode to set up your Wireguard connection to 44net.cloud, assuming 44.X.Y.Z/32 is your 44net.cloud tunnel IP address:

# 1. Add the WireGuard interface - PUT YOUR WIREGUARD PRIVATE KEY BELOW
/interface/wireguard/add name=wg-44net listen-port=13231 private-key="YOUR PRIVATE KEY HERE"

# 2. Assign the IP address to the interface - PUT YOUR 44NET.CLOUD 44net IP ADDRESS BELOW
/ip/address/add address=44.X.Y.Z/32 interface=wg-44net

# 3. Set the DNS server (optional, for local resolver usage)
/ip/dns/set servers=1.1.1.1

# 4. Add the WireGuard peer - PUT YOUR 44NET.CLOUD PEER PUBLIC KEY, PRESHARED KEY, ENDPOINT ADDRESS, and PORT BELOW
/interface/wireguard/peers/add interface=wg-44net \
    public-key="YOUR PUBLIC KEY HERE" \
    preshared-key="YOUR PRESHARED KEY HERE" \
    endpoint-address=44.X.Y.Z \
    endpoint-port=YOUR 44NET.CLOUD PORT HERE \
    allowed-address=44.0.0.0/9,44.128.0.0/10,169.228.34.84 \
    persistent-keepalive=20

# 5. Configure traffic
/ip firewall filter add chain=input action=accept in-interface=wg-44net comment="Allow input from wg-44net" place-before=5

/ip route add dst-address=44.0.0.0/9 gateway=wg-44net comment="44Net outbound routing"
/ip route add dst-address=44.128.0.0/10 gateway=wg-44net comment="44Net outbound routing"

Here, we configure the wireguard connection to allow 44net traffic as well as traffic to the amprgw at UCSD.

Configure WAN Options

My hAp ac2 has two wireless radios on 2.4 and 5 ghz (wlan1 and wlan2, respectively). Optionally, you can configure your node as a WiFi client or hotspot to connect to the Internet or to create a hotspot. If you configure a WiFi client, be sure it (i.e., wlan2) is acting as a DHCP client in addition to the ether1 port.

Here, we will configure wlan1 as a client and put it on the bridge with our ethernet LAN ports, and then add ether1 as a DHCP client acting as the WAN port. I will also set wlan2 to act as a WiFi client so that I can connect to the internet.

First, we will set up the bridge to include the ethernet LAN ports:

/interface bridge port
add bridge=bridge comment=defconf interface=ether2
add bridge=bridge comment=defconf interface=ether3
add bridge=bridge comment=defconf interface=ether4
add bridge=bridge comment=defconf interface=ether5

Configure WiFi Hotspot

wlan1 can be configured as a wireless access point hotspot so that clients can connect to it and receive 44net IP addresses as if they were plugged into a LAN ethernet port. Set wlan1 to ap-bridge mode and associate it with an SSID name and security profile with your desired pre-shared keys. Then add it to the bridge:

/interface bridge port
add bridge=bridge comment=defconf interface=wlan1

Configure WiFi Client

wlan2 can be used as an WiFi client (station mode) for outbound connections from your clients to the Internet via an existing base station. I configured wlan2 as a client, and associated it with a security profile that included my pre-shared keys for the wireless network I was connecting to (similar to the WiFi hotspot I established on wlan1). I set wlan2 to be a wireless station, and set wlan2 as a DHCP client.

/interface wireless set [find name=wlan2] mode=station
/ip dhcp-client add interface=wlan2 add-default-route=yes default-route-distance=1 use-peer-dns=yes use-peer-ntp=yes disabled=no
/interface list member
add interface=wlan2 list=WAN comment="Wi-Fi uplink is WAN too"

Configure DHCP

Set up your router’s DHCP server to use the 44net subnet you’ve been allocated by AMPR, filling in your subnet information (i.e., 44.x.y.0/29), gateway IP (i.e., 44.x.y.1), and usable IP addresses (i.e., 44.x.y.1-44.x.y.6) below. We will also set the ether1 WAN port as a DHCP client.

/ip pool
add name=dhcp ranges=44.x.y.1-44.x.y.6
/ip dhcp-server
add address-pool=dhcp interface=bridge name=defconf
/ip dhcp-server network
add address=44.x.y.0/29 gateway=44.x.y.1 dns-server=44.x.y.1
/ip dhcp-client
add interface=ether1 comment=defconf

Assigning IP addresses from your 44net Subnet and from 44net.cloud

Assign an IP address for the gateway to internal network bridge. We assume your gateway IP is 44.x.y.1 from your AMPR 44net subnet allocation.

/ip address
add address=44.x.y.1/29 interface=bridge comment=defconf

Create an IPIP Tunnel to the UCSD 44net Gateway

In order to receive IPIP packets to your gateway from UCSD, you will need an IPIP tunnel interface to UCSD (using the IP address associated with amprgw.ucsd.edu) and from your 44net.cloud IP tunnel address 44.X.Y.Z:

/interface ipip
add name=ipip-44net local-address=44.X.Y.Z remote-address=169.228.34.84 allow-fast-path=no
/ip address add address=44.X.Y.Z/32 interface=ipip-44net
/ip firewall mangle
add chain=forward tcp-flags=syn protocol=tcp out-interface=ipip-44net \
    action=change-mss new-mss=clamp-to-pmtu comment="Clamp MSS for IPIP-over-WG on egress"
add chain=forward action=change-mss protocol=tcp tcp-flags=syn in-interface=wg-44net \
    new-mss=clamp-to-pmtu comment="Clamp MSS when ingressing WG"    

Configuring the Basic Routing Table

To route traffic over the Wireguard interface and over the IPIP tunnel, add the following routing tables and routes. Here, we assume 44.x.y.z is your 44net.cloud tunnel IP address, and 44.0.0.0/29 is your AMPR 44net subnet allocation.

/routing table
add name=via-wg
add name=via-ipip
add fib name=via-wg
add fib name=via-ipip

/ip route
add dst-address=44.0.0.0/9 gateway=wg-44net comment="Send all AMPRNet traffic via WireGuard"
add dst-address=44.128.0.0/10 gateway=wg-44net comment="Send all AMPRNet traffic via WireGuard"
add dst-address=0.0.0.0/0 gateway=wg-44net routing-table=via-wg comment="Send all traffic that came in over Wireguard back out via Wireguard"
add dst-address=0.0.0.0/0 gateway=ipip-44net routing-table=via-ipip comment="Send all traffic that came in over the IPIP tunnel back out via the IPIP tunnel"
add dst-address=169.228.34.84/32 out-interface=wg-44net comment="UCSD IPIP transport via WG"
    
/routing rule
add src-address=44.x.y.z/32 interface=wg-44net action=lookup table=via-wg 
add src-address=44.x.y.z/32 interface=ipip-44net action=lookup table=via-ipip
add src-address=44.0.0.0/29 interface=wg-44net action=lookup table=via-wg
add src-address=44.0.0.0/29 interface=ipip-44net action=lookup table=via-ipip

Configuring Basic Firewall Rules

You’ll want to add additional rules to harden this installation! These simply make the tunnel connections functional, and these rules are not intended to secure the network from the outside. Here, we assume 44.x.y.0/29 is your 44net subnet allocation from AMPR, 44.x.y.1 is your gateway IP address and that 44.x.y.2-44.x.y.6 are your remaining routable IP addresses on your subnet.

/ip firewall filter
add chain=input action=accept connection-state=established,related,untracked comment="Allow established"
add chain=input action=drop connection-state=invalid comment="Drop invalid"
add chain=input action=accept protocol=icmp comment="Allow ICMP"
add chain=input action=accept in-interface=wg-44net comment="Allow input from wg-44net"
add chain=input action=accept dst-address=44.x.y.1 protocol=icmp comment="Allow ICMP to 44Net address"
add chain=input action=drop in-interface-list=!LAN comment="Drop non-LAN traffic"
add chain=input in-interface=wg-44net protocol=ipip action=accept comment="Allow inbound IPIP via WG"

add chain=forward action=accept connection-state=established,related,untracked
add chain=forward action=drop connection-state=invalid
add chain=forward action=fasttrack-connection connection-state=established,related hw-offload=yes comment="FastTrack"
add chain=forward action=accept dst-address=44.x.y.2-44.x.y.6 comment="Inbound to 44Net hosts"
add chain=forward action=accept dst-address=44.0.0.0/9 src-address=44.x.y.0/29
add chain=forward action=accept dst-address=44.128.0.0/10 src-address=44.x.y.0/29
add chain=forward action=accept dst-address=44.x.y.0/29 in-interface=wg-44net
add chain=forward action=accept out-interface=wg-44net src-address=44.x.y.0/29
add chain=forward action=accept dst-address=44.x.y.0/29 in-interface=ipip-44net
add chain=forward action=accept out-interface=ipip-44net src-address=44.x.y.0/29
add chain=forward out-interface=ipip-44net action=accept comment="Allow outbound to IPIP tunnel"

/ip/firewall/connection/tracking/set enabled=yes

Configuring DNS

Enable outside DNS lookups as follows (feel free to replace your favorite DNS servers for 1.1.1.1,8.8.8.8. We assume 44.x.y.1 is your gateway IP.

/ip dns
set allow-remote-requests=yes servers=1.1.1.1,8.8.8.8
/ip dns static
add name=router.lan address=44.x.y.1 type=A comment=defconf

Adding 44net Network Gateways to your Routing Table

You can route traffic over the IPIP tunnel directly to other 44net subnets. To do this, you need to be aware of their routing table. UCSD sends this routing table periodically to all nodes, but there is not an easy way to process them on Mikrotik routers once they’re received. Instead, we can create them manually, and flush/re-create the table on-demand to receive any updates.

This Python program can be run on your local computer, and it generates a Mikrotik script that you can upload and run on your router to populate these routing entries. They are all tagged with ampr-imported-route so that they can be flushed for re-creation without modifying the rest of your routing rules.

import requests
import ipaddress

# Upload output file to router and execute with /import file-name=ampr_routes.rsc

API_TOKEN = "YOUR AMPR PORTAL API TOKEN FROM YOUR AMPR PORTAL PROFILE PAGE"
OUTPUT_FILE = "ampr_routes.rsc"
GATEWAY = "ipip-44net" # or none to use their address, if routing over ipip already for these IP ranges
ROUTE_COMMENT = "ampr-imported-route"

# List of local subnets to skip (any CIDR you handle internally)
SKIP_PREFIXES = [
    "44.x.y.0/29",     # Your allocation
]
SKIP_NETWORKS = [ipaddress.ip_network(p) for p in SKIP_PREFIXES]

# Fetch route list from AMPRNet
response = requests.get(
    "https://portal.ampr.org/api/v2/encap/routes",
    headers={
        "Authorization": f"Bearer {API_TOKEN}",
        "Accept": "application/json"
    }
)

data = response.json()
routes = data.get("encap", [])

with open(OUTPUT_FILE, "w") as f:
    # First, remove all old AMPR routes by comment
    f.write(f"/ip route remove [find comment=\"{ROUTE_COMMENT}\"]\n")

    # Now add the updated routes
    for route in routes:
        prefix = f"{route['network']}/{route['cidr']}"
        leaseholder = route.get("leaseholder", "unknown")
        
        # Skip if the prefix overlaps any local subnet
        if any(ipaddress.ip_network(prefix).overlaps(local) for local in SKIP_NETWORKS):
            continue        
            
        if GATEWAY is None:
            gateway = route['gatewayIP']
        else:
            gateway = GATEWAY
        
        f.write(
            f"/ip route add dst-address={prefix} gateway={gateway} comment=\"{ROUTE_COMMENT}\"\n"
        )

Upload the ampr_routes.rsc file to your Mikrotik router under the Files tab, and back in the terminal, execute the following command to run the script and add the routes:

/import file-name=ampr_routes.rsc

Wrapping Up

Reboot the router and wait an hour for UCSD to start sending packets to your gateway.

Test by pinging your gateway (gw.<your call sign>.ampr.org or 44.x.y.1).

Be sure to set firewall rules to restrict traffic, especially inbound, to your router!

• allscan
• supermon
• allmon3
• skywarn plus
• dvswitch
• digital_link
• alltune

Step 1: Install ASL3

1. Prepare the Raspberry Pi:
   • Download and install the Raspberry Pi Imager.
   • Select Lite 64-bit OS and configure username, password, and enable SSH.
   • Flash the microSD card and boot the Raspberry Pi.
2. Install ASL3:

   sudo -s
   apt update && apt upgrade
   cd /tmp
   wget https://repo.allstarlink.org/public/asl-apt-repos.deb12_all.deb
   dpkg -i asl-apt-repos.deb12_all.deb
   apt update
   apt install git asl3
   

3. Configure ASL3:
   • Run the ASL configuration menu:

     asl-menu
     

   • Adjust node settings as needed and save.
   • For my setup, I set CTCSS From to usb instead of usbinvert

Access ASL3 at http://<your_ip_address>:9090.

Step 2: Configure ASL3 Components

SimpleUSB Configuration

Edit the simpleusb.conf file to set up your hardware interface:

nano /etc/asterisk/simpleusb.conf

Configure Audio Levels

Restart Asterisk and test the setup:

asterisk -r
rpt fun <your_node_number> *355553

Speak into the microphone and adjust the audio settings so that the meter just touches the 5kHz level. Disconnect when done with:

rpt fun <your_node_number> *155553

To set the audio transmit level, edit /etc/asterisk/simpleusb.conf and set the rxmixerset value. I went with a value around 650, such that running asterisk -rvvv (after restarting asterisk) and rpt debug level 7 decodes and displays DTMF codes being sent and audio levels “just about right” or at least just a bit low when testing on node 55553. I found that setting the audio level to the “just about right” setting caused the DTMF tones to be oversaturated and fail to decode, so I adjusted this to a slightly lower value.

Test AllStarLink Connection

Connect to Allstar Echo node: 40894 via the radio by entering *340894 to connect (and speak / echo), and *140894 to disconnect.

Allmon3 Setup

1. Install Allmon3:

   apt install allmon3
   

2. Configure Allmon3 settings in /etc/allmon3/allmon3.ini according to these instructions. Be sure to remove the allmon3 user account and add an admin password:

   Update passwords:

   allmon3-passwd --delete allmon3
   allmon3-passwd admin
   

   Uncomment / set account and manager.conf secret for node 1999.

3. Restart services:

   systemctl restart asterisk
   systemctl start allmon3
   

Access Allmon3 at http://<your_ip_address>/allmon3.

Echolink Setup

Edit the following files to configure Echolink: /etc/asterisk/echolink.conf and /etc/asterisk/modules.conf.

In /etc/asterisk/modules.conf, add or uncomment this line: load => chan_echolink.so. If there is a similar line with noload =>, comment that out.

In /etc/asterisk/echolink.conf, add your AllStarLink node number and set your personal EchoLink information.

Load the Echolink module and restart Asterisk:

systemctl restart asterisk

Test by connecting to *33009999 (EchoLink echo test 9999); then *13009999 to disconnect. To connect to an EchoLink node, dial *33 followed by a 6 digit EchoLink node number. If the node number is fewer than 6 digits long, prepend the node number with enough zeroes to make a 6 digit number. For example, EchoLink node 9999 is entered as 009999.

Step 3: Install and Configure DVSwitch

1. Install DVSwitch:

   wget http://dvswitch.org/bookworm
   chmod +x bookworm
   ./bookworm
   apt update
   apt install dvswitch-server
   apt install php-cgi libapache2-mod-php8.2
   

2. Configure DVSwitch:

   cd /usr/local/dvs
   ./dvs
   

   You can set modes from the dvs menu under Advanced - Configure Other Stanzas (Edit <mode>), Additional DMR Networks, and Configure Favorite TG. Additionally, you may be able to set up DV3000 USB as the vocoder here if available for D-Star support under the initial setup menu, in the Hardware Vocoder section (for example, if you have a USB ThumbDV AMBE vocoder device).

3. Edit configuration files as needed: In /opt/Analog_Bridge/Analog_Bridge.ini, under [USRP], set:

   txPort = 32001                          ; Transmit USRP frames on this port
   rxPort = 34001                          ; Listen for USRP frames on this port
   usrpAudio  AUDIO_USE_GAIN
   usrpGain = 3.00
   tlvAudio = AUDIO_USE_GAIN
   

   In /opt/MMDVM_Bridge/MMDVM_Bridge.ini, set Jitter=750 under [DMR Network], and set RX/TXFrequency to 433800000 under [Info]. You can also set your contact information in this file.

4. Set up private node 1999 in ASL3 to bridge to DVSwitch:

    sudo asl-menu
   

   Under Node Settings - AllStar Node Settings - Add Node with the following parameters: node number 1999, “None of the Above”, “Radio Interface USRP”, and “Duplex Type 0 / Half”.

   Test by connecting/disconnecting to node 1999 in allmon3. You must connect your ASL node to 1999 before using DVSwitch. You can dial *31999 to do this (and *11999 to disconnect).

5. Enable and start DVSwitch services:

   systemctl enable analog_bridge mmdvm_bridge md380-emu
   systemctl start analog_bridge mmdvm_bridge md380-emu
   

6. Test DVSwitch:

   /opt/MMDVM_Bridge/dvswitch.sh mode YSF
   /opt/MMDVM_Bridge/dvswitch.sh tune parrot.ysfreflector.de:42020
   

   In general, you can connect to any mode and endpoint via:

   /opt/MMDVM_Bridge/dvswitch.sh mode {DMR|NXDN|P25|YSF|DSTAR} # Set Analog_Bridge digital mode
   /opt/MMDVM_Bridge/dvswitch.sh tune <tg> # Tune to specific TG number/Reflector
   

   Don’t forget to connect to node 1999 either through DTMF tones, or through allmon3. You can change digital modes using the web interface at http://<your_ip_address>/dvswitch/index.php.

   Note that DVSwitch cannot parse the # private call character in a tune command using the /opt/MMDVM_Bridge/dvswitch.sh tune yourbrandmeisterpasswordhere@3102.repeater.net:62031!91 format (i.e., using !9990#). Instead, run these as two commands:

   /opt/MMDVM_Bridge/dvswitch.sh tune yourbrandmeisterpasswordhere@3102.repeater.net:62031
   /opt/MMDVM_Bridge/dvswitch.sh tune '9990#'
   

   The ! format seems to work when connecting to a non-private call talkgroup; however, it should be separated for any private calls requiring a # at the end (including the 4000# unlink command.

7. Enable DVSwitch Mode Switcher Frontend:

    sudo apt update && sudo apt upgrade && sudo apt install git nodejs
    git clone https://github.com/firealarmss/dvswitch_mode_switcher.git
    cd dvswitch_mode_switcher
   

   Follow the instructions in dvswitch_mode_switcher-README.md.txt within the above repository. I also set enabled: true under usrp in /opt/dvswitch_mode_switcher/configs/config.yml.

    cd /opt/dvswitch_mode_switcher
    cp debian/dvswitch_mode_switcher.service /etc/systemd/system/dvswitch_mode_switcher.service
    systemctl daemon-reload
    systemctl enable dvswitch_mode_switcher.service
    systemctl start dvswitch_mode_switcher.service
   

   Then, log onto the ASL3 Cockpit at http://<your_ip_address>:9090 to update the firewall to allow port 3000 access. After logging in, click Networking on the left, click Edit Rules and Zones in the firewall panel, click Custom Ports, and enable port 3000 over TCP. Alternatively, I logged in over ssh and restricted access to a particular IP block (instead of adding it through the web interface, which opens the port to all IP addresses), by running:

    cat <<EOF > /usr/local/bin/nft-allow-allstarlink.sh
    #!/bin/bash
    CHAIN_NAME="filter_IN_allstarlink_allow"
    TABLE_NAME="inet firewalld"
   
    # Wait up to 30 seconds for firewalld to create the required chain
    for i in {1..30}; do
        if /usr/sbin/nft list chain $TABLE_NAME $CHAIN_NAME >/dev/null 2>&1; then
            break
        fi
        /usr/bin/sleep 1
    done
   
    # If the chain still doesn't exist, fail
    if ! /usr/sbin/nft list chain $TABLE_NAME $CHAIN_NAME >/dev/null 2>&1; then
        echo "Error: firewalld chain $CHAIN_NAME not found after timeout"
        exit 1
    fi
   
    /usr/sbin/nft add rule inet firewalld filter_IN_allstarlink_allow ip saddr <your net address>/<your subnet i.e. 24> tcp dport 3000 accept
    EOF
   
    chmod +x /usr/local/bin/nft-allow-allstarlink.sh
   
    mkdir -p /etc/systemd/system/firewalld.service.d
   
    cat <<EOF > /etc/systemd/system/firewalld.service.d/99-add-allstarlink-rules.conf
    [Service]
    ExecStartPost=/usr/local/bin/nft-allow-allstarlink.sh
    EOF
   
    systemctl daemon-reexec
   

   Access the portal via http://<your_ip_address>:3000. Again, be sure to connect to node 1999 first! You can edit your favorite digital talkgroups by editing the /opt/dvswitch_mode_switcher/configs/tg_alias.yml file. For example:

    - tgid: "yourbrandmeisterpasswordhere@3102.repeater.net:62031!91"
      alias: Brandmeister Worldwide
   

   Again, be sure not to use the !TG suffix for private calls ending in #. Instead, configure and execute two commands to connect via a private call:

    - tgid: "yourbrandmeisterpasswordhere@3102.repeater.net:62031"
      alias: Brandmeister Master
    - tgid: "9990#"
      alias: Brandmeister Parrot Test (Connect to master first)
   

Step 4: Install and Configure Supermon

1. Install Supermon:

   cd /usr/local/sbin
   wget "http://2577.asnode.org:43856/supermonASL_fresh_install" -O supermonASL_fresh_install
   chmod +x supermonASL_fresh_install
   ./supermonASL_fresh_install
   

2. Configure Supermon:
   • Edit allmon.ini and global.inc in /var/www/html/supermon/.

   • Set up .htpasswd for authentication:

     htpasswd -cB /var/www/html/supermon/.htpasswd admin
     

3. Enable automatic database updates:

   systemctl enable asl3-update-astdb.service asl3-update-astdb.timer
   systemctl start asl3-update-astdb.timer
   

4. Access Supermon at http://<your_ip_address>/supermon.

5. Update supermon with /usr/local/sbin/supermonASL_latest_update

6. Edit /var/www/html/supermon/almon.ini to modify the top menu. For example, you can add links to all the URLs from the tools in this document for easy access.

Step 5: Configure Skywarn Plus

bash -c "$(curl -fsSL https://raw.githubusercontent.com/Mason10198/SkywarnPlus/main/swp-install)"

Configuration

1. Configure /usr/local/bin/SkywarnPlus/config.yaml file according to readme instructions.

2. Add these lines to enable weather alert tail messages at a certain interval of activity:

   tailmessagetime=60000
   tailsquashedtime=30000
   tailmessagelist=/tmp/SkywarnPlus/wx-tail
   

3. Add to root crontab:

   * * * * * /usr/bin/python3 /usr/local/bin/SkywarnPlus/ASL3_Supermon_Workaround.py
   * * * * * /usr/local/bin/SkywarnPlus/SkywarnPlus.py
   * * * * * chown -R asterisk:asterisk /tmp/SkywarnPlus 
   

4. Follow these instructions to add time and weather hourly announcements. Add or modify your root crontab as follows:

   00 00-23 * * * /usr/bin/perl /usr/local/sbin/saytime.pl 19320 62933 > /dev/null
   

Allscan

Follow these instructions.

sudo apt update; sudo apt install php unzip -y
cd ~
wget 'https://raw.githubusercontent.com/davidgsd/AllScan/main/AllScanInstallUpdate.php'
chmod 755 AllScanInstallUpdate.php
sudo ./AllScanInstallUpdate.php

Edit /etc/php/8.2/cli/php.ini and uncomment extension=pdo_sqlite and extension=sqlite3.

Test at http://<your-ip-address>/allscan (set up initial user). You can now use allscan to connect/disconnect instead of allmon3 or DTMF.

Edit favorite nodes at /var/www/html/supermon/favorites.ini:

label[] = "Label"
cmd[] = "rpt cmd %node% ilink 3 <node number>"
label[] = "Echolink Label"
cmd[] = "rpt cmd %node% ilink 3 3<0 prepadded 6 digit node number>"

Alltune

Follow the instructions at the download provided here. Extract the web files to /var/www/html/alltune and access at http://<your-ip-address>/alltune.

IAX Configuration

You can access your AllStarNode from an Android device or other IAX connection by adding the following stanza to /etc/asterisk/iax.conf:

[iaxclient]                      ; Connect from iax client (Zoiper...)
type = friend                    ; Notice type here is friend <--------------
context = iax-client             ; Context to jump to in extensions.conf
auth = md5
secret = your-secret-password-here
host = dynamic
disallow = all
allow = ulaw
allow = adpcm
allow = gsm
transfer = no
requirecalltoken=no ; to allow all connections
;calltokenoptional=0.0.0.0/0.0.0.0 ; to connect from a particular IP address

And add this in the /etc/asterisk/extensions.conf file:

[iax-client]                            ; for IAX VoIP clients.
exten => ${NODE},1,Ringing()
        same => n,Wait(10)
        same => n,Answer()
        same => n,Set(CALLSIGN=${CALLERID(name)})
        same => n,NoOp(Caller ID name is ${CALLSIGN})
        same => n,NoOp(Caller ID number is ${CALLERID(number)})
        same => n,GotoIf(${ISNULL(${CALLSIGN})}?hangit)
        same => n,Playback(rpt/connected-to&rpt/node)
        same => n,SayDigits(${NODE})
        same => n,rpt(${NODE}|P|${CALLSIGN}-P)
        same => n(hangit),NoOp(No Caller ID Name)
        same => n,Playback(connection-failed)
        same => n,Wait(1)
        same => n,Hangup

You can then configure DroidStar by adding the following in the Hosts section: IAX <your node number> <your node IP address> 4569 iaxclient your-secret-password-here, and choose your node under the IAX hosts section on the main tab. You might have to update your databases and hosts with the buttons under Settings prior to use. Once connected, you can issue DTMF codes to connect/disconnect, and use the PTT button to transmit.

Digital Link DTMF Tuning

To send DTMF tones to switch digital modes, servers/reflectors, and talkgroups, visit https://github.com/BillJr99/digital_link and follow the installation instructions there.

Enabling a ThumbDV AMBE Device

I have a USB vocoder, which I enabled by editing /opt/Analog_Bridge/Analog_Bridge.ini and setting:

[General]
decoderFallBack = true
userEmulator = false

[DV3000]
; address = 127.0.0.1
; rxPort = 2460
address = /dev/ttyUSB0
baud=460800
serial = true

References

• DVSwitch Installation Guide
• Supermon for ASL3
• DVSwitch Mode Changer
• ASL3 Installation Guide by Ham Radio and Networking
• ASL3 Installation Video by Ham Radio and Networking on Youtube
• Ham Radio Crusader Youtube Channel for Information on ASL3, DVSwitch, Supermon, SkywarnPlus, and more
• Installing Supermon on ASL3
• DVSwitch Installation
• Allmon3 and EchoLink on ASL3 by Ham Radio and Networking on Youtube
• DVSwitch and ClearNode on AllStar by Ham Radio and Networking on Youtube
• DVSwitch on AllStarLink 3 by Ham Radio and Networking on Youtube
• DVSwitch Server Part 1 and Part 2 by Ham Radio Crusader on Youtube
• ASL3 Cockpit Firewall
• SkywarnPlus on ASL3 by Ham Radio Crusader
• Supermon 7.4+ on ASL3 by Ham Radio Crusader
• Supermon for ASL3
• Time and Weather Announcements on SkywarnPlus by Ham Radio Crusader
• AllScan Setup Instructions
• Alltune