RunOnMine

Let AI work. Keep control local.

A local-first Model Context Protocol (MCP) gateway and desktop control center for macOS, Linux, and Windows.

Website · Install · Quick start · How it works · Security · Documentation

RunOnMine sits between an AI assistant and a machine you own. It gives the AI controlled access to files, terminals, browsers, and desktop applications while keeping execution, policy, credentials, approvals, and audit records on your machine.

Instead of exposing SSH, a raw shell, or a public MCP listener, RunOnMine checks who is asking, what tool is being called, which resource it targets, and whether the action needs local approval before anything executes.

What you get

Capability	RunOnMine boundary
Files	AI access is limited to directories you explicitly select.
Terminal & processes	Commands are evaluated by policy and can require exact local approval.
Browser automation	Uses an isolated browser profile with network and private-address protections.
Desktop control	Native desktop actions run only when the OS/session permits them.
Remote connectivity	Managed tunnels connect outward; the MCP server stays on loopback.
Safety controls	Local approvals, explicit deny rules, tamper-evident audit, diagnostics, and Emergency Lock.

The AI model still runs in the AI service you choose. Tool execution happens through the RunOnMine boundary on the machine you control.

How it works

1. An AI client sends an MCP tool request through a configured connector.
2. RunOnMine evaluates connector/requester identity, selected roots, policy, resource scope, and any exact-action approval.
3. The action is allowed, held for local approval, or denied.
4. The result is returned to the AI and the local audit trail is updated.

RunOnMine supports local stdio, opt-in authenticated loopback HTTP, Cloudflare connectors, and OpenAI Secure MCP Tunnel. See Connection modes for the full connector model.

Install

Note

RunOnMine is pre-release software. The latest public beta is v0.1.0-beta.1. macOS is ad-hoc signed but not Developer ID signed or notarized, and the Windows installer is not Authenticode signed. Gatekeeper or SmartScreen may therefore warn on downloaded builds. Each primary artifact has an adjacent SHA-256 checksum, and target-specific CycloneDX SBOMs are attached to the release.

Platform	Public beta download
Windows x86_64	runonmine-desktop_0.1.0-beta.1_x64-setup.exe
Linux x86_64 — Desktop	runonmine-desktop_0.1.0-beta.1_amd64.deb
Linux x86_64 — Headless	runonmine_0.1.0-beta.1_amd64.deb
Linux ARM64 — Headless	runonmine_0.1.0-beta.1_arm64.deb
macOS 12+ — Universal	RunOnMine_0.1.0-beta.1_universal.dmg

Portable unsigned archives, checksums, and SBOMs are available on the release page. Source builds remain supported for developers and platforms not covered by the packaged beta.

Windows x86_64

Run runonmine-desktop_0.1.0-beta.1_x64-setup.exe. It is a current-user install; the optional LocalSystem helper is not installed or activated unless you explicitly request it later. Because this beta is not Authenticode signed, Windows SmartScreen may show an unrecognized-publisher warning.

After installation, initialize the project directory the AI may access:

$rom = Join-Path $env:LOCALAPPDATA "RunOnMine\runonmine.exe"
& $rom setup --root "C:\path\to\your\project"
& $rom service install

Launch RunOnMine from the Start Menu to open the security control center. See the Windows guide for package lifecycle, uninstall behavior, and the optional privileged helper.

Linux desktop (x86_64)

Download runonmine-desktop_0.1.0-beta.1_amd64.deb, then install it with:

sudo apt install ./runonmine-desktop_0.1.0-beta.1_amd64.deb
runonmine setup --root "$HOME/Projects/my-project"
runonmine service install
runonmine-desktop

For headless x86_64 or ARM64 systems, use the corresponding runonmine_* DEB. Headless services need an explicit secure secret-store setup, so follow the Linux and VPS guide rather than copying desktop service assumptions to a server.

macOS 12+

Open RunOnMine_0.1.0-beta.1_universal.dmg and copy RunOnMine.app to Applications. The beta uses verified ad-hoc code signatures and hardened runtime, but it is not Apple Developer ID signed or notarized, so Gatekeeper may warn or block a quarantined download.

RunOnMine does not bypass macOS consent prompts. Desktop input/capture may require Accessibility or Screen Recording permission. See the macOS guide.

Quick start

1. Select only the directories AI may use

runonmine setup --root /absolute/path/to/project

Do not select your whole home directory unless that broader access is genuinely required.

2. Start with the Safe policy

runonmine policy show

New connectors start with Safe: reads are available, writes/execution ask locally, and administrator execution is denied. Developer is intended for trusted selected-root coding work. Automation (full in the CLI) is the broadest local preset and should be used only on a dedicated or tightly scoped machine.

3. Run the agent

For a one-off foreground session:

runonmine agent run

Or install the normal per-user service so RunOnMine can recover with your login session:

runonmine service install
runonmine service status

4. Connect your AI client

The smallest local surface is the default stdio connector:

runonmine connect list
runonmine mcp stdio --connector <local-connector-id>

Authenticated loopback HTTP is opt-in and its bearer token is never printed:

runonmine connect local-http enable \
  --token-output /absolute/private/local-http.json

For remote access, use a managed Cloudflare or OpenAI connector instead of opening the MCP listener to the network. See Connection modes.

Everyday controls

Task	Command / UI
Review pending actions	Approvals in the desktop app or runonmine approvals list
Approve once	runonmine approvals approve <id> --once
Inspect policy	runonmine policy show
Check health	runonmine doctor
Create a redacted support bundle	runonmine support-bundle --output runonmine-support.zip
Stop access immediately	runonmine lock

runonmine lock stops the agent and managed connectors, rejects queued approvals, revokes live OAuth sessions, and invalidates temporary connector credentials.

Why not direct SSH or a raw MCP server?

Direct machine access	RunOnMine
Broad account authority	Capability- and resource-scoped policy
One credential often unlocks everything	Connector/requester identity is evaluated per action
No built-in human checkpoint	Dangerous actions can require exact local approval
Public listener or inbound firewall rule	MCP remains on loopback; managed tunnels connect outward
Ad-hoc logs	Tamper-evident audit plus Emergency Lock

Security at a glance

RunOnMine is designed to make the machine boundary visible rather than pretend machine automation is harmless:

• MCP is never bound directly to a public network interface.
• Remote connectors cannot approve their own dangerous requests.
• Remote administrator execution is denied by a non-bypassable safety ceiling.
• Shell processes start from a cleared environment; Windows PowerShell profiles are disabled.
• The optional privileged helper is absent by default and requires separate, explicit installation.
• Filesystem tools operate inside explicitly selected roots.
• Browser automation uses an isolated profile instead of the user’s daily browser profile.
• Secrets stay in the operating-system credential store or the documented encrypted headless fallback.
• Audit records are tamper-evident and avoid storing raw secrets or command payloads.

Warning

Shell, browser, desktop, and privileged tools can make destructive or external changes. RunOnMine is a security boundary and approval system, not a sandbox. Give the agent only the account authority and selected roots it actually needs.

Read the Permissions model, Threat model, and Browser security before enabling broader write or execution capabilities.

Components

• runonmine — setup, connectors, policy, approvals, service lifecycle, diagnostics, audit, and Emergency Lock.
• runonmine-agent — local MCP server and connector supervisor.
• runonmine-desktop — security control center for approvals, connections, permissions, OAuth, audit, and diagnostics.
• runonmine-helper — optional separately installed privileged helper.

Project status

RunOnMine is still pre-release software. The repository records release state in machine-readable form: acceptance/release-candidate.toml identifies the frozen source candidate and acceptance/release-gates.toml records which acceptance and security gates actually passed.

Public beta may be distributed unsigned when that limitation is stated prominently and every required public-beta gate passes. Unsigned artifacts do not establish publisher identity or operating-system trust and must not be presented as production-signed builds.

Documentation

Start with the documentation index.

• Get started: secure onboarding and troubleshooting
• Platforms: macOS, Linux/VPS, and Windows
• Architecture: architecture, connection modes, and MCP tools
• Security: permissions, threat model, audit integrity, and privileged helper
• Quality & release: testing, release acceptance, and release process
• Help: support and security reporting

Development

RunOnMine is a Rust workspace pinned to Rust 1.95.0. Keep Cargo.lock committed. Before opening a pull request, run:

python3 scripts/ci/check-docs.py
cargo run --locked -p xtask -- verify

On supported headless Linux development hosts, use --headless. See CONTRIBUTING.md for security-sensitive change requirements and the complete contributor workflow.

License

Apache License 2.0. See LICENSE.