Remote phone access in BrokenCode

Run curl -fsSL https://brokengpt.com/install-vps | sudo bash in your server’s SSH terminal. BrokenCode 1.18.57 or later installs under a dedicated brokencode user, starts at boot with systemd, and prints a phone pairing QR. The server keeps working after SSH disconnects.

Supported servers use x86_64 or ARM64 Linux with systemd. Hetzner, Hostinger VPS, and other Linux VPS providers work with this setup. Vercel serverless functions do not provide the persistent process and listening port required here. Start with 2 GB of RAM for hosted-model coding. For heavier builds or local inference, increase the service’s MemoryMax and CPUQuota with sudo systemctl edit brokencode and choose suitable hardware.

Allow TCP 43821 in the provider firewall for direct access. The installer adds that port when UFW is active and detects the public IPv4 address. For a different address or port, append -- --port 43821 --address https://your-host:43821 to bash -s. A private network address also works. Use --no-tunnel to require direct connections only.

Run the installer again to update. It verifies the downloaded release checksum and preserves projects, saved authorization, identity, port settings, and paired phones. Stop the service with sudo systemctl stop brokencode. For logs, use sudo journalctl -u brokencode -f.

1. Install the current phone app and choose Connect computer. Scan the terminal QR or paste its full code. The one-use code expires after ten minutes.
2. Run sudo brokencode-server pair whenever you want to add a phone. Existing phones remain paired through server restarts and updates.
3. Use sudo brokencode-server devices to list paired devices; revoke one with sudo brokencode-server revoke --device ID.
4. Open your paired server on the phone. Add a model provider from the model picker, open a project under /srv/brokencode, and start a task. Use Apps & MCP to connect apps on that server.

With BrokenCode 1.18.61 or later, ask the agent to start a frontend or backend, or add its foreground start command in Settings → Agent & extensions → Project servers. BrokenCode remembers the command and gives you Start, Stop and Restart controls on desktop and phone.

Managed servers sleep after 15 minutes without agent activity in that project. Active tasks, questions and approval waits keep them awake. Adjust the interval or choose Keep running for previews and background services that need to stay available. Website traffic does not reset this timer.

Ask the agent to start a saved server by name to wake it, or tap Start. Only processes started by this manager are stopped. Your paired remote connection stays available. After the host restarts, saved servers remain stopped until you start them. Sleeping releases CPU and memory; it does not turn off or change the billing of the VPS itself.

Questions and approvals stay pending until you answer or cancel the task. The agent tool connection sends progress while waiting, and the phone repairs an idle connection before submitting your decision.

If a prompt acknowledgement is lost, updated phone and host versions use the same message ID to avoid creating another turn. Commands and approval decisions are not automatically repeated. Keep the host online; iOS or Android may suspend the phone’s connection while the app is closed, and the phone reconnects when you return.

Open Apps & MCP inside the connected workspace on iPhone or Android. Add Gmail, GitHub, or a compatible HTTPS MCP server, then choose Authorize. Consent opens in the phone’s system browser. GitHub may show a short device code to enter.

For loopback OAuth connections, the phone receives the browser callback and forwards its one-use code and state over the paired connection. The workspace verifies the originating session and exchanges the code on the host. Provider credentials and PKCE verifiers remain on that host. Keep the authorization screen open until Connected appears.

Authorization applies to the selected server. It does not copy your laptop’s accounts to a VPS. Provider consent, app registration requirements, and supported OAuth methods still apply. Servers that require custom HTTPS callbacks need their registered callback configuration.

BrokenCode Desktop hosts your phone connection. Tasks run on your computer using its local projects, models, credentials, MCP servers, and permissions. The phone prefers direct access and uses an authenticated outbound tunnel when the network blocks it. No BrokenGPT or Cloudflare account is needed for QR pairing.

1. Install BrokenCode 1.18.45 or later on your computer and update your phone app.
2. Open Settings → Remote access in the desktop app and choose Enable remote access. Keep the computer running and awake.
3. Choose Connect computer in the phone app. Scan the QR code or paste the full pairing code. Codes expire after ten minutes and work once.
4. Open the paired computer. The phone saves its credentials securely and reconnects without scanning again.

BrokenCode opens an encrypted listening port and tries automatic router mapping through UPnP and NAT-PMP. Local Wi-Fi, public addresses, and existing private networks can carry a direct connection. Active router mappings renew in place.

For a forwarded port or a private-network hostname, open Connect from another network in Remote access and save the encrypted computer address before pairing. Leave it blank to use automatic discovery. A stable hostname can keep the same pairing usable when the computer’s IP address changes.

When a router or mobile carrier blocks incoming traffic, the laptop opens an outbound tunnel automatically. The phone tries direct addresses together and gives them a short head start, then uses the tunnel if needed. Users do not need to log in to Cloudflare or configure their router.

The tunnel address stays stable when the laptop's local address changes. Paired phones reconnect with their saved credentials and learn refreshed direct addresses. Keep both devices online and the laptop awake; the workspace continues to run on the laptop.

With desktop and phone version 1.18.45 or later, requests, live task updates, and terminal traffic share one persistent, authenticated connection. A healthy connection reuses the verified computer address. Discovery and connection checks run again when the connection breaks or the phone returns from the background.

The phone prefers a reachable direct address and keeps the outbound tunnel as a fallback. Requests still travel to the computer and responses travel back, so mobile coverage, distance, and the selected route affect latency. Keeping the connection open removes repeated setup, while your work continues to run on the laptop.

The QR code pins the computer’s exact certificate. Direct connections verify that certificate; tunnel connections verify a fresh challenge signed by the same computer before sending pairing credentials. Pairing credentials live in the phone’s secure storage; the computer saves token hashes and protects its host identity with the operating system’s credential store. A VPS stores its identity and device records in private files readable only by the dedicated server user.

Cloudflare carries live tunnel traffic over TLS on both legs and terminates that TLS. The tunnel service retains the computer's public identity fingerprint and does not save workspace contents, pairing tokens, or terminal traffic. Your projects, task history, provider credentials, and paired-device authorization stay on the computer.

Choose Remove device on the desktop to revoke a phone and close its active requests and terminal connections. Turn off remote access to close the listening port and outbound tunnel. Pairing another phone keeps your existing pairs. Work and tool approvals remain on the host; pairing does not bypass them.

• Continue a task, send a follow-up, select models and reasoning, or interrupt work from either device.
• Browse local folders on the computer. Native file saves detect conflicting edits.
• Use the live terminal on the host. The phone never executes the host’s shell commands locally.
• Unsent drafts and attachments stay with their task. Closing the phone leaves the computer’s work running.
• Desktop access requires BrokenCode Desktop to remain running. VPS access uses the persistent brokencode service instead. Keep the chosen host online.

The phone reads available models and connected tools from its host. Model and reasoning selections use the same task settings. Attach photos to prompts when the selected model supports images. The microphone inserts locally transcribed text into your draft for review before sending.

• Android prefers advanced on-device speech on supported phones and checks for an available local English service on other Android 12 or later devices. Missing supported language packs download automatically, with progress when the service provides it.
• Supported iPhones on iOS 26 use the newer local speech transcriber and download English assets when needed. Earlier supported phones use the installed on-device English dictation language.
• Website chatbot connections run on the desktop and retain their own compatibility and text-input limits.

Download the signed APK from the download page. Android 8 or later supports remote workspace access. Choose Connect computer to pair directly. Install updates over the existing app to keep your pairs and drafts.

The app has native screens for tasks, messages, models, folders, file edits, and a live terminal. An existing account connection remains available from Use an existing account connection.

The native iPhone source includes direct pairing and on-device dictation. It can be built and installed with Xcode using your Apple signing team. An App Store or TestFlight download is not currently available. Source builds must be rebuilt and reinstalled to update.

Existing hosted account connections remain available for compatibility. Their browser access and terminal bridge use the account relay. The brokencode remote terminal command continues to manage that connection. Choose desktop QR pairing for phone access without account sign-in.

Server-delivered task notifications use the existing account infrastructure. A direct connection does not provide background server push notifications while the phone app is closed.