# Operance > Local-first AI desktop action layer for controlling your computer with natural language. - **Type:** MCP server - **Install:** `agentstack add mcp-raunakkathuria-operance` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [raunakkathuria](https://agentstack.voostack.com/s/raunakkathuria) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [raunakkathuria](https://github.com/raunakkathuria) - **Source:** https://github.com/raunakkathuria/operance - **Website:** https://operance.dev ## Install ```sh agentstack add mcp-raunakkathuria-operance ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Operance Turn intent into action. **Operance is a local-first AI desktop action layer that lets you control your computer with natural language.** Speak or type what you want, and Operance turns that intent into safe, typed desktop actions before anything runs. The current public beta is Fedora KDE Plasma Wayland first and uses a tray-first click-to-talk workflow. It is ready for outside developers and early adopters to install, test, report issues, and help extend. Today, Operance can open apps and websites, focus or quit apps with confirmation, list recent files, list or search known folders by file name, show basic file metadata, manage Desktop files or folders with confirmation, list, find, or switch windows, answer desktop-status questions, and control basic audio state. It also supports safe JSON desktop skill packs for adding exact phrase shortcuts that emit existing typed actions without changing the portable core. The tray and verified commands work without an AI model. A local OpenAI-compatible model, such as an Ollama-served Qwen model, can be enabled as a bounded planner fallback after `operance --planner-readiness` reports it is safe to enable. Model output is still constrained to Operance's typed action schema and goes through validation, policy, and confirmation gates. For developers, Operance is also built to be extended. Under the hood, it has a shared portable core, per-platform providers and adapters, and an MCP-compatible control surface. The current delivery scope stays Linux-first while keeping the core portable for later Windows and macOS adapters. Platform roadmap: - Phase 1: Linux/KDE/Wayland - Phase 2: Windows - Phase 3: macOS The implementation stays Linux-first today. The portable core remains shared across platforms, including the voice pipeline orchestration, planner, typed action schema, safety model, and MCP server, while platform providers own host-specific readiness, setup workflow, and release-verification rules and OS-specific execution or input translation stays behind per-platform adapters. That keeps the current delivery scope simple without closing off the later Windows and macOS paths. Windows and macOS provider scaffolds exist for adapter authors, but they are intentionally unverified and block live desktop commands until native adapters are implemented. ## Public Beta Quickstart Use the packaged Fedora RPM for the public beta experience. From the current GitHub release, run the setup script against that release's asset URL: ```bash curl -fsSLO https://github.com/raunakkathuria/operance/releases/download//setup.sh bash ./setup.sh --release-url https://github.com/raunakkathuria/operance/releases/download/ operance --version operance --installed-smoke operance --public-beta-checklist operance --beta-feedback ``` If you already downloaded the RPM from the same release, the stable local package setup path is: ```bash bash ./setup.sh --package ./operance-0.1.0-1.noarch.rpm operance --version operance --installed-smoke operance --public-beta-checklist operance --beta-feedback ``` `operance --installed-smoke`, `operance --public-beta-checklist`, and tray **Setup and status** now include one explicit next action. When the install is ready, the next action is to click the tray icon once and say `open browser`. Then click the tray icon and say: ```text open browser open the browser open google.com go to google.com search google for linux automation search the web for linux automation open firefox open downloads open folder downloads list files in downloads find file named notes.txt search documents for invoice show details for notes.txt show recent downloads open the first one what can I say what did you hear are you listening is local AI ready why did that fail what apps are open is firefox open switch to it switch to firefox window what time is it wifi status what is the volume set volume to 50 percent ``` If anything fails, collect a support bundle before changing the machine: ```bash operance --support-bundle ``` The bundle includes `issue-report.md`, a redacted paste-ready GitHub issue draft. If you only need the draft without creating an archive, run: ```bash operance --issue-report ``` For one combined install, verify, try, and report checklist, run: ```bash operance --public-beta-checklist operance --beta-feedback ``` The tray menu exposes **Setup and status**, **Try commands**, **Beta feedback guide**, **Supported commands**, **Report an issue**, optional always-on listening controls, recent interaction details, and release update checks. Detailed diagnostics such as planner readiness, installed-smoke output, and raw support snapshots remain available from the CLI and the setup/status flow instead of crowding the default tray menu. The release artifact set includes `setup.sh` beside the RPM, checksums, and manifest. The repo-local copy lives at `scripts/setup.sh`. `--release-url` downloads the manifest, checksums, setup script, and RPM from the same release asset base URL, verifies `SHA256SUMS`, then runs the same install, tray startup, installed-smoke, command catalog, and support-bundle flow as `--package`. Use [docs/release/public-beta.md](docs/release/public-beta.md) for the public beta install, local AI planner, release artifact, and feedback path. The repository also includes a static public landing page at [site/index.html](site/index.html). It explains Operance for new users and links back to GitHub-rendered canonical Markdown docs for developer details. The site build entrypoint is `./scripts/build_site.sh`, which writes a self-contained artifact to `dist/pages/` by copying the shared brand icon into the deployment root. The Cloudflare Workers Static Assets deployment is configured in `wrangler.toml`: use `./scripts/build_site.sh` as the build command and `npx wrangler deploy` as the deploy command. ## Developer Quickstart Use this path when developing Operance itself from a source checkout: ```bash ./scripts/install_linux_dev.sh --ui --voice .venv/bin/python -m operance.cli --version .venv/bin/python -m operance.cli --about .venv/bin/python -m operance.cli --check-updates .venv/bin/python -m operance.cli --doctor .venv/bin/python -m operance.cli --getting-started .venv/bin/python -m operance.cli --supported-commands --supported-commands-available-only .venv/bin/python -m operance.cli --skills ./scripts/run_mvp.sh ./scripts/run_checkout_smoke.sh ``` Try a few live commands from the verified subset: ```bash OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what time is it" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what is my battery level" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "wifi status" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "open firefox" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "open localhost:3000" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "show recent files" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "what can I say" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "is local AI ready" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "list windows" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "switch to window firefox" OPERANCE_DEVELOPER_MODE=0 .venv/bin/python -m operance.cli --transcript "set volume to 50 percent" ``` If the MVP path fails or you need to file a bug, collect the current issue artifact with: ```bash .venv/bin/python -m operance.cli --support-bundle ``` That archive includes a generated `issue-report.md` draft. For a quick paste-only draft from a source checkout, use: ```bash .venv/bin/python -m operance.cli --issue-report ``` For release-readiness work, use the repository gate that combines tests, branding guard, source-checkout smoke, reset-aware Fedora package gate dry-run, and the installed desktop smoke checklist. The gate also runs controlled live command smoke against a temporary desktop fixture, so file-command verification does not touch your real Desktop directory: ```bash ./scripts/run_release_readiness_gate.sh ``` Before tagging a packaged release candidate on Fedora KDE, run the packaged evidence gate from the same checkout. It rebuilds the `mvp` RPM, verifies the artifact, installs it with stale user-service reset, runs installed desktop smoke, captures a support bundle from the installed command, and then prints the manual tray click-to-talk checks that still require your active desktop session: ```bash ./scripts/run_package_evidence_gate.sh ``` Current assumptions for that path: - Linux - KDE Plasma on Wayland - local source checkout - optional voice and UI extras installed when you want the tray and click-to-talk path ## Current Public Position Operance is ready for a **Fedora KDE Wayland public beta** for outside developers and early adopters. It is not yet a broad public desktop release. - Recommended public beta path: Fedora RPM install of the `mvp` runtime profile through `setup.sh` - Developer/source path: source checkout with `./scripts/install_linux_dev.sh --ui --voice`, `.venv/bin/python -m operance.cli --doctor`, `./scripts/run_mvp.sh`, and `./scripts/run_checkout_smoke.sh` - Default interaction: tray plus click-to-talk - Optional always-on listening: the tray can start or stop the voice-loop service when the voice runtime is configured - The supported Fedora package path now vendors the tray UI and STT runtime dependencies needed for the MVP tray plus click-to-talk path - First installed-package diagnostic: `operance --installed-smoke` - Public beta install, verify, try, and report checklist: `operance --public-beta-checklist` - 10-minute beta feedback loop: `operance --beta-feedback` - First-run activation diagnostic: `operance --getting-started` - Explicit release-channel check: `operance --check-updates` - Product-facing local AI setup guide: `operance --local-ai-coach` - Local AI planner status check: `operance --planner-status` - Paste-ready feedback draft: `operance --issue-report` - Stable packaged setup entrypoint: `./scripts/setup.sh --package ./operance-0.1.0-1.noarch.rpm` - Release-asset setup entrypoint: `./setup.sh --release-url https://github.com/raunakkathuria/operance/releases/download/` - Tray-first onboarding: setup/status, try commands, beta feedback guide, supported commands, issue reporting, recent interaction details, update checks, and optional always-on listening controls are available from the tray menu - First-run next action: installed smoke, public beta checklist, and tray setup/status lead with the next user action, such as clicking the tray icon and saying `open browser` when the package is ready - Public beta distribution guide: [docs/release/public-beta.md](docs/release/public-beta.md) - Packaged release-candidate evidence gate: `./scripts/run_package_evidence_gate.sh` - Wake-word and TTS assets remain optional and are not part of the packaged support contract; spoken response text is available even when TTS audio is not configured - Windows and macOS are architecture targets only; their current providers are scaffolds, not supported runtimes Always-on listening is optional and experimental unless a model-backed wake-word asset is configured. For the current beta, the most reliable path is still click-to-talk. If you start the always-on loop with the built-in energy fallback, treat it as a sound trigger and use two steps: ```text Operance open browser ``` The same pattern applies to other commands, such as `go to google.com`, `search the web for linux automation`, or `what time is it`. You can also try one continuous phrase such as `Operance open browser`; the voice loop feeds the trigger frame into command capture and trims short wake residue when the command starter is recognized. If the energy fallback triggers and no command follows, the tray reports `Sound trigger detected, but no command followed.` and returns to waiting. If it only captures a clipped tail fragment such as `is it?`, the tray reports that it only heard part of a command and asks you to repeat the full command after `Operance`. A future model-backed public wake phrase is planned as `Hey Ops`, but the current package does not claim that phrase as supported until a model-backed detector is configured. Click-to-talk remains the recommended beta path when you want the most responsive command capture. Not yet claimed: - broad distro or desktop-environment support - Windows or macOS delivery - wake-word-first as the default interaction model - a zero-setup consumer install story - a skills marketplace or searchable skill registry Use [docs/release/public-beta.md](docs/release/public-beta.md) for the public beta distribution path, [docs/release/public-handoff.md](docs/release/public-handoff.md) for the current public handoff, [docs/release/release-readiness.md](docs/release/release-readiness.md) for the release stop line, [docs/release/fedora-checklist.md](docs/release/fedora-checklist.md) for the exact Fedora gate, [docs/release/release-plan.md](docs/release/release-plan.md) for the current release sequence, [docs/requirements/linux.md](docs/requirements/linux.md) for Linux setup, packaging, and advanced diagnostics, and [docs/release/public-repo-metadata.md](docs/release/public-repo-metadata.md) for suggested GitHub About metadata. ## How To Contribute Anyone can contribute right now through one of these paths: - test Operance on Fedora KDE Wayland and file reproducible issues with a support bundle - improve onboarding, troubleshooting, and public handoff docs - add safe JSON phrase shortcuts through desktop skill packs - add tests and bug fixes that make tray plus click-to-talk more reliable - harden packaging, setup, doctor, and release-gate workflows This is still a founder-maintained public beta. Small, focused fixes and high-quality issue reports are more useful than broad rewrites. Start with [CONTRIBUTING.md](CONTRIBUTING.md). For larger product or architecture changes, read [docs/specs/README.md](docs/specs/README.md), the product PRD in [docs/specs/product-prd.md](docs/specs/product-prd.md), and the current [beta product direction](docs/specs/beta-product-direction.md) before coding. Non-trivial work should start from a goal-spec GitHub issue so scope, safety, tests, and docs are agreed before implementation. If you want to add a safe phrase shortcut for existing behavior, read [docs/contributing/skill-packs.md](docs/contributing/skill-packs.md). If you want to add a new desktop command, read [docs/contributing/command-authoring.md](docs/contributing/command-authoring.md) before changing core modules. If you are reporting a problem instead of sending a patch, attach the output artifact from `.venv/bin/python -m operance.cli --support-bundle` whenever possible and paste the bundled `issue-report.md` draft into the issue body. This repository already contains the Phase 0A foundation plus the later planner, MCP, Linux-adapter, tray, voice, and release-tooling slices needed for the current public beta. Keep `README.md` for the public stop line and use [CHANGELOG.md](CHANGELOG.md) when you need the feature-by-feature implementation history. ## Current status Operance already has a coherent Linux-first public beta path: a typed and validated runtime, tray plus click-to-talk MVP flow, and Fedora packaging or support tooling. For the current public handoff, the supported command surface is intentionally narrower than the full implemented runtime. Use [CHANGELOG.md](CHANGELOG.md) for the feature-by-feature implementation history. What works now: - Core runtime: typed action models, deterministic intent matching, validator and policy enforcement, local audit logging, bounded local planner fallback, and MCP-compatible control surfaces. - Verified co … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [raunakkathuria](https://github.com/raunakkathuria) - **Source:** [raunakkathuria/operance](https://github.com/raunakkathuria/operance) - **License:** MIT - **Homepage:** https://operance.dev Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-raunakkathuria-operance - Seller: https://agentstack.voostack.com/s/raunakkathuria - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.