Macha docs

Macha exposes a port on your local machine to the public internet. No account, no signup, one command.

Installation

Pick the method that suits your platform. All paths end up with a single macha binary.

Mac

curl -fsSL https://macha.live/install.sh | bash

Downloads the correct pre-built binary for Apple Silicon (aarch64) or Intel (x86_64) and installs it to /usr/local/bin.

Linux

curl -fsSL https://macha.live/install.sh | bash

Statically linked with musl — works on any Linux distribution with no libc dependency. Supports x86_64 and aarch64.

Windows

irm https://macha.live/install.ps1 | iex

Installs to %LOCALAPPDATA%\macha\bin and adds it to your user PATH. Restart your terminal after install.

From source (Cargo)

cargo install macha

Requires the Rust toolchain. Compiles from crates.io — takes about a minute on first run.

Verify

macha --version

Your first tunnel

Two things are needed: a local server running, and the subdomain you want.

• 1
  Start your app

  Macha works with any server. The only thing it needs is a port number.

  examples

  # Node / Express on :3000
  node server.js
  
  # Python / FastAPI on :8000
  uvicorn main:app --port 8000
  
  # Anything — just know the port

• 2
  Run Macha

  copy

  macha --port 3000 --subdomain myapp

  Replace 3000 with your app's port and myapp with any subdomain you want (letters, digits, hyphens — max 63 characters).

• 3
  Get your URL

    Dashboard → http://127.0.0.1:4040
  ✓  Tunnel: https://myapp.macha.live

  Share https://myapp.macha.live with anyone. Open http://127.0.0.1:4040 to see requests in real time.

Local dashboard

Every time you run macha, a dashboard starts automatically at http://127.0.0.1:4040. Open it in your browser.

The dashboard shows:

• Connection status and tunnel URL
• Stats — total requests, bytes in/out, average response time, uptime
• Live request log — method, path, size, duration — updates in real time

It uses Server-Sent Events so the log updates live without polling.

Change the dashboard port

macha --port 3000 --subdomain myapp --dashboard-port 5050

Set --dashboard-port 0 to disable the dashboard entirely.

CLI flags & environment variables

Every flag has a corresponding environment variable. Flags take precedence.

Examples

# Basic
macha --port 3000 --subdomain myapp

# Using env vars (good for .env files)
PORT=3000 SUBDOMAIN=myapp macha

# Self-hosted server with auth token
macha --port 3000 --subdomain myapp \
      --server tunnel.yourcompany.com \
      --token my-secret-token \
      --tls

# Run once (no reconnect), custom dashboard port
macha --port 8080 --subdomain staging \
      --no-reconnect \
      --dashboard-port 5050

Rust library — quick start

Embed tunneling directly in your Rust app with no external process.

[dependencies]
macha = "0.2"
tokio = { version = "1", features = ["full"] }

use macha;

#[tokio::main]
async fn main() -> macha::Result<()> {
    // blocks until disconnected; auto-reconnects by default
    macha::start("myapp", 3000).await
}

Run in the background alongside your server

use macha::Tunnel;

#[tokio::main]
async fn main() -> macha::Result<()> {
    let tunnel = Tunnel::builder("myapp", 3000)
        .build()?;

    tokio::spawn(async move {
        let _ = tunnel.run().await;
    });

    // start your own server here…
    std::future::pending::<()>().await;
    Ok(())
}

Builder API

All options are chainable on Tunnel::builder(subdomain, port).

use macha::Tunnel;

let tunnel = Tunnel::builder("myapp", 3000)
    .server("tunnel.yourcompany.com")
    .token("my-secret-token")
    .tls()
    .reconnect(true)
    .build()?;

tunnel.run().await?;

Log channel

Wire a tokio::sync::broadcast channel into the tunnel to receive a RequestLog after every completed request.

use macha::{Tunnel, RequestLog};
use tokio::sync::broadcast;

let (tx, mut rx) = broadcast::channel::<RequestLog>(256);

// spawn log consumer
tokio::spawn(async move {
    while let Ok(log) = rx.recv().await {
        println!("{} {} — {}ms", log.method, log.path, log.duration_ms);
    }
});

Tunnel::builder("myapp", 3000)
    .log_channel(tx)
    .build()?
    .run().await?;

RequestLog fields

Self-hosting — Docker

Run your own tunnel server on any VPS. Your users connect to it instead of macha.live — traffic never leaves your infrastructure.

services:
  macha:
    image: ghcr.io/dhineshk/macha-server:latest
    restart: unless-stopped
    ports:
      - "80:8080"     # public HTTP (put Caddy in front for HTTPS)
      - "9000:9000"   # agent control plane
      - "9001:9001"   # agent data plane
    environment:
      DOMAIN: tunnel.yourcompany.com
      AUTH_TOKEN: change-me-to-a-random-secret

docker compose up -d

That's it — the server is running. Now point agents at it:

macha --port 3000 --subdomain myapp \
      --server tunnel.yourcompany.com \
      --token your-secret

Tunnel URLs will read https://myapp.tunnel.yourcompany.com.

Server environment variables

HTTPS with Caddy

Caddy handles wildcard TLS certificates automatically using Let's Encrypt. Add this alongside your docker-compose.yml:

*.tunnel.yourcompany.com {
    tls {
        dns <your-dns-provider>
    }
    reverse_proxy macha:8080
}

services:
  caddy:
    image: caddy:latest
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    environment:
      <DNS_PROVIDER_API_TOKEN_VAR>: <your-token>

  macha:
    image: ghcr.io/dhineshk/macha-server:latest
    restart: unless-stopped
    expose: ["8080"]
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      DOMAIN: tunnel.yourcompany.com
      AUTH_TOKEN: change-me

volumes:
  caddy_data:

TLS for agent connections

By default ports 9000 and 9001 are plain TCP. If you want the agent-to-server connection encrypted (important if AUTH_TOKEN is set), add TLS:

environment:
  TLS_CERT: /certs/fullchain.pem
  TLS_KEY:  /certs/privkey.pem
volumes:
  - /etc/letsencrypt/live/tunnel.yourcompany.com:/certs:ro

Then agents must connect with --tls:

macha --port 3000 --subdomain myapp \
      --server tunnel.yourcompany.com \
      --token my-secret \
      --tls

For self-signed certificates, use --tls-ca /path/to/ca.pem instead of --tls.

Auth tokens

Set AUTH_TOKEN on the server to require all agents to authenticate. Without a valid token, agents get ERR invalid or missing token and are disconnected.

AUTH_TOKEN=a-long-random-string-here

# flag
macha --port 3000 --subdomain myapp --token a-long-random-string-here

# env var
MACHA_TOKEN=a-long-random-string-here macha --port 3000 --subdomain myapp

Rate limiting

The server applies two independent rate limits automatically — no configuration needed.

Per-subdomain request limit

Each subdomain has a token bucket: capacity 200, refill rate 100/second. Requests that exceed this are rejected with HTTP 429 Too Many Requests without hitting the agent pool. This protects against a single tunnel overwhelming the server.

Per-IP registration limit

Each unique IP address can register at most 5 subdomains per minute. Attempts beyond this are rejected with ERR too many registration attempts. This prevents automated subdomain squatting.

Reserved subdomains

The following subdomains cannot be registered — they are permanently blocked:

api, www, admin, root, mail, server, dashboard, status, health,
macha, app, staging, prod, beta, static, assets, cdn, auth,
login, signup, register, support, help, docs, blog, dev, test

Any attempt to register one of these returns ERR reserved subdomain.