Skip to content
Projects

mrpulor-gh/nuphus has 102 GitHub stars and 20 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-16 19:53 UTC. Last push 2026-11-12.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Collecting history
in 15 days
Collecting history
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Nuphus — 本地优先的 AI Agent:真实桌面执行力 + 手机第二块屏幕。Local-first AI agent with real desktop execution and dual-device real-time sync.

AI

README.en.md

Original

Nuphus — Local-First AI Companion for Daily Coding, Office Work & Automation Workflows

Apache-2.0 License Rust Tauri React npm version npm downloads CI

English | 中文

Official website: www.nuphus.com — product overview, installers, changelog and documentation

Download Nuphus 1.4.0   GitHub Release v1.4.0

Version: 1.4.0 · Status: Release (stable) · Platforms: Windows / macOS / Linux Tech Stack: Tauri v2 · Rust · React 18 · TypeScript

Nuphus desktop & mobile

Nuphus is an AI Agent that runs entirely on your computer — local service, private data, and real desktop execution power. Your phone is its second screen on the same Wi-Fi LAN.

It reads the screen, drives the mouse and keyboard, controls windows, reads and writes files, and orchestrates the browser — turning LLM reasoning into real automation. The service, data, and Agent all run locally; model connections are configured by you. The phone connects to the desktop over the local Wi-Fi LAN by default, sharing the same memory, Agent, and conversation.


Design Philosophy

We don't chase flashy tricks — we value practical capability. Minimalist pragmatism: features appear on demand; no bloated shells, no repeated exploration, no wasted effort. Everything must land in daily work.

Leader: Serial thinking, parallel execution

Nuphus's core engine is built in Rust; tool calls complete in milliseconds, so the latency bottleneck is model inference, not the engine. Agent decisions are themselves causal chains — each step depends on the result of the previous one, and desktop system operations should follow serial logic.

  • Global understanding, task ownership — the Leader parses the goal, plans the path, monitors progress, and consolidates delivery
  • Internal orchestration (serial) — dispatches built-in GoalType ExecAgents (project analysis / code generation / debugging / file operations, etc.) along the causal chain
  • External orchestration (parallel) — through explicit interaction instructions, it can open Cline to fix a bug, Claude Code to write tests, and the browser to look up docs simultaneously — each external agent has its own context; Nuphus sits on top, verifying with screenshots, reading output, and consolidating decisions
  • Context passing — explicit instructions give external agents task context, reducing repeated instructions and re-exploration

What is serial is thinking; what is parallel is execution.

Nuphus desktop: a conversation executing, with the Appearance panel open (three built-in themes / custom themes / interface opacity)

Workflow: Turning one exploration into deterministic execution

Making an LLM spend tokens to solve 85%-identical tasks every time is a double waste of compute and time. Nuphus's answer — let the LLM reason once, compile it into a workflow, then execute repeatedly with near-zero tokens:

Natural language interaction → Agent co-explores (understand UI/flow/params) → solidify parameters step by step → compile into a deterministic execution sequence → engine repeats

This is not scheduled tasks — it is turning one intelligent exploration into repeatable deterministic execution:

  • Natural language exploration — interact with the Agent in natural language: grading exam papers, browser automation, desktop software operations... the Agent understands intent, recognizes the UI, and operates frame by frame
  • Parameter solidification — after co-exploring, solidify each step's locating, operation, and exception handling into parameters (parameters are the contract, all backed by UI evidence)
  • Deterministic execution — the compiled sequence repeats with near-zero tokens, no longer relying on the LLM to re-reason every time
  • Guardian repair — at runtime the Agent stands guard: on errors, it fixes, records, and optimizes according to the design intent and goal, rather than blindly retrying

One compile-time investment buys deterministic, repeatable, near-zero marginal cost automation.


Core Highlights

Real Desktop Execution

Nuphus installs directly on your OS with native-grade screen perception and input control:

  • Drive any GUI — window + OCR + mouse/keyboard; automate any desktop app or web page without needing their API
  • Built-in browser — a programmable browser engine; web automation, data collection, and form interaction all run locally
  • Programming & project analysis — project analysis, code generation, debugging, file operations with deep project context
  • Multi-agent orchestration — run Cline, Claude Code and other external agents in parallel, consolidating decisions

Dual-Device Sync: Desktop Works, Phone Controls

Nuphus separates "execution" from "control": the desktop is the Agent's hands, your phone is the remote.

  • Same session, synced across devices — the phone connects to the same desktop Agent: messages share one entry point; history, memory and state are shared
  • Real-time event stream — every step (thinking, tool calls, results) streams to the phone over WebSocket
  • Workflow remote control — pause, resume, stop running workflows from your phone
  • Execution trace playback — view the Agent's full trace on the phone; every step is transparent
  • Wi-Fi LAN direct — the phone reaches the local service directly when both devices share the same Wi-Fi, with no official server
  • Your server, your control — Nuphus does not provide an official relay; for remote access, deploy and configure your own relay-server

P2P and custom server connections remain optional user-controlled capabilities.

Local-First, Private by Default

  • Data stays on your machine — conversations, memory, plugins all stored locally
  • Local AI engines — PP-OCRv4 (OCR) and Candle (semantic search) run locally; everyday recognition costs zero API calls
  • 4-layer security — permission gates → human-in-the-loop → injection detection → circuit breaker
  • Model freedom — unified access to OpenAI / Anthropic / DeepSeek / Qwen / Zhipu and other mainstream providers, switch anytime

Built-in Tools: PDF / Image / Video / Audio / Docs

No external tools to install — 23 built-in processing commands:

Category Capabilities
PDF Merge / Compress / Text extraction / Images to PDF / Extract pages / Rotate
Image Compress / Convert / Resize / Stitch / Batch compress / Batch convert
Video Compress / Extract frames / To GIF / Cut clip
Audio Extract audio / Audio convert / Voice clone (cloud)
Docs docx / pptx / xls / pdf → text

More Capabilities

Capability Description
Memory system Cross-session experience accumulation; SQLite + FTS5 + vector semantic search — gets smarter the more you use it
Zero-compile extension Knowledge, skills, workflows, ui-maps are plain-text files; drop into plugin/ and they load
Three-layer vision Built-in OCR (zero API cost) → configurable vision model (complex scenes) → user-guided vision (most flexible fallback)
Deterministic workflows Compile recurring tasks into workflows and run with zero tokens (see philosophy above)
Sound feedback Task done / error / retry all have distinct sounds — know the state without staring at the screen

Installation

One-command npm install (recommended)

A single command installs and auto-matches your platform's binary (Windows x64 / macOS arm64 / Linux x64). No installer download, no Node.js / Rust required:

# Global install (provides the nuphus command)
npm install -g @nuphus/nuphus-desktop

# Or try without installing (no global write)
npx @nuphus/nuphus-desktop

Then type nuphus in your terminal to launch.

First install is large (desktop app bundles local OCR / speech models), please be patient.

Download installers

For users unfamiliar with the command line — no CLI, no Node.js / Rust required:

  1. Download the installer for your platform from the official website (fast in China) or GitHub Releases:
    • Windows: .exe (NSIS installer, per-user, no admin rights needed)
    • macOS: .dmg
    • Linux: .deb / .AppImage
  2. Double-click to install (Windows creates a Nuphus desktop shortcut)
  3. Double-click the shortcut to launch

Build from source (developers)

Prerequisites:

Tool Version Purpose
Rust 1.95.0 (pinned by rust-toolchain.toml) Core engine compilation
Node.js ≥ 20 (vitest 4 does not support 18) Tauri frontend build and frontend tests
Tauri CLI cargo install tauri-cli --version "^2" Desktop app development
git clone https://github.com/mrpulor-gh/nuphus.git
cd nuphus

# Install dependencies (root Tauri CLI + frontend deps)
npm install

# Run in dev mode
npx tauri dev

Quick Start

Configure a model

  1. On first launch, follow the onboarding to pick a provider and enter your API key
  2. Press Enter to finish

You can also skip config with env vars: QWEN_API_KEY="sk-xxx" npx tauri dev

After onboarding, modify config in Settings → Models. API keys are encrypted: on Windows they're encrypted with system-level DPAPI into local config.toml (enc:v1: format, bound to the current user); macOS/Linux currently store plaintext (relying on file permissions; OS credential integration is on the roadmap). Never share or commit this file.

Connect your phone

  1. Make sure the phone and desktop are on the same Wi-Fi LAN
  2. On the desktop, enable the local mobile service in the Phone settings page (default port 18772)
  3. Scan the LAN pairing code, or open the LAN address and enter the pairing password
  4. Add to Home Screen (PWA); use it like an app from then on

Only the local Wi-Fi LAN is used by default. The server address can be changed from the phone pairing page or Network & Connections; remote access requires your own deployed server.


Architecture Overview

Nuphus uses a six-layer architecture, security threaded through every layer:

┌─────────────────────────────────────────────┐
│ Tauri shell                                 │  ← frontend UI + OS capabilities (notify, tray, hotkeys)
├─────────────────────────────────────────────┤
│ Runtime                                     │  ← unified main loop, 3-mode routing (Leader / Workflow / Custom)
├─────────────────────────────────────────────┤
│ Agent                                       │  ← Leader decision / ExecAgent execution / WorkflowAgent design
├─────────────────────────────────────────────┤
│ Transport                                   │  ← multi-provider abstraction (unified access to major AI vendors)
├─────────────────────────────────────────────┤
│ Tools / Memory / Workflow                   │  ← execution infrastructure
├─────────────────────────────────────────────┤
│ Security / Permissions                      │  ← security chain across all layers (injection detection / permission tiers / review)
└─────────────────────────────────────────────┘

Dual-device sync architecture:

┌──────────┐   WebSocket real-time event stream   ┌──────────────┐
│  Phone PWA│ ←────────────────────────────────→  │ desktop mobile│
│(chat/remote)│   POST /message shared entry        │ server(18772)│
└──────────┘                                      └──────┬───────┘
      ↕ Wi-Fi LAN direct (default)                        │ shared session/memory/state
┌────────────────┐                                ┌──────┴───────┐
│ Optional server │ ←── user configured ───────→ │  Nuphus      │
│ (not official)  │                              │  desktop     │
└────────────────┘                                │  Agent engine │
                                                  └──────────────┘

Phone messages go through submit_user_message(source="mobile"), sharing the same leader_agent / busy lock / dedup logic as the desktop — the two devices are two views of one Agent, not two separate systems. Disconnects auto-reconnect with exponential backoff and re-pull history to fill gaps; no messages are lost.

Data flow: user input → Tauri event → Runtime routing → Leader decision → task_dispatch → ExecAgent execution → result return → frontend display (synced to desktop & phone)


Configuration

Nuphus uses a TOML config file; src/config/mod.rs::load_registry searches by priority:

# Path Use
1 <exe_dir>/config.toml Portable deployment
2 ./config.toml Development
3 ~/.config/nuphus/config.toml Linux/macOS user-level
4 ~/.nuphus/config.toml Legacy compatibility
5 <AppData>/nuphus/providers.toml Windows desktop canonical config (anchored by desktop, auto-generated on first launch)

Design Principles

  1. Local-first — data stays local by default; cloud only when you opt in
  2. Minimal mental model — keep every feature simple, avoid over-abstraction
  3. Determinism first — compile to a workflow instead of re-reasoning; reuse instead of rewriting
  4. Long-term first — prefer solutions consistent with the existing architecture and maintainable
  5. Restraint over stacking — every new feature must prove it's irreplaceable
  6. Closed-loop design — every module forms a complete loop from input to output

Contributing

Nuphus is a community-driven open-source project. Besides code, you can help build the ecosystem:

Contribute plugins (coming soon)

Plugin type Description Examples
ui-maps UI layout descriptions for any software (button positions, window identification) Photoshop export panel, enterprise ERP layout
workflows Reusable workflow templates "Daily project backup", "Batch image compression"
skills Domain methodologies and operation guides "Frontend UI design guidelines", "Code patterns for a framework"
knowledge Project domain knowledge docs API references, config notes, architecture docs

All plugins are plain-text files (.md / .json); drop them into the matching plugin/ directory and Nuphus loads them.

Get involved

  • GitHub Issues: bug reports and feature requests
  • GitHub Discussions: usage questions, experience sharing, plugin recommendations

Acknowledgements

v1.1.3 Contributors

This release has no community pull requests; all changes were made by the maintainer.

v1.0.0 Contributors

No external pull requests were merged in this release; all changes were made by the maintainer.

v0.2.31 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@Steooenwolf-666 #107 ChatGPT plan sign-in and Responses inference: generic OAuth, secure credential storage, per-model protocol routing and request constraints
@Steooenwolf-666 #108 Fix IPC parameter casing for execution reviews, inline config and new sessions (top-level camelCase)

v0.2.30 Contributors

No external pull requests were merged in this release; all changes were made by the maintainer.

v0.2.29 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@zhoupeiyu515-ui #105 Fixes session-row hover overlap and stray button hits, restores the ModelsPage test baseline (adds the missing getVisionResolution mock)

v0.2.28 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@zhoupeiyu515-ui #104 Adds quick-filter chips for popular models and multi-keyword (space-OR) filtering

v0.2.24 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@zhoupeiyu515-ui #84 Adds the mobile server / relay threat model and accepted limits to SECURITY.md
@yuansui486 #87 Fixes Markdown rendering for external data points (MarkdownInline exported for reuse)
@yuansui486 #88 Clarifies model connection success feedback and moves model capability probing off the switch path
@Steooenwolf-666 #91 Correctly propagates desktop input and submit-hotkey failures in the external-Agent dispatch sequence

v0.2.23 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@Steooenwolf-666 #67 Keep monthly 29–31 day schedules when re-editing a workflow
@Steooenwolf-666 #70 Show the original path when a mobile image fails to decode
@Steooenwolf-666 #71 Fix loop variable scope check when moving canvas steps
@Steooenwolf-666 #72 Stabilize canvas draft and session snapshot tests
@Steooenwolf-666 #73 Protect external agent task state and preview the latest reported run
@Steooenwolf-666 #74 Add a non-sensitive run parameter scheme for workflows
@Steooenwolf-666 #75 Retry failed images in place on mobile
@fouyzjl #79 Persist base_url in switch_model so an edited endpoint no longer reverts
@zhoupeiyu515-ui #80 Expand only the last conversation's project folder on startup, and fix submenu clipping

v0.2.22 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@yuansui486 #65 Improve workflow node debugging, run evidence and canvas editing

v0.2.21 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@yuansui486 #58 Improve cross-platform desktop execution reliability and workflow progress reporting
@yuansui486 #59 Fix canvas workstation window dragging; add a prototype light/dark toggle
@yuansui486 #61 Refine workflow node forms, variable selection and canvas layout
@zhoupeiyu515-ui #63 Add a TypeSafe console link to the enhanced-judgement model API key row

v0.2.20 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@yuansui486 #56 Improve cross-platform target binding, semantic observation and stable replay
@zhoupeiyu515-ui #57 View desktop-local images on mobile: new /file endpoint with inline rendering

v0.2.19 Contributors

Thanks to the community contributors who submitted pull requests in this release:

Contributor PR Summary
@yuansui486 #52 Semantic desktop automation foundation (UIA/Accessibility): observation, bounded candidates, pre/post execution verification
@yuansui486 #54 Enhanced judgement model: standalone configuration with structured selection from local bounded candidates
@zhoupeiyu515-ui #50 Harden log rotation: rename failures no longer lose history

Contributors of earlier releases are recorded in CHANGELOG.md.

License

Copyright © 2026 Nuphus Team · Apache License 2.0