Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.murmur.dev/llms.txt

Use this file to discover all available pages before exploring further.

Murmur provides secure access to agent VMs through IAP-tunneled SSH and port forwarding through the port-proxy service. No public IPs are exposed — all connectivity is authenticated and tunneled.

​
murmur ssh

SSH into an agent’s VM through an IAP (Identity-Aware Proxy) tunnel. 
murmur ssh <slug> [flags] [-- command]

​
Flags

FlagTypeDescription
--attachboolAttach to the agent’s tmux session (where Claude Code runs)
-vboolVerbose mode — show SSH connection details and diagnostics
--Separator for non-interactive commands (everything after -- is run on the VM)

​
Interactive login

Open a shell on the agent’s VM: 
murmur ssh fix-auth-bug
This drops you into a bash shell on the VM. You can explore the filesystem, check logs, run tests manually, or debug issues.

​
Attach to Claude’s tmux session

Attach directly to the tmux session where Claude Code is running. This lets you see Claude’s output in real time and interact with the terminal: 
murmur ssh --attach fix-auth-bug
Attaching to the tmux session is only available for agents spawned in interactive mode (-i). Autonomous agents run headlessly without a tmux session.
To detach from the tmux session without killing it, press Ctrl+B then D.

​
Non-interactive commands

Run a command on the VM without opening an interactive session. Everything after -- is executed remotely: 
# Check disk space
murmur ssh fix-auth-bug -- df -h

# Run tests
murmur ssh fix-auth-bug -- cd /home/user/repo && go test ./...

# View a log file
murmur ssh fix-auth-bug -- tail -100 /tmp/claude.log

# Check running processes
murmur ssh fix-auth-bug -- ps aux

​
Verbose mode

Use -v for SSH diagnostics when troubleshooting connection issues: 
murmur ssh -v fix-auth-bug
This prints the IAP tunnel details, SSH handshake progress, and any errors.

​
murmur port-forward

Tunnel local ports to the agent’s VM through the port-proxy service. This lets you access services running on the VM (web servers, databases, debug ports) from your local machine. 
murmur port-forward <slug> <port...> [flags]

​
Flags

FlagTypeDescription
--insecureboolSkip TLS verification for the tunnel (use for development only)

​
Single port

# Forward local port 3000 to VM port 3000
murmur port-forward fix-auth-bug 3000
Then open http://localhost:3000 in your browser to access the service.

​
Multiple ports

Forward several ports at once: 
# Forward web server and debug port
murmur port-forward fix-auth-bug 3000 8080 5432

​
How port forwarding works

Browser/Client         CLI                Port Proxy           VM
┌──────────┐      ┌──────────┐       ┌──────────────┐    ┌──────────┐
│ localhost │─────▶│ murmur   │──────▶│ murmur-port- │───▶│ Service  │
│ :3000    │      │ port-fwd │ JWT   │ proxy        │    │ :3000    │
└──────────┘      └──────────┘       └──────────────┘    └──────────┘
  1. The CLI opens a local listener on the specified port
  2. Connections are authenticated with a JWT and forwarded to the port-proxy service
  3. The port-proxy routes traffic to the correct VM via a bidirectional PortTunnel gRPC stream
  4. The VM’s agent process registers its tunneled ports at startup

​
murmur url

Get public URLs for accessing ports or agent dashboards.

​
murmur url port

Get a public URL that tunnels to a port on the current VM. This command is only available from within a VM (agent context). 
murmur url port <port>

# Get a public URL for a web server running on port 3000
murmur url port 3000
# Output: https://abc123.port.murmur.ai
The returned URL is a short, deterministic subdomain on the port-proxy service. It is publicly accessible and authenticated via the URL token. Use cases from within an agent:
  • Share a preview URL in a PR description
  • Expose a test server for integration testing
  • Provide a link to a documentation preview

​
murmur url agent

Get the murmur-ui dashboard URL for an agent. 
murmur url agent [slug]

# Get dashboard URL for a specific agent
murmur url agent fix-auth-bug
# Output: https://app.murmur.ai/w/my-workspace/u/alice/fix-auth-bug

# Get dashboard URL for the current agent (from within a VM)
murmur url agent

​
Web terminal access

Agents spawned in interactive mode (-i) automatically start a ttyd web terminal. You can access it through:
  1. Dashboard: Click the terminal icon on the agent’s detail page
  2. Direct URL: Available in the murmur status output
  3. SSH attach: murmur ssh --attach <slug> (connects via IAP tunnel)
The web terminal provides a browser-based terminal experience with the same access as SSH.

​
IAP tunneling

All SSH and port-forward connections use Google Cloud IAP (Identity-Aware Proxy) tunnels. This means:
  • No public IPs: VMs have no public IP addresses. All access is through IAP.
  • Identity-based access: Connections are authenticated against your Google/GitHub identity.
  • Audit logging: All tunnel connections are logged for security auditing.
  • Encryption: Traffic is encrypted end-to-end through the IAP tunnel.

​
Troubleshooting

If SSH connections fail:
SymptomLikely causeFix
Connection refusedAgent is sleeping or terminatedmurmur wake <slug> or check murmur status
Permission deniedIAP access not configuredRe-run murmur setup or check IAP permissions
TimeoutVM is booting or network issueWait and retry, or use -v for diagnostics
Host key changedNew VM after sleep/wake cycleExpected — the host key changes with each VM

​
Port-proxy architecture

The port-proxy service (murmur-port-proxy) enables secure access to VM ports without exposing public IPs:
  1. When an agent VM starts, it opens a persistent bidirectional gRPC stream (PortTunnel) to the port-proxy service
  2. The port-proxy assigns a deterministic subdomain label based on the agent slug and port
  3. Incoming HTTP(S) requests to {label}.port.murmur.ai are routed through the tunnel to the correct VM and port
  4. The tunnel is authenticated with JWTs and encrypted with TLS
This architecture means:
  • VMs never need public IPs or firewall rules
  • Port access is revoked instantly when the agent terminates
  • Multiple ports per VM are supported (each gets a unique subdomain)
  • WebSocket connections are supported through the tunnel