English | 简体中文
One sentence: let Muse read and write files in specific folders on your Windows PC.
You say "write me a Python script and put it in my Documents" — seconds later the file is on your disk. No more copy-pasting code out of chat.
flowchart LR
PC["Windows PC<br/>muse-file-api.py<br/>listens on 127.0.0.1:18790 only<br/>whitelisted folders only"]
NET["Internet<br/>Cloudflare Tunnel<br/>TLS encrypted"]
CLI["Client<br/>pcfile.py / curl<br/>any HTTP client"]
CLI --> NET --> PC
Made for Muse first: the installer, the docs, and CONNECTOR-BRIEF.md (a paste-ready setup brief for Muse) all assume Muse on the other end. The API itself is plain HTTPS + bearer token, so any HTTP client can use it too.
This project exists because Muse currently has no official desktop app for Windows or Linux — this bridge is a workaround for that gap. If Meta ever ships official Windows/Linux apps, this project will be retired and no longer maintained.
- A Windows 10/11 PC, connected to the internet
- About 10 minutes
- No admin rights needed, no Python knowledge needed
Click Code → Download ZIP at the top right of this page, then unzip it anywhere (D:, C:, wherever — just remember where).
Open the unzipped folder (the one containing install.ps1), right-click an empty spot and choose "Open in Terminal" (Windows 11; on Windows 10, hold Shift, right-click, and choose "Open PowerShell window here"), then paste the following and press Enter:
powershell -ExecutionPolicy Bypass -File .\install.ps1No terminal option in the right-click menu? Open PowerShell from the Start menu, then
cdinto the unzipped folder (the level where you can seeinstall.ps1), e.g.:cd D:\muse-file-bridge-main\muse-file-bridge-main
The script installs Python and cloudflared automatically (via winget). It will ask a few questions:
| Prompt | Recommendation |
|---|---|
| Which directories may Muse access? (comma-separated, Enter for default) | Press Enter. The default is Documents\MuseBridge, which the script creates automatically |
| Allow Muse to write files? First time, read-only is recommended [y/N] | Type n on first install. Read-only is the safe default; writes can be enabled later |
| Tunnel mode: [1] named tunnel (stable, needs a domain) [2] quick tunnel (throwaway) | Choose 2 for a first try. Choose 1 later when you have your own domain on Cloudflare |
Choosing 2 (quick tunnel): at the end you will receive an address like https://random-words.trycloudflare.com. It changes every time the PC restarts — suitable for evaluation only.
Choosing 1 (named tunnel): a browser window will open for Cloudflare login and authorization; you will then enter a public hostname (e.g. bridge.yourdomain.com).
"All done!" indicates a successful install. The installer registers two auto-start tasks (MuseFileBridge API and MuseFileBridge Tunnel) — no console windows; they run silently in the background and restart on failure.
Note: when the PC sleeps or you sign out, both tasks stop and Muse loses connection — this is the most common cause of sudden disconnects. No connection during sleep is normal; it resumes automatically after wake, so you don't need to set sleep to "Never". You do need to stay signed in (locking the screen is fine; signing out is not).
Send the public address (the full https://...) to Muse.
Muse will send you a secure card. Open this file in Notepad:
C:\Users\YourName\.muse-bridge\token
Copy the long token and paste it into the card. The token is a password: enter it into the card only, never paste it into chat (the card is encrypted end-to-end; chat is not).
First confirm the server is alive locally (run in PowerShell):
$t = (Get-Content "$env:USERPROFILE\.muse-bridge\token" -Raw).Trim()
Invoke-RestMethod -Headers @{Authorization = "Bearer $t"} http://127.0.0.1:18790/api/healthok : True means the server is fine (replace 18790 if you changed the port). Then open your public address in a browser: a 401, an "unauthorized" prompt, or a browser error page all mean the tunnel is through (it's just missing the token); a spinning timeout means the tunnel isn't up or the PC is asleep.
If both look good, tell Muse: "list the files in my bridge folder".
If you chose read-only in step 2 (typed n), write attempts will be rejected — this is expected behavior, indicating the read-only protection is active. To enable writes later: open C:\Users\YourName\.muse-bridge\config.json in Notepad, change read_only to false, save; then open Task Scheduler (search taskschd.msc in the Start menu), find MuseFileBridge API, right-click → Restart.
- Muse only sees folders you approve. If you only opened
Documents\MuseBridge, your Desktop, Downloads, and everything else on D: are invisible and inaccessible...traversal, absolute paths, and symlink escapes are rejected. This is a hard server-side restriction. - The server only listens locally. It binds to
127.0.0.1— unreachable from your LAN or the internet except through your own tunnel. - The token is a password. It exists only in the token file on your PC (file permissions restricted to your user) and is entered into the secure card. Rotate it anytime with
python client/pcfile.py rotate-token— the old token is invalidated immediately; the new one is written only to your PC's file. - Read-only by default. Start in read-only mode, confirm the assistant behaves as expected, then enable writes manually.
- Everything is logged. Every read and write is recorded in
C:\Users\YourName\.muse-bridge\audit.log(one JSON object per line) for later review. - Writes are atomic. An interrupted transfer never leaves a half-written file.
- Muse cannot delete your files. There is intentionally no delete endpoint.
- Clean uninstall supported. See "Uninstall" below.
-
Open the folder you unzipped earlier (the one containing
uninstall.ps1), right-click an empty spot and choose "Open in Terminal" (Windows 11; on Windows 10, hold Shift, right-click → "Open PowerShell window here"), then run:powershell -ExecutionPolicy Bypass -File .\uninstall.ps1
-
The script first removes the two auto-start tasks (
MuseFileBridge APIandMuseFileBridge Tunnel); the service stops immediately. -
It then asks whether to also delete
C:\Users\YourName\.muse-bridge(configuration, whitelist, and token):- Type
y: everything is deleted and unrecoverable. A future reinstall will start fresh. - Press Enter (
n): configuration and token are kept. Re-runninginstall.ps1later resumes without reconfiguration.
- Type
What uninstall does not remove:
- Your whitelisted folders themselves (e.g. files inside
Documents\MuseBridge) — the uninstaller never touches your files. - Python and cloudflared — both are general-purpose tools that other software may use.
Optional: if you created a named tunnel and want to remove it from Cloudflare as well:
cloudflared tunnel delete muse-bridge(Quick tunnels expire automatically when stopped — no action needed.)
If the unzipped folder was already deleted, remove manually: search
taskschd.mscin the Start menu to open Task Scheduler, findMuseFileBridge APIandMuseFileBridge Tunnel, right-click → Delete; then manually delete theC:\Users\YourName\.muse-bridgefolder if you want the configuration gone too.
MCP servers only serve MCP clients. If your assistant can't speak MCP (or simply can't reach your machine), this plain HTTPS API is the pragmatic alternative: anything that can do HTTPS with a bearer token can use it.
python server\muse-file-api.pyThe first run generates an access token and prints it — save it, it's shown only once. It also writes a default config that exposes only an empty Documents\MuseBridge folder, in read-only mode — safe to run as-is. To expose more, edit %USERPROFILE%\.muse-bridge\config.json:
{
"port": 18790,
"read_only": false,
"roots": {
"projects": "D:\\Projects",
"plugins": "D:\\MyPlugins"
}
}Restart the script after editing. Manual tunnel setup:
cloudflared tunnel login
cloudflared tunnel create muse-bridge
cloudflared tunnel route dns muse-bridge bridge.yourdomain.com
cloudflared tunnel run --url http://127.0.0.1:18790 muse-bridgeWindows PowerShell:
$env:MUSE_BRIDGE_TOKEN="<the token from step 3>"
$env:MUSE_BRIDGE_URL="https://bridge.yourdomain.com"
python client\pcfile.py health
python client\pcfile.py list projects
python client\pcfile.py read projects notes/todo.txt
python client\pcfile.py write projects notes/todo.txt ./todo.txt
python client\pcfile.py mkdir projects new-folder
python client\pcfile.py sync .\my-plugin plugins my-plugin # upload a whole folderLinux / macOS:
export MUSE_BRIDGE_TOKEN="<the token from step 3>"
export MUSE_BRIDGE_URL="https://bridge.yourdomain.com"
python client/pcfile.py health
python client/pcfile.py list projects
python client/pcfile.py read projects notes/todo.txt
python client/pcfile.py write projects notes/todo.txt ./todo.txt
python client/pcfile.py mkdir projects new-folder
python client/pcfile.py sync ./my-plugin plugins my-plugin # upload a whole folderThe client refuses plain http:// URLs — pass --allow-http only for local testing against 127.0.0.1.
Every endpoint requires Authorization: Bearer <token>.
| Method | Path | Description |
|---|---|---|
| GET | /api/health |
Liveness check, lists exposed roots and protocol version |
| GET | /api/list?root=NAME&path=REL |
List directory entries (capped at 5000, truncated: true when capped) |
| GET | /api/read?root=NAME&path=REL |
Read a file (UTF-8 text, or base64 for binary) |
| POST | /api/write |
JSON {root, path, content, encoding} — writes a file, creating parent dirs |
| POST | /api/mkdir |
JSON {root, path} — creates a directory |
| POST | /api/rotate-token |
Rotates the token — the old one stops working immediately. The new token is written only to the PC's token file and is never returned in the response (so it can't leak through chat) |
Limits: 2 MB per read, 10 MB per write, ~1000 requests/minute shared by all tunnel traffic (the server sees every tunnelled request as 127.0.0.1; 429 when exceeded). In read-only mode (read_only: true in config.json), write/mkdir return 403. There is intentionally no delete endpoint.
Setting up Muse to use this API? Paste CONNECTOR-BRIEF.md into it — it's a ready-made setup brief.
| Symptom | What to do |
|---|---|
| Installer throws ParserErrors / garbled Chinese | The ZIP is outdated. Download the latest release (script encoding issue fixed) |
401 unauthorized |
The client's token doesn't match %USERPROFILE%\.muse-bridge\token on the PC. Copy it again (never paste into chat — use the assistant's secure card flow) |
| Client can't reach the server | First confirm the PC isn't asleep and the user is still signed in (most common cause). Then check Task Scheduler → MuseFileBridge API / MuseFileBridge Tunnel → Last Run Result, and %USERPROFILE%\.muse-bridge\server.log |
| Tunnel address changed | You're on a quick tunnel; its address changes on restart. Send the new address to your assistant. For a stable address, re-run the installer and pick a named tunnel |
| Port already in use | Change port in %USERPROFILE%\.muse-bridge\config.json and restart the MuseFileBridge API task (the tunnel command uses the same port) |
| Rotate the token | python client/pcfile.py rotate-token (needs token/URL set). The old token dies immediately; copy the new one from %USERPROFILE%\.muse-bridge\token — it is never printed or returned over the API |
Writes rejected with 403 |
The server is in read-only mode. Set read_only: false in %USERPROFILE%\.muse-bridge\config.json and restart the MuseFileBridge API task |
| What did the assistant touch? | Check %USERPROFILE%\.muse-bridge\audit.log (one JSON object per line) |
tunnel route dns fails |
The domain's DNS zone must be on the Cloudflare account you logged into |
install.ps1 One-click installer: Python check (auto-install via winget),
cloudflared, token, config, named or trial tunnel,
auto-start tasks (Windows)
uninstall.ps1 Removes the auto-start tasks (Windows)
CONNECTOR-BRIEF.md Paste-ready brief for wiring an AI assistant to this API
server/muse-file-api.py Windows file API server (Python standard library only)
client/pcfile.py Standalone client (Python standard library only)
tests/smoke_test.py End-to-end smoke test, standard library only
CHANGELOG.md Release notes
MIT — see LICENSE.
If this project saved you some time, feel free to buy me a coffee. ☕
| WeChat Reward |
|---|