mact-cli 1.1.0

Mirrored Active Collaborative Tunnel — CLI to share live localhost previews with your team

MACT

Mirrored Active Collaborative Tunnel — route a stable public URL to the localhost of the developer who last committed, with automatic fallback and an offline page when nobody is connected.

Progress and planning live in project-tracking/ (PROGRESS.md, ROADMAP.md).

Install

pip install mact-cli      # from PyPI (once published) — CLI only (requests + frpc download on first tunnel use)
# Self-host the control-plane API from the same repo / sdist:
pip install "mact-cli[server]"
# Editable for development (CLI + server deps + tests):
pip install -e ".[dev]"

If frpc is not on your PATH, the first mact up with a tunnel downloads a matching frp release into ~/.cache/mact/frp/<version>/ (override the tag with MACT_FRP_VERSION, e.g. v0.61.0).

Quick start (developer)

# 1. Set your identity
mact init --developer alice

# 2. (Optional) Configure tunnel — needed to expose your local port publicly
mact configure-frp --server-addr mact.live --server-port 7000 \
  --auth-token YOUR_FRP_TOKEN --vhost-domain tunnel.mact.live

# 3. Create a room
mact create --room demo --port 3000
#   → prints join_secret, admin_token, member_token

# 4. Share the join secret with collaborators — they run:
mact join --room demo --port 3001 --secret <join_secret>

# 5. Start the tunnel + heartbeat (keep this running while developing)
mact up --room demo --port 3000

# 6. Install the git post-commit hook (reports commits automatically)
mact hook install --room demo

# 7. Check room status anytime
mact status --room demo

Quick start (server)

Operators run the FastAPI app with uvicorn (not published as a separate console script on PyPI):

pip install "mact-cli[server]"
uvicorn mact.server.main:app --host 0.0.0.0 --port 8000

Default data store is SQLite at ./mact.db. For production, use PostgreSQL and run migrations (see Database migrations).

CLI commands

Command	Description
mact init --developer <id>	Set developer identity
mact configure-frp ...	Configure FRP tunnel settings
mact create --room <id> --port <port>	Create room, get tokens
mact join --room <id> --port <port> --secret <s>	Join with secret
mact up --room <id> [--port <p>] [--no-tunnel]	Start tunnel + heartbeat
mact status --room <id>	Fetch room status
mact rooms	List locally saved rooms
mact hook install --room <id>	Install git post-commit hook
mact commit-report --room <id>	Report HEAD commit (used by hook)

Environment (server)

Variable	Default	Meaning
DATABASE_URL	sqlite:///./mact.db	SQLAlchemy URL (postgresql+psycopg://... for Postgres)
MACT_AUTO_CREATE_TABLES	true	Create tables on startup (dev only)
MACT_PRESENCE_TTL_SECONDS	60	Member liveness TTL
MACT_PUBLIC_BASE_DOMAIN	mact.live	Wildcard subdomain routing ({room}.mact.live). Empty disables.
MACT_DEV_DASHBOARD	unset/false	Enable dev-only path dashboard routes (/rooms/{id}/dashboard)

Environment (CLI)

Variable	Default	Meaning
MACT_BACKEND_URL	http://127.0.0.1:8000	Control-plane API base URL used by CLI commands
MACT_FRP_VERSION	v0.61.0	FRP release tag auto-downloaded when frpc is missing

API endpoints

Method	Path	Auth	Description
GET	/health	—	Liveness check
GET	/ready	—	Readiness (DB reachable)
POST	/rooms	—	Create room → tokens
POST	/rooms/{id}/join	join_secret in body	Join room → member_token
POST	/rooms/{id}/commits	Bearer member_token	Report commit
PATCH	/rooms/{id}/commits/{hash}/comment	Bearer admin_token	Set/clear admin comment
GET	/rooms/{id}/status	—	Room status JSON
POST	/rooms/{id}/presence/heartbeat	Bearer member_token	Heartbeat (+ optional upstream update)
POST	/rooms/{id}/presence/disconnect	Bearer member_token	Disconnect
GET	/r/{id}[/path]	—	Mirror HTTP proxy to active upstream
WS	/r/{id}[/path]	—	Mirror WebSocket to active upstream (same path/query as HTTP)
GET	/dashboard	—	Room dashboard (subdomain only)

Public URLs (production)

With MACT_PUBLIC_BASE_DOMAIN=mact.live and DNS *.mact.live → server:

• Mirror: https://{room}.mact.live/
• Dashboard: https://{room}.mact.live/dashboard
• Tunnel vhosts: http://{dev}-{room}.tunnel.mact.live (via frps)

Path-based routing (/r/{room}) remains for local dev or when subdomain routing is disabled.

Expose the API only behind trusted network controls (private network, VPN, or auth gateway). By design, room creation/status endpoints are open unless you add an external access-control layer.

Database migrations

cd "/path/to/M ACT"
alembic upgrade head

Set MACT_AUTO_CREATE_TABLES=false when using Alembic in production.

Tests

pip install -e ".[dev]"
pytest -v

Architecture

See ARCHITECTURE.md for the full design, phased delivery plan, security notes, and distributed systems considerations.