Claude Remote: Run Commands on Your Machine from Claude.ai

I’ve been using Claude Code daily for months now. It’s become central to how I work—writing code, managing files, running builds. But there’s a gap: when I’m away from my desk with just my phone, I lose all that capability.

Claude.ai on mobile is great for conversation, but it can’t touch my machine. Until now.

Introducing Claude Remote

Claude Remote is an open source MCP bridge that connects Claude.ai to your local machine. It lets Claude run shell commands, read and write files, and list directories—all from your phone or any web browser.

The architecture is simple:

+----------------+          +-------------------+          +----------------+
|                |   SSE    |                   |    WS    |                |
|   Claude.ai    |<-------->|  Server (Cloud)   |<-------->|     Agent      |
|   (iOS/Web)    |   MCP    |                   |  Relay   |   (Daemon)     |
+----------------+          +-------------------+          +----------------+

1. You chat with Claude on your phone or browser
2. Claude calls MCP tools (run_shell_command, read_file, etc.)
3. The server relays commands to your connected agent via WebSocket
4. The agent executes commands and returns results
5. Results flow back through SSE to Claude

Why Build This?

The immediate motivation was practical: I wanted to check on long-running processes, read log files, or quickly edit configs without pulling out my laptop.

But there’s a deeper reason. MCP is becoming the standard for how AI interacts with external systems. Claude.ai already supports remote MCP connections—it just needs something to connect to. Claude Remote fills that gap with minimal complexity.

Three Ways to Run It

We’ve made deployment flexible based on your needs:

Local with ngrok (simplest): Run everything on your machine with ngrok providing the HTTPS tunnel. No cloud deployment needed. Great for trying it out.

Docker + reverse proxy (self-hosted): Run the server on your own infrastructure. You control everything.

Fly.io (managed): Deploy to Fly.io for automatic HTTPS and global availability. A few commands and you’re live.

Security Considerations

Running commands remotely requires care. Claude Remote includes several safety measures:

• Token-based authentication between all components
• Path restrictions limiting file access to home directory, /tmp, and /var/tmp
• All traffic encrypted via HTTPS/WSS
• Command logging to SQLite for audit trails

This isn’t a replacement for proper security practices, but it provides a reasonable baseline for personal use.

Getting Started

The quickest path to trying it out:

# Clone the repo
git clone https://github.com/basicmachines-co/claude-remote
cd claude-remote

# Generate auth token and start server
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env
docker-compose up -d

# Start ngrok tunnel (in another terminal)
ngrok http 8080
# Note your https://xxx.ngrok-free.app URL

# Start the agent (in another terminal)
cd agent
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
export AUTH_TOKEN=$(cat ../.env | cut -d= -f2)
export RELAY_URL=ws://localhost:8080/ws/agent
python agent.py

Then add your ngrok URL to Claude.ai under Settings > Connectors > MCP, and you’re connected.

Open Source

Claude Remote is released under AGPL-3.0, the same license we use for Basic Memory. The code is straightforward Python—about 400 lines for the server, 400 for the agent. Fork it, modify it, make it yours.

Check it out: github.com/basicmachines-co/claude-remote

If you build something interesting with it, I’d love to hear about it.

—Drew