Live remote desktop · real PTY shell (Claude Code, vim, top — all real) · on-device voice agent · self-hosted · Apple Silicon native · zero cloud · zero API keys
💡 Looking for the iMessage version? See
claude-screen-to-phone— same Mac, async text-driven workflow. FiaOS is the live one — open a web page, you are on the Mac.
Tags:
claude-code·mac-mini·apple-silicon·mlx·local-ai·on-device-ai·self-hosted·homelab·headless-mac·vnc-alternative·ssh-alternative·web-terminal·pty·xterm.js·ai-agent·voice-assistant
A single page that turns your Mac mini into a fully remote-controlled headless dev box — accessible from any device with a browser. Phone. Laptop. Friend's PC. Doesn't matter.
Three things, that's it:
| 🖥️ | Screen | Live screenshot of your Mac, refreshing every second. Click anywhere to drive the mouse. Type to send keys. |
|---|---|---|
| 💻 | Terminal | Real PTY-backed interactive zsh. claude works. vim works. top works. cd actually sticks. Rendered with xterm.js so colors and ANSI escapes are pixel-perfect. |
| 🎙️ | Voice | Push-to-talk to a local on-device voice model (PersonaPlex MLX on Apple Silicon). Loads on demand, idles out to free RAM. |
The Terminal tab is a real PTY. That means anything that needed a TTY —
claude,vim,htop,gh,python -i— just works. No hacks, no faking it.
Open the URL on your phone, log in once, and you've got a real shell on your Mac mini in your pocket.
tailscale + an SSH client + a VNC viewer can each do a piece of this. FiaOS bundles them into one auth-gated web page so you can drive your Mac mini from any device — without installing anything client-side.
The Terminal tab specifically gets you a working Claude Code session on your Mac mini, from your phone. That's the killer feature this whole thing was built around.
If any of these describe you, FiaOS exists for you.
- 🤖 Claude Code on iPhone / iPad — Your Mac mini does the heavy lifting; your phone is just the front-end.
- 🏠 Headless Mac mini homelab — Plug it in, never connect a monitor again. Drive everything from a browser.
- 🛡️ Self-hosted Cursor / GitHub Copilot Workspace alternative — Same kind of agentic coding loop, on hardware you own, with no SaaS in the path.
- 📡 Replace SSH + VNC + RDP — One web page does what used to take three apps and a Tailscale subscription.
- 🎙️ Local voice assistant on Apple Silicon — On-device MLX speech model. No audio leaves your house.
✈️ Travel light — Borrow any laptop, hit your URL, you're back at your dev environment.
Already using
claude-screen-to-phone? That's the async sibling — text a command from anywhere, your Mac executes it, you get screenshots/videos back as iMessages. FiaOS is the live mode — open a web page, you're sitting at the Mac in real time. Different superpowers, same family.
| Tool | Mode | Live screen | Real shell | Voice | Mobile | Self-hosted | Native client? |
|---|---|---|---|---|---|---|---|
| FiaOS | Live | ✅ | ✅ PTY | ✅ on-device | ✅ | ✅ | ❌ none |
claude-screen-to-phone |
Async (iMessage) | ❌ | ❌ | ✅ | ✅ | ✅ Messages | |
| Tailscale + SSH | Live shell | ❌ | ✅ | ❌ | ✅ | ✅ required | |
| VNC / Apple Remote Desktop | Live screen | ✅ | ❌ | ❌ | ✅ | ✅ required | |
| Cursor mobile | Async cloud | ❌ | ❌ | ✅ | ❌ cloud | ✅ required | |
| iSH / Termius | Live shell | ❌ | ✅ | ❌ | ✅ | ✅ required | |
| ChatGPT app | Cloud chat | ❌ | ❌ | ✅ cloud | ✅ | ❌ cloud | ✅ required |
Requires: Apple Silicon Mac · macOS 14+ · Python 3.12+
git clone https://github.com/nicedreamzapp/FiaOS.git
cd FiaOS
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txtpython3 -c 'import secrets; print(secrets.token_urlsafe(24))'FIAOS_PASSWORD='your-strong-password' .venv/bin/python3 server.py
# open http://localhost:9000Copy examples/com.fiaos.server.plist to ~/Library/LaunchAgents/, edit the password and absolute paths, then:
launchctl load ~/Library/LaunchAgents/com.fiaos.server.plistThe bundled watchdog.sh script can be wired up the same way for self-healing.
| File | What it does |
|---|---|
tunnel_to_vps.sh |
Opens an autossh reverse tunnel to a VPS so you can hit it at https://fia.your-domain.com |
nginx-fia.conf |
Matching nginx site config (HTTPS termination + WebSocket upgrade headers) |
Both are templates — replace the hostnames and key paths and you're live.
If you only want to use it on your home network, skip this step entirely.
Voice requires PersonaPlex MLX and Hugging Face access to the model weights. Once it's pip install-ed, FiaOS will spawn it on demand when you hit the Voice tab and shut it back down after 60 s of idle.
| ✅ | Server refuses to start without FIAOS_PASSWORD set — no default fallback in the source |
|---|---|
| ✅ | Signed session cookies, persisted to disk so they survive restarts |
| ✅ | Login endpoint rate-limited (10 attempts / 5 min / IP) |
| Terminal is a real PTY — anyone with the password has the same power as SSH. Treat the password like an SSH key. | |
The _PROTECTED_PATTERNS regex blocks the obvious "kill FiaOS itself" footguns but is not a security boundary. A real shell can run arbitrary scripts. |
|
| 💡 | Want 2FA? Put FiaOS behind a reverse proxy that does it (Cloudflare Access, Authelia, etc.). |
server.py ─ aiohttp server, all routes, PTY terminal handler
executor.py ─ natural-language → shell helper (legacy /api/command)
fia_ptt.py ─ voice push-to-talk WebSocket bridge
fia_talk.py ─ voice TTS layer
sample_voices.py ─ voice sample preview helper
static/
index.html ─ single-page UI (Screen / Terminal / Voice)
login.html ─ password form
*.js *.wasm ─ Opus codec workers for voice streaming
launch_server.sh ─ venv launcher used by the LaunchAgent
start.sh ─ dev helper (starts server + tunnel + caffeinate)
watchdog.sh ─ keep-alive checker
tunnel_to_vps.sh ─ autossh reverse tunnel
nginx-fia.conf ─ nginx HTTPS + WebSocket upgrade template
examples/ ─ LaunchAgent plist template
- Backend: Python 3.12 ·
aiohttp·pty·Quartz(screen capture) ·psutil - Frontend: vanilla JS · xterm.js 5.3 · WebSocket · WebAudio
- Voice: MLX on Apple Silicon (via PersonaPlex)
- Tunnel: OpenSSH reverse forwarding · nginx HTTPS termination
Does this replace SSH?
For interactive use, basically yes — the Terminal tab is a real PTY-backed zsh -l -i, so anything that worked in SSH works here. For automation (scp, rsync, git push over SSH agent forwarding) you still want SSH.
How is this different from VNC or Apple Remote Desktop?
VNC streams the framebuffer continuously; FiaOS just polls a screenshot every 1–5 seconds. That's all you need for "what's happening?" and "click here." It's much lighter on bandwidth, doesn't need a native client, and works perfectly over a phone hotspot.
Does the voice agent send audio to the cloud?
No. Voice runs entirely on-device using MLX on Apple Silicon (via PersonaPlex). Your audio never leaves your Mac mini. There are no API keys to set.
Can I use this without exposing it to the internet?
Yes — skip steps 4 and 5. Run the server, hit http://your-mac-mini.local:9000 from any device on your home network. No tunnel, no nginx, no domain.
Why Apple Silicon only?
The voice model uses MLX, which is Apple-Silicon-only. Screen capture uses Apple's Quartz framework. Everything else (terminal, screen, file browsing) would work on Intel Macs and Linux, but the voice tab specifically would need a different inference backend.
Does it work without Claude Code?
Of course. FiaOS is a remote-Mac-control web UI — Claude Code is just one of many programs you can run in the Terminal tab. vim, nvim, tmux, htop, gh, node, python -i, custom scripts — they all work because the shell is a real PTY.
How is FiaOS different from a Tailscale + SSH setup?
Tailscale + SSH gives you a terminal. FiaOS gives you a terminal plus a live screen viewer plus a voice agent plus a mobile-friendly UI plus zero client-side install — all behind one password on a single web page.
Is this a Cursor mobile alternative?
Sort of. Cursor mobile is a polished AI-coding UI tied to a SaaS. FiaOS is a self-hosted web shell that lets you run whatever AI coding agent you want (Claude Code, Aider, gh-copilot, your own scripts) on hardware you control.
Solo dev. No VC. Built on a Mac in Humboldt County. If FiaOS saves you a Claude bill or just makes you smile, kick a few bucks at github.com/sponsors/nicedreamzapp — every dollar goes back into more local-first tools and keeping this 100% open source.
MIT — see LICENSE.
Built by Matt Macosko · Fia is the assistant who lives on the Mac mini.
⭐ If you find this useful, drop a star — or 💚 sponsor to keep it growing.