MOBaiLE

Run your own computer from iPhone.

Pair MOBaiLE with a Mac or Linux machine you control, send a prompt by text or voice, and follow the run in one live thread.

The phone is the control surface. Your computer keeps the repo, shell, credentials, files, and network access. This repo contains the public backend, runtime, and setup scripts for installing or self-hosting MOBaiLE.

Install Guide · Marketing Plan · Launch Kit · Backend · Architecture · Scripts

Your phone starts and follows the run. Your Mac or Linux machine does the work.

Get a run back in minutes

curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes

If you want the shortest path, do this:

1. Run the installer on the Mac or Linux machine you want MOBaiLE to use.
2. The one-liner uses the recommended defaults: Full Access, Anywhere with Tailscale, and Yes for the background service.
3. When the installer shows the pairing QR, open MOBaiLE on your iPhone and tap Scan Pairing QR.
4. Point the phone at the screen, confirm the pairing, and send a small prompt.
5. Run mobaile first-run to try a safe starter task in ~/MOBaiLE-playground.
6. Run mobaile demo --out mobaile-demo.md if you want a sanitized shareable proof artifact.
7. Run mobaile ready --open-permissions --open-setup on the Mac if browser or desktop control needs final permission approval.
8. Later, run mobaile status any time to check that the computer is ready. If your shell does not find it yet, run ~/.local/bin/mobaile status.

For the most autonomous private-host setup, use the same installer with one extra flag:

curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --high-autonomy

On macOS, you can also open scripts/MOBaiLE Setup.command from a checkout or the MOBaiLE-Setup-macOS.zip release asset. It opens Terminal, runs the same high-autonomy installer, and keeps the window open so human unblock steps remain visible.

That high-autonomy path keeps Full Access explicit, starts the background service, prepares the QR, runs mobaile ready --open-permissions --open-setup, installs the macOS keep-awake helper when available, checks local Codex sign-in when supported, and lands on the computer-local setup page. It still cannot sign in to Codex/Claude, sign in to Tailscale, grant macOS privacy permissions, or solve 2FA/CAPTCHAs for you; it reports those as human unblock steps.

Run mobaile setup on the backend computer to open the computer-local setup page with the pairing QR, backend readiness checks, first-run status, and autonomy readiness. It uses 127.0.0.1, so it is not a phone-openable link; scan the QR with the iPhone instead. If setup feels off, run mobaile ready --open-permissions --open-setup for the guided high-autonomy flow, mobaile check for a quick preflight, or mobaile repair to refresh pairing, restart the service, and run diagnostics. When you want the latest installed CLI/backend later, run mobaile update. To remove MOBaiLE from the host, run mobaile uninstall; add --delete-data --yes when you also want local pairing, run history, logs, and runtime data deleted.

install.sh installs or updates MOBaiLE in ~/MOBaiLE, configures the backend, creates the pairing QR, keeps the service running in the background when supported, and installs the mobaile command for status, pairing, and logs.

What the installer handles: uv, a backend-compatible Python through uv, backend Python dependencies, backend config, service setup, computer-local setup page, QR pairing, and Full Access autonomy provisioning. What you still need: git, curl, and a signed-in agent CLI for agent runs. Codex CLI or Claude CLI works; without one, MOBaiLE can pair and run direct shell commands, but not agent coding runs. Browser/desktop automation in Full Access mode uses npx, so install Node.js/npm if mobaile check reports it missing. The default Anywhere with Tailscale path also needs Tailscale on both the computer and iPhone. You can skip Tailscale only for same-Wi-Fi pairing, local simulator testing, or a public HTTPS URL.

Want to inspect first? Append --dry-run to any one-liner to print the choices and commands without changing your computer.

Need the longer setup and operations path? Start with docs/USAGE.md.

Who it is for

MOBaiLE is for people who already trust a local Mac or Linux environment and want phone-native control over the agents running there. It fits developers, operators, and founders who use Codex or Claude locally, keep credentials on their own machine, and want to start or follow work when opening the laptop is awkward.

The first success should be simple: install the backend, pair the iPhone, run mobaile first-run, then see planning, execution, and the final result come back in one live phone thread.

Why people use it

• Use the environment that already has the work. Run against your actual repo, shell, credentials, files, and network instead of copying context into a hosted IDE.
• Follow the work, not just the final answer. Prompt, live progress, result, artifacts, and follow-up stay in one readable thread.
• Start the next step when the laptop is awkward. Voice mode, silence-based send, widgets, haptics, audio cues, and Shortcuts make quick work practical away from the desk.
• Keep context attached to the workspace. Pair once, stay in the same workspace thread, and make the next run inherit what just happened.

Create proof without exposing your work

Backend activity events are the same progress source the phone UI follows. mobaile demo turns those events into a sanitized Markdown or JSON replay you can share without raw logs, stdout, stderr, prompts, file paths, or tokens.

mobaile first-run
mobaile demo --out mobaile-demo.md
mobaile demo --run-id <run-id> --out mobaile-demo.md

Use the built-in sample for a quick public artifact, or point it at a real run when you want a phone-safe proof of what happened.

For launches, posts, and README updates, use the backend-owned docs/LAUNCH_KIT.md. It keeps the public message centered on the host/runtime truth: your iPhone starts and follows the work, while your own Mac or Linux machine keeps execution, files, credentials, and network access.

Launch from the backend repo

The public backend should be the first conversion path because it proves the claims before anyone installs the private iPhone app:

1. Show the value in one line: run local coding agents from iPhone without moving your repo, shell, files, credentials, or network into a hosted workspace.
2. Give the installer immediately, then define first success as mobaile first-run returning progress and a result to one live phone thread.
3. Attach a sanitized mobaile demo artifact to release notes, founder posts, and community launches.
4. Link the trust model whenever you mention full-access mode, Tailscale, pairing, credentials, or agent providers.

Search-focused public pages live under docs/ for the highest-intent questions:

• docs/codex-from-iphone.html
• docs/claude-code-from-iphone.html
• docs/self-hosted-iphone-agent.html
• docs/tailscale-iphone-agent.html
• docs/safe-vs-full-access.html

Keep trust boundaries explicit

• The phone does not run the code. It sends prompts, audio, attachments, and session metadata to the backend you control.
• Access mode stays visible. Use safe on a cautious host, or full-access on a trusted private machine.
• Pairing is deliberate. MOBaiLE uses a QR and one-time pair_code; the long-lived API token stays on the host.
• The network path is inspectable. Pairing prefers Tailscale or a configured public URL, and the backend remains yours to operate.

For public-facing trust copy, use the GitHub Pages trust page source in docs/trust.html.

Three moments that matter

• Start in the right workspace. See the paired runtime, working directory, and chat switcher before sending the first prompt.
• Follow the run live. Progress, result, summary, artifacts, and next recommended action stay together in the same thread.
• Keep talking without losing context. Voice mode reopens the mic after each reply while attachments and typed follow-ups stay in the same conversation.

Good First Prompts

• create a hello python script and run it
• inspect this repo and tell me where onboarding feels rough
• run the backend smoke test and summarize what passed
• fix the failing test and explain the patch

Other setup paths

Use these only if the main install command is not what you want.

• Already in a checkout and want to run the installer there: bash ./scripts/install.sh --checkout "$PWD"
• macOS clickable high-autonomy setup: open scripts/MOBaiLE Setup.command
• Same recommended setup with explicit flags: curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --mode full-access --phone-access tailscale --background-service yes
• Guided high-autonomy setup: curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --high-autonomy
• Same Wi-Fi only: curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --phone-access wifi
• Local simulator/dev only: curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --mode safe --phone-access local --background-service no
• Preview before changing anything: curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes --dry-run
• Backend-only/manual path from a checkout: bash ./scripts/install_backend.sh --mode full-access --phone-access tailscale
• Local simulator-only testing: bash ./scripts/install_backend.sh --mode safe --phone-access local

If you skip QR pairing, the app can also be connected manually with a reachable server address and API token.

Full setup details

Install the essentials

On your computer:

• git and curl
• uv and Python 3.11+ only if you are not letting the installer add them for you
• Codex CLI or Claude CLI, installed and signed in, for real agent runs
• Node.js/npm only if you want npx-based browser/desktop automation in Full Access mode
• Tailscale for the default Anywhere with Tailscale path

On your iPhone:

• Tailscale, unless you are pairing only on the same Wi-Fi or through a public HTTPS URL
• MOBaiLE, from TestFlight or the App Store, or built locally from ios/

MOBaiLE never runs code on the phone. It only sends prompts, audio, attachments, and session metadata to the backend you pair with.

Sign in to Tailscale on both devices

Use the same tailnet on both devices. On the computer:

tailscale status
tailscale ip -4

Install on the computer

Recommended path:

curl -fsSL https://raw.githubusercontent.com/vemundss/mobaile/main/scripts/install.sh | bash -s -- --yes

If you are already in a checkout:

bash ./scripts/install.sh --checkout "$PWD"

The pasted one-liner uses recommended defaults because piped shell scripts cannot reliably prompt. If you run the installer from a checkout without --yes, it asks three questions:

1. How much access should MOBaiLE have on this computer? Keep Full Access unless you specifically want the safer mode.
2. Where should your phone work? Keep Anywhere with Tailscale for the normal remote setup.
3. Should MOBaiLE stay running in the background? Keep Yes if this computer should stay ready for the phone.

Manual host-only path from a checkout:

bash ./scripts/install_backend.sh --mode full-access --phone-access tailscale
bash ./scripts/service_macos.sh install   # macOS
# or on Linux:
bash ./scripts/service_linux.sh install
bash ./scripts/pairing_qr.sh

What the installer does:

• installs backend dependencies and creates backend/.env
• creates backend/pairing.json using a Tailscale URL when available
• installs and starts a background service on macOS or Linux when supported
• generates a pairing QR; run mobaile pair later to refresh it

If you want a stable hostname for the iPhone, set VOICE_AGENT_PUBLIC_SERVER_URL before pairing. Otherwise MOBaiLE uses the URLs for the selected phone access mode: Tailscale mode advertises Tailscale/public URLs only, while Wi-Fi mode advertises the LAN URL.

Check that the computer is ready

curl http://127.0.0.1:8000/health

Expected result: JSON with status ok.

Pair the phone

On the computer:

1. Run mobaile pair. If your shell does not find it yet, run ~/.local/bin/mobaile pair.
2. Open the Pairing QR path it prints.

The path may be under the checkout or under the installed service runtime, depending on how the backend is running.

On the iPhone:

1. Tap Scan Pairing QR inside MOBaiLE.
2. Point the phone at the QR on your computer.
3. Confirm pairing inside MOBaiLE.

Manual fallback in app settings:

• Server URL: preferred URL from the active pairing file
• API Token: VOICE_AGENT_API_TOKEN from the active backend .env
• Session ID: keep iphone-app unless you want a custom one

If the app works on Wi-Fi but not on cellular, verify the chosen Tailscale or public URL is reachable from the phone.

Validate remote use

1. Turn off Wi-Fi on the iPhone.
2. Keep Tailscale connected.
3. Send a small prompt such as create and run a hello script.
4. Confirm live events and the final result both come back in the thread.

Designed For On-The-Go Use

• Widget: add Start Voice Task to jump straight into recording from the Home Screen.
• Haptic and audio cues: useful when you do not want to stare at the screen for confirmation.
• Live voice drafts: speech appears in the composer while recording, so you can stop, edit, continue dictating, and send when it is right.
• Voice mode: keeps the mic reopening after each reply so the conversation can continue hands-free.
• Auto-send after silence: ideal for shorter one-shot voice captures.
• Siri and Shortcuts: available intents include Start Voice Mode and Send Last Prompt.

Developer Commands

Common maintenance commands:

bash ./scripts/doctor.sh
bash ./scripts/pairing_qr.sh
cd backend && bash ./run_backend.sh
cd backend && uv run pytest -q
cd backend && uv run python ../scripts/sync_contracts.py --check

Shell linting is developer-only tooling. Install shellcheck and shfmt if you want to run bash ./scripts/shell_checks.sh lint; they are not required for a normal MOBaiLE host install.

Service control:

# macOS
bash ./scripts/service_macos.sh status
bash ./scripts/service_macos.sh restart
bash ./scripts/service_macos.sh logs

# Linux
bash ./scripts/service_linux.sh status
bash ./scripts/service_linux.sh restart
bash ./scripts/service_linux.sh logs

Optional npm wrappers:

npm run setup:server
npm run backend:start
npm run doctor
npm run pair:qr
npm run ios:open

Optional commit-time secret scanning:

uv tool install pre-commit
pre-commit install
pre-commit run --all-files

Troubleshooting

Common fixes

• Pairing QR contains 127.0.0.1 instead of a Tailscale or LAN URL:

bash ./scripts/install_backend.sh --mode full-access --phone-access tailscale
bash ./scripts/pairing_qr.sh

• iPhone can pair on Wi-Fi but not on cellular:

  • run mobaile doctor and fix any reported pairing or advertised-URL issues first
  • run mobaile pair and scan the fresh QR; pair codes expire
  • confirm the pairing URL prefers a *.ts.net Tailscale MagicDNS host; raw 100.x Tailscale IPs are fallback-only and can be blocked by iOS transport policy in release builds
  • confirm Tailscale is connected on both devices
  • in iOS Settings, confirm Cellular Data is enabled for Tailscale and MOBaiLE
  • confirm the backend is still running with mobaile status

• Voice works for text but not the mic:

  • enable Speech Recognition for MOBaiLE in iOS Settings
  • on a real iPhone, MOBaiLE transcribes locally first, and OPENAI_API_KEY is only needed for backend audio-upload fallback

• Backend audio uploads fail:

  • set OPENAI_API_KEY in backend/.env
  • text prompts still work without it, but /v1/audio depends on backend transcription

More Docs

• Usage guide: docs/USAGE.md
• Backend details and endpoints: backend/README.md
• Scripts reference: scripts/README.md
• Architecture: ARCHITECTURE.md
• Marketing plan: docs/MARKETING.md
• Documentation policy: docs/POLICY.md
• Public pages and App Store URLs: docs/PUBLIC_PAGES.md
• Contributing: CONTRIBUTING.md
• Security policy: SECURITY.md
• Code of conduct: CODE_OF_CONDUCT.md

License

This project is source-available under the Functional Source License, Version 1.1, ALv2 Future License (FSL-1.1-ALv2). You may use, modify, and redistribute MOBaiLE for permitted purposes, but you may not make it available to others as a competing commercial product or service. Each released version becomes available under the Apache License, Version 2.0 on the second anniversary of the date that version was made available.

See LICENSE for the full text. The MOBaiLE name, logo, app icon, and brand assets are reserved separately under TRADEMARKS.md.