Skip to main content
Glama
README.md
# FreeRemoteDesktop

**Your computer. Your model. Your rules.**

A model-neutral, self-hosted Model Context Protocol (MCP) desktop bridge.
FreeRemoteDesktop does not operate an LLM, bypass model subscriptions, or promise free tokens.
It replaces metered third-party desktop execution with a local tool server. MIT licensed.

## One-click Claude Desktop install (MCP Bundle)

Build and install the `FreeRemoteDesktop-0.3.0.mcpb` bundle using `python pack_mcpb.py`.
Choose this bundle from Claude Desktop's Extensions > Install Extension.
Select your approved workspace when prompted. Requires an MCPB host supporting the
UV runtime. This package does **not** embed Python; the host UV runtime manages it.
The manifest is validated with `@anthropic-ai/mcpb`; actual Claude GUI installation
has not yet been tested.

## Engineering Studio and offline operations

- Zero-model-call engineering recipes: python frd.py recipes, then use
  python frd.py run git_status --workspace /your/project.
- Optional local-model Studio: python local_studio.py, then visit
  http://127.0.0.1:8899 on the computer. Ollama and a tool-capable model required.
- Live private screen preview and browser actions are disabled by default.
- Remote ChatGPT bridge uses the official Secure MCP Tunnel with user-supplied
  credentials and appropriate ChatGPT workspace entitlements.

Read CONNECTIVITY.md for setup and limitations and ROADMAP.md for ship gates.

## Quick start

Requirements: Python 3.10+; Windows, macOS or Linux (GUI capture is primarily tested on Windows).

```sh
python setup.py plan --client codex
python setup.py install --client codex
python test_product.py
```

For Claude Desktop:

```sh
python setup.py plan --client claude-desktop
python setup.py install --client claude-desktop
```

Restart the selected client. Invoke `desktop_status` to confirm.
Fresh installations start with zero approved roots; choose one project directory in the dashboard or edit the config. Configuration is created at `~/.freeremotedesktop/config.json`, and existing
Codex/Claude config is backed up before editing. The installer never silently
changes another agent's configuration.

## Tools

| Tool | Default |
| --- | --- |
| desktop_status | enabled |
| list_directory | enabled within roots |
| read_text_file | enabled within roots |
| search_text / read_lines | bounded and enabled within roots |
| list_job_recipes / job_history | enabled |
| run_job | requires local allow_jobs permission |
| search_text / read_lines | enabled within roots and bounded |
| list_job_recipes / job_history | enabled |
| run_job | disabled; explicit local permission required |
| write_text_file | disabled |
| run_command | disabled; exact command allowlist |
| capture_screen | disabled; requires Pillow |
| gui_click / gui_type / gui_hotkey | disabled; requires PyAutoGUI |
| browser_navigate / browser_snapshot / browser_screenshot / browser_click / browser_fill | disabled; Playwright + hostname allowlist; click also requires allow_gui |

Set the exact approved workspace paths and enable capabilities locally by editing
`~/.freeremotedesktop/config.json`. The user must explicitly opt in for every dangerous
capability. Avoid adding sensitive paths to `roots`. File-name checks are not a DLP solution.

Optional dependencies:
```sh
python -m pip install pillow pyautogui playwright
python -m playwright install chromium  # optional if Google Chrome is installed
```
The normal read-only installation has **zero third-party Python dependencies**.

## Offline mode — zero AI inference calls

The built-in `frd.py` CLI runs locally with Python and no model, API key or chatbot:

```sh
python frd.py recipes
python frd.py status
python frd.py run git_status --workspace /absolute/path/to/repository
python frd.py run python_compile --workspace /absolute/path/to/project
python frd.py history
```

Opt in with `allow_jobs: true` in your local permission configuration, and set the
approved root to the project. `python_tests` separately requires
`allow_test_execution: true` because tests execute project-defined code.

To run a deterministic recipe continuously without invoking any model:

```sh
python frd.py schedule git_status --workspace /absolute/path/to/repository --every-seconds 3600
```

This foreground scheduler runs until interrupted; it is *not* a persistent OS service.
No AI-generated changes or new instructions occur in offline mode. Workflow receipts
are stored in `~/.freeremotedesktop/jobs.jsonl`.

## Token-efficient MCP retrieval

Use `search_text` to return up to 50 relevant line previews rather than entire files,
and `read_lines` for exact 1–150-line windows. All use the approved root policy,
skipping known sensitive filename patterns. This reduces irrelevant context, not the
per-token rate charged by an AI provider.

## HTTP mode (local integration only)

```sh
# set FRD_BEARER_TOKEN to a strong, random secret using your OS secure environment settings
python server.py --transport http --port 8765
```

The HTTP listener binds **127.0.0.1 only**, requires bearer authentication, and is
not a production remote MCP deployment. Never publicly proxy it as-is. A remote
deployment needs OAuth, per-device user authentication, hardened host/origin and
network controls, token rotation, TLS, abuse prevention, and an audit review.

## Client/platform matrix

- **Codex and Claude Desktop:** supported via STDIO installer.
- **Other STDIO MCP agents:** configure command `python`, args `/absolute/path/server.py`.
- **Claude web/mobile:** needs an authenticated remote HTTPS MCP gateway; not supplied yet.
- **ChatGPT:** remote MCP connector availability and write tools depend on plan; not supplied yet.
- **@FreeRemoteDesktop:** availability depends on the host client's tool/plugin naming UI.
- **Computer vision:** `capture_screen` returns image bytes when enabled; host client must support rendering or consuming them.

## Security model

No privileged agent, daemon, unattended background service, or public endpoint installed.
Writes and control are opt-in. Protected filename/extension denylist, configured roots,
output/timeout caps, command exact-match allowlist, explicit overwrite flag, and JSONL
audit trail. These are protections, **not a sandbox**. Run under a low-privilege OS user.
Do not use on shared machines without additional OS account separation.
GUI and browser tools can expose confidential information; enable only with supervision.
No telemetry sent to Efficient Labs or any third party by this package.

## Architecture

```
MCP client -> STDIO transport -> policy-gated tools -> local computer
                           \-> optional authenticated loopback HTTP
```

## Current release status

**Developer preview v0.3.0; not ready for public production.** Remote authentication,
visual UI, full screen-streaming, per-action approvals,
machine-level integration tests, signed installers, packaging, cross-platform CI and
public vulnerability review remain to be implemented and verified.

## License

MIT. Copyright 2026 Efficient Labs contributors.

TDQS

B3.4/5.0

Scored across 19 tools

Disambiguation4/5

Most tools target clearly distinct resources or capability areas: jobs, filesystem, command execution, GUI, and browser. The main possible confusion is read_text_file versus read_lines, and to a lesser extent capture_screen versus browser_screenshot, but their descriptions make the contexts reasonably clear.

Naming Consistency4/5

Names are predominantly snake_case and action-oriented, with clear namespaced prefixes for GUI and browser operations. Minor deviations such as job_history and desktop_status use noun-first phrasing, but the overall convention remains readable and predictable.

Tool Count4/5

Nineteen tools is somewhat large, but the server covers several distinct capability families: jobs, filesystem, command execution, desktop GUI, and browser automation. Each tool appears to earn its place within those areas rather than being redundant bloat.

Completeness4/5

The surface covers core workflows for file reading/writing/listing/searching, command execution, job running/history, screen capture, GUI input, and browser interaction. Some gaps exist, such as no explicit file delete/move operations and limited browser navigation/history controls, but agents can generally work around them or the omissions are consistent with the safety-first design.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues