NANOHAT OS AGENT
Sub-1B parameter desktop agent distillation and native Linux execution runtime, specifically built for Fedora Workstation. Runs with sub-second latency on commodity CPU hardware using quantized models (SmolLM2-360M, Qwen2.5-0.5B), built with a pure native Python harness and backed by 250k verified action traces.
HOW NANOHAT WAS BORN & DISTILLED
Why Operating System Agents Cannot Live in the Cloud
Desktop OS control requires instant, deterministic feedback: launching applications, reading system memory, querying active processes, and toggling configuration switches.
Relying on 70B+ parameter cloud frontier models proved unsustainable: 2 to 5 seconds of network latency per turn, heavy recurring API costs, and continuous security exposure transmitting personal desktop state to remote servers. Worse, prevailing agent frameworks bundled hundreds of megabytes of third-party dependency bloat.
Curating the High-Entropy Action Dataset
I abandoned generic pre-training in favor of deep action-space distillation, synthesizing and curating 250,600 multi-turn action conversations (152.7M high-entropy tokens).
To ensure high execution accuracy, every conversation was required to pass 4 strict mechanical validation gates before touching the model weights: AST syntax validation, JSON argument verification, canonical tool contract bounds, and fail-closed headless simulation checks.
Deterministic POSIX Runtime Without Framework Bloat
The final model weights (SmolLM2-360M and Qwen2.5-0.5B) run locally on commodity CPU hardware using quantized GGUF inference, achieving sub-second reaction times.
In NanoHat V3, I froze the canonical agent tool surface to exactly 17 tools across 7 core modules. Built with zero external agent framework dependencies—pure standard-library Python (subprocess, asyncio) enforcing typed ToolSpec schemas and fail-closed mechanical safety gates that refuse headless execution of destructive commands (process termination, service restarts, file deletion) without explicit TTY confirmation.
WHO IT'S BUILT FOR
01 // LOCAL AI RESEARCHERS
Engineers exploring Small Language Model (SLM) parameter efficiency, response-only loss masking, and mechanical validation gating for autonomous action datasets.
02 // PRIVACY-FIRST USERS
Users who demand 100% offline desktop automation—managing tasks, diagnosing CPU/RAM bottlenecks, and controlling apps with zero telemetry leaving their laptop.
03 // SYSTEMS ARCHITECTS
Developers seeking deterministic machine-checkable tool contracts (OK: ... vs ERROR[reason]: ...) with fail-closed destructive safety gates.
DISTILLATION & RUNTIME ARCHITECTURE
Trajectory Generation
Automated multi-turn trajectory engine synthesizes diverse desktop interaction scenarios tailored for Linux and Fedora Workstation.
4-Gate Mechanical Filter
Enforces strict JSON schema compliance, replay grounding against mock OS backends, word-count tier ceilings, and zero duplicate fingerprints.
Response-Only Loss Masking
Full Fine-Tuning (FFT) on SmolLM2-360M-Instruct and Qwen2.5-0.5B, calculating gradients strictly over generated agent tool calls.
GGUF Model Packaging
Direct export to llama.cpp GGUF quantizations (Q4_K_M and F16) for CPU SIMD (AVX2/AVX-512) and Vulkan acceleration on Linux.
Native OS Harness
Standard-library dispatcher dispatches tool calls with fail-closed TTY confirmation gates for destructive system modifications.
NANOHAT V3 FROZEN TOOL REGISTRY
Frozen 17-Tool Contract Surface
Every tool is defined as an immutable ToolSpec registered against a strict nanohat.context.Context. Each tool invocation strictly validates against JSON schemas and returns a machine-checkable protocol: OK: <payload> on success, or ERROR[<reason>]: <explanation> on failure.
Low-overhead inspection of Linux subsystem metrics: CPU usage, RAM pressure, disk partition utilization, battery level, or top running processes.
Readonly network telemetry and diagnostics: ICMP ping latency, DNS resolution checks, external public IP lookup, interface IP enumeration, and WiFi status.
host: string (optional target host or domain)
Readonly package management queries via DNF and Flatpak: lists installed packages, queries metadata, searches repos, and checks available updates.
name: string (package query or filter)
Readonly process and systemd service introspection: finds processes by binary name with PID/cmdline matching, or checks unit status via systemctl.
name: string (target process or systemd service)
Executes OS desktop actions. Destructive operations (kill_process, restart_service, empty_trash) are mechanically gated with confirmation or fail closed in headless environments.
target: string (app, service name, or signal)
Hardware controls for audio volume, display brightness, and desktop media playback via playerctl and native audio sinks.
action: "get" | "set" | "play_pause" | "next" | "prev"
value: string (e.g. "50%", "+5%")
Controls desktop notification delivery: reads current state, enables/disables Do Not Disturb (DND), or toggles notification suppressions.
enabled: "true" | "false" (for set action)
Securely reads, populates, or purges desktop text clipboard contents using native Wayland (wl-clipboard) or X11 (xclip) backends.
text: string (text payload for set action)
Scoped filesystem operations strictly constrained to the user's home directory. Reading, writing, appending, listing, and regex glob searching. File deletion (delete) triggers a mechanical confirmation gate or fails closed.
path: string · content: string · pattern: string
Persistent associative memory: stores and retrieves user preferences, project paths, and environment settings across reboots and conversations.
key: string · value: string
Persistent task manager: schedules actions with natural relative intervals ("in 30 minutes") or ISO dates, backed by an async scheduler loop.
task: string · due: string · id: string · status: string · range: string
Manages asynchronous countdown timers. Alerts the user upon expiry with desktop notifications and audible cues.
duration: string (e.g. "15m", "1h") · label: string · id: string
Manages calendar events with start and end datetime bounds, location tags, and range filters ("today", "this_week", "all").
title: string · start: ISO · end: ISO · location: string · range: string
Evaluates arithmetic expressions safely through AST node validation, operand length caps, and operator whitelists to prevent arbitrary Python execution.
Deterministic unit and timezone conversion across physical domains: length, mass, volume, digital data units, temperature scales, and IANA timezone offsets.
value: string · from_unit: string · to_unit: string
Dispatches real-time web search queries returning ranked result snippets without the memory footprint of rendering headless Chromium instances.
Fetches remote web pages and extracts page title and readable body excerpt, enforcing hard character limits to protect model context windows.
CURRENT STAGE & THE HARD PART
NanoHat V2 Active · V3 Harness Built
NanoHat V2 is the working, stable operational baseline desktop agent executing low-latency system actions on commodity hardware.
For NanoHat V3, the entire runtime architecture—including the frozen 17-tool canonical registry across 7 subsystem modules, mechanical fail-closed destructive safety gates, and typed stdout contract dispatchers—is fully engineered in Python code.
Sub-1B Distillation Training & Rigorous Testing
While the V3 software harness is ready, the model weights themselves are actively in training and awaiting full benchmark verification.
Distilling 250,600 action traces into sub-1B parameter models (SmolLM2-360M and Qwen2.5-0.5B) requires careful loss masking over tool call tokens. The active challenge is completing the training runs and running deep regression testing to guarantee the V3 model reliably matches or exceeds V2 execution accuracy on low-memory CPU threads before deployment.