Complete guide to remote vibe coding with BeachViber
Install the BeachViber agent, pair your phone, and start controlling Claude Code remotely. Most people are up and running in under a minute.
Requirements
Desktop
Node.js and Claude Code CLI installed. Works on macOS, Linux, and Windows.
Phone
Any modern browser — Chrome, Safari, or Firefox. The app is a PWA — no app store needed.
Network
Internet connection on both devices. No VPN, port forwarding, or firewall changes required. The relay handles NAT traversal.
Quick Start
From zero to remote vibe coding in three commands.
The agent discovers your projects automatically and displays a QR code for pairing. Next step: open the BeachViber app on your phone and scan the code.
Pairing Your Phone
Pair once, then reconnect automatically on future sessions.
Install the BeachViber agent
Run npm install -g @beachviber/agent on your desktop (requires Node.js and Claude Code CLI). Then run beachviber in any project directory. The agent will display a QR code in your terminal.
Open the BeachViber app
Go to app.beachviber.com on your phone. Sign up with your email or GitHub account. On first visit, you'll be prompted to install the PWA for a native app experience.
Scan the QR code
Tap Add Desktop and point your camera at the QR code displayed in your terminal. The QR code contains the pairing code and your desktop's public key — it is short-lived.
Verify the code
Both devices display a matching 8-digit verification code. This confirms the connection hasn't been intercepted. Enter the code shown on your phone into the desktop terminal to complete pairing.
You're connected
End-to-end encryption keys are exchanged automatically. Future connections reconnect instantly — no re-pairing needed unless you explicitly unpair. The BeachViber agent installs a tool permission hook so tool approvals route to your phone.
Managing Sessions
Start a session
From the phone app, browse your projects (with git branch, last commit, and status). Tap a project and type a prompt to start a new Claude Code session. The agent spawns claude in that project directory with all your local tools and environment.
Live streaming
Claude's responses stream to your phone token-by-token over WebSocket. You see the output in real time, just like using Claude Code locally. Markdown rendering, code blocks, and tool use indicators are all supported.
Resume sessions
Sessions persist across connections. If you close the app and come back later, you can resume right where you left off. The full conversation history is available on your phone.
Tool Approval
You control what Claude can do on your machine.
✅ How it works
When Claude wants to run a command, edit a file, or perform any action with side effects, the request is routed to your phone for approval. You see exactly what Claude wants to do and can approve or deny it.
- Auto-approved: Tools already allowed in your Claude Code settings (e.g., Read, Glob, Grep) are approved instantly without bothering you
- Phone approval: Everything else — Bash commands, Edit, Write — shows up on your phone with the full command or file path
- Always denied if unreachable: If your phone is unreachable, all tool requests are denied. Claude never gets silent permission
- Approval timeout: If you don't respond in time, the request is automatically denied
🛠 Customizing permissions
BeachViber reads your existing Claude Code permission settings. Patterns you've already allowed there (like Bash(npm test *)) are auto-approved without going to your phone. You can tune the balance between convenience and control by adjusting your Claude settings.
Multi-Desktop Setup
Control multiple machines from one phone.
💻 Multiple machines
Run beachviber on each machine you want to control. Pair each one by scanning its QR code from the phone app. All paired desktops appear in the Desktops view, where you can switch between them. Each pairing has its own encryption keys.
Profiles
Run multiple agent instances on the same machine.
👤 Named profiles
Use the --profile flag to run separate BeachViber instances with independent config, encryption keys, and pairing state:
Each profile gets its own config file, its own encryption keys, and its own local communication channel. Profile names must be 1–32 alphanumeric characters or hyphens.
Configuration
💻 CLI flags
- beachviber — Start the agent with the default profile
- beachviber --profile <name> — Use a named profile (separate config, keys, and socket)
- beachviber --reset — Delete all config and keys from your local BeachViber config directory, then exit
- beachviber --version — Show version number
- beachviber --help — Show all available options
🔐 Encryption keys
BeachViber uses X25519 key exchange with AES-256-GCM for end-to-end encryption. Private keys are stored securely in your OS keychain — they never leave your machine and are not accessible to JavaScript on the web app side. See the security page for the full cryptographic protocol.
Troubleshooting
"QR code won't scan"
Make sure you're scanning from inside the BeachViber app (not your phone's default camera app). The QR code is short-lived — restart the agent with beachviber to generate a fresh one. Ensure your phone camera has permission to access the camera.
"Phone shows 'Connecting...' but never connects"
Check that both devices have internet access. The relay server requires outbound WebSocket connections on port 443. Some corporate firewalls block WebSocket upgrades — try a different network.
"Tool approvals aren't showing on my phone"
Verify the tool permission hook is installed: check your Claude Code settings for a hook entry referencing BeachViber. The hook is installed automatically when the agent starts. If it's missing, restart the agent. Also ensure the tool isn't already in your Claude Code allow list (auto-approved tools skip the phone).
"Agent crashes on Windows"
Ensure you're running the latest BeachViber agent, which includes Windows compatibility fixes. Earlier versions had issues on Windows. Update with npm install -g @beachviber/agent@latest.
"Verification codes don't match"
This means the connection may have been intercepted. Do not proceed. Close the pairing flow on both devices and try again. If it happens repeatedly, try a different network. The verification code is derived from the shared encryption key — a mismatch means the keys don't agree.
"Session starts but Claude doesn't respond"
Make sure Claude Code CLI is installed and accessible in your PATH. The agent spawns claude as a child process — if it's not found, sessions will fail silently. Run claude --version in your terminal to verify. Also check that your Anthropic API key is configured.
"I got logged out and lost my pairing"
Private/Incognito browsing mode does not persist any website data. When you close a private tab (or the browser closes it in the background), all cookies, saved login state, and encryption keys are deleted. This logs you out and removes your desktop pairing. To avoid this, always use a regular (non-private) browser tab when using BeachViber.
Frequently Asked Questions
Does BeachViber store my code or prompts?
No. The cloud relay is a pass-through — it routes encrypted messages between your phone and desktop but cannot read them and does not store them. Your code, prompts, and responses never leave your devices in plaintext. See the security architecture for details.
Can I use BeachViber without an internet connection?
No. Both your phone and desktop need internet access to communicate through the relay. However, Claude Code itself runs locally on your desktop — if the relay goes down mid-session, Claude continues working and you can check the results when connectivity is restored.
Can I pair multiple desktops to one phone?
Yes. Pair as many machines as you want. Each desktop gets its own encryption keys and appears in the Desktops view on your phone. Switch between them freely.
What happens if I lose connection during a session?
The BeachViber agent automatically reconnects to the relay. Any Claude Code session running locally continues uninterrupted. When you reconnect from your phone, you can resume the session and see what happened while you were away.
Where can I find BeachViber?
The BeachViber agent and web app are available on GitHub. The phone app and relay server are operated by BeachViber LLC.
Does BeachViber use --dangerously-skip-permissions?
Never. BeachViber integrates with Claude Code's built-in permission system via tool permission hooks. It respects your existing permission settings and adds remote approval on top. We never bypass safety checks.
Ready to start?
Install the BeachViber agent and pair your phone in under a minute.