SyncNode
Think Locally. Act Intelligently.
The problem SyncNode solves
The Problem SyncNode Solves
The Problem
Modern industrial and enterprise workflows involve repetitive, multi-step operations across documents, spreadsheets, presentations, desktop applications, and system tools. Traditional automation scripts are often brittle when interfaces or workflows change, while unconstrained AI agents can make incorrect decisions, execute unintended actions, or expose confidential information.
Organizations need automation that is not only intelligent, but also controlled, verifiable, recoverable, and auditable.
Our Solution: SyncNode
SyncNode is an on-premise agentic AI workbench that transforms natural-language instructions into controlled, multi-step system automation.
Built around local and open-weight AI models, SyncNode combines AI reasoning with deterministic execution infrastructure. It can plan tasks, interact with tools, process files, generate business artifacts, verify results, recover from failures, and maintain an audit trail—all within a governed execution environment.
The core principle is simple:
The model proposes. Deterministic infrastructure validates, authorizes, executes, and verifies.
What Can People Use SyncNode For?
| Use case | How SyncNode helps |
|---|---|
| Document automation | Process documents, extract information, and generate structured reports. |
| Spreadsheet workflows | Read, update, transform, and validate spreadsheet data. |
| Presentation generation | Create presentations from task instructions and available source material. |
| Desktop automation | Coordinate multi-step tasks across supported desktop applications and system tools. |
| Operational workflows | Execute repeatable procedures with checkpoints, policy checks, and verification. |
| Long-running tasks | Track progress, recover from failures, and resume eligible workflows from checkpoints. |
| Confidential environments | Support on-premise execution and local models to reduce reliance on external AI services. |
| Governed automation | Enforce permissions, request human approval where required, and record execution events. |
How SyncNode Works
USER INSTRUCTION
↓
INTENT UNDERSTANDING
↓
TASK PLANNING
↓
OBSERVE APPLICATION / SYSTEM STATE
↓
POLICY & PERMISSION VALIDATION
↓
HUMAN APPROVAL, WHEN REQUIRED
↓
CONTROLLED TOOL EXECUTION
↓
RESULT VERIFICATION
↓
┌─ SUCCESS → CHECKPOINT & CONTINUE
│
└─ FAILURE → RECOVER → RE-OBSERVE
↓
VERIFY AGAIN
↓
AUDIT TRAIL & COMPLETION REPORT
System Architecture
| Layer | Responsibility |
|---|---|
| AI Reasoning Layer | Interprets instructions, plans tasks, and proposes tool actions. |
| Orchestration Layer | Maintains workflow state, sequences actions, and manages checkpoints. |
| Policy & Approval Layer | Validates permissions, enforces execution rules, and gates sensitive actions. |
| Tool Execution Layer | Interacts with supported applications, documents, spreadsheets, presentations, and system tools. |
| Verification & Recovery Layer | Checks outcomes, detects failures, and selects appropriate recovery strategies. |
| Memory & Retrieval Layer | Retrieves relevant information and supports reusable workflows and procedural memory. |
| Audit & Artifact Layer | Records execution events and manages generated outputs and evidence. |
| Local AI Runtime | Supports on-premise inference using compatible local/open-weight models. |
Why SyncNode Is Different
- Local-first architecture: Designed for organizations that need greater control over sensitive data and AI infrastructure.
- Controlled execution: AI-generated actions pass through validation and policy enforcement rather than receiving unrestricted control.
- Verification-first automation: Success is checked against observable outcomes instead of relying solely on the model's claims.
- Failure recovery: Checkpoints and recovery strategies help eligible workflows resume after interruptions or failed actions.
- Human oversight: Approval gates preserve human authority over designated sensitive or consequential operations.
- Reusable procedural knowledge: Verified workflows can inform future executions and support adaptation when conditions change.
Our Goal
SyncNode aims to make complex system automation more accessible without sacrificing operational control. By combining agentic reasoning with deterministic infrastructure, it seeks to bridge the gap between rigid scripts and autonomous agents that are difficult to trust.
Think Locally. Act Intelligently.
Challenges we ran into
Building SyncNode — a local-first, sovereign AI automation workbench (FastAPI backend + Electron/React frontend + Ollama/Gemma running fully offline) — meant every "cloud shortcut" was off the table. We hit hard problems in model reliability, Windows desktop automation, document handling, and local inference performance. Here are the ones that mattered.
1. A small, local model that still has to drive real workflows
We run gemma4:e4b on consumer hardware (RTX 2050, 4 GB VRAM) with no cloud fallback. A small model is far less forgiving than a frontier API, so most of our effort went into making the system robust rather than trusting the model.
| Problem | Symptom | Fix |
|---|---|---|
Model emitted tool calls as raw <tool_code> XML in chat | XML leaked into the UI instead of executing | Parser using ast.literal_eval to extract nested args from text, then strip the XML before streaming |
| Planner produced steps with no postconditions | PlannerError aborted the entire run | Auto-inject a sensible default postcondition per action type instead of failing fast |
Model hallucinated assertion types (ui_element_contains, etc.) | Verification failed on valid work | Alias map routing ~40 hallucinated assertion names to real ones |
2. Windows desktop automation is brittle by nature
Driving live Office apps through UI Automation surfaced a long tail of race conditions and edge cases.
| Challenge | What broke | Resolution |
|---|---|---|
uia_type ran before the window existed | Window 'Word' not found after 3000ms | Auto-launch the correct Office app when the target window is missing, then wait for focus |
| Office title bars strip file extensions | Window lookup for Report.docx missed Report | Normalize titles (strip .docx/.xlsx/.pptx) before matching |
openpyxl can't write a file Excel has open | Permission denied | Close-before-write pattern + retry-on-lock |
{Ctrl}w closed the Electron app itself | App crash mid-run | Blocked the shortcut; route closes through uia_click/{Alt}{F4} |
3. Document ingestion and path resolution
Uploaded files and generated artifacts live in different places, which caused silent "file not found" failures.
| Challenge | Root cause | Fix |
|---|---|---|
"Analyze the uploaded spreadsheet" failed at inspect_data with 0 artifacts | excel.inspect only looked in the sandbox, not uploads/ | Unified path resolution across all Excel read/inspect tools to search uploads/, workspace, Desktop, Downloads |
| Read/inspect steps failed verification despite succeeding | command_succeeded only checked success/exit_code, not read-result shapes | Taught the assertion to recognize exists, sheets, values, content |
document.read_pdf failed on a bare filename | No resolver for partial names | _resolve_any_file() searches common locations, newest match wins |
4. The sandboxed code harness that quietly hung
The in-chat code executor caused one of the nastiest UX bugs: an infinite-feeling loop.
| Challenge | Symptom | Fix |
|---|---|---|
| Executor rejected non-Python languages | "Unsupported language: rust" | Added Rust, Go, C, C++, TypeScript, Ruby with a compile-then-run path |
Interactive code (input()) hung for the full timeout | Timed out after 30s, repeated | Closed stdin (DEVNULL) → fails instantly; added an interactive-input guard that rejects such code with an actionable message |
| Model retried the same broken code with cosmetic changes | 5 wasted rounds per request | Loop-guard that breaks after 2 same-reason failures, not just identical args |
5. Fully-offline local inference
Running without internet exposed hidden network dependencies.
| Challenge | Symptom | Fix |
|---|---|---|
sentence-transformers phoned home to HuggingFace Hub on every load | ~90 s of DNS retry backoff per ingest | Set HF_HUB_OFFLINE / TRANSFORMERS_OFFLINE before import, at startup and in the ingest path |
| Ollama GPU watchdog timed out on a single-GPU + iGPU box | Model load failures | Pinned CUDA_VISIBLE_DEVICES, disabled iGPU, raised load timeout |
6. Packaging for Windows without admin rights
Shipping a .exe on a locked-down machine broke electron-builder.
| Challenge | Symptom | Fix |
|---|---|---|
winCodeSign extraction needed symlink privilege | A required privilege is not held by the client | Shimmed the bundled 7za to skip symlink restore (macOS-only .dylib links we don't need), producing a clean NSIS installer |
Key takeaway
The hardest part of a sovereign, local-first agent isn't the model — it's everything around it: deterministic tool contracts, defensive path resolution, verification that fails closed without blocking valid work, and a harness that degrades gracefully instead of hanging. We leaned on a comprehensive test suite (82 passing tests) and a restart-and-smoke-test loop to keep every fix honest.
Technologies used
Ollama — local LLM runtime (serves Gemma offline)
Google Gemma — the local models (gemma4:e4b, gemma3:4b/1b)
FastAPI — Python backend API with SSE streaming
LangGraph — agentic workflow orchestration
Electron — Windows desktop app shell
React — frontend UI (with Vite + Tailwind)
ChromaDB — local vector database for RAG
Sentence-Transformers — local embeddings (all-MiniLM-L6-v2)
Playwright — browser automation
UI Automation (uiautomation / pywin32) — Windows desktop/Office control
