mact-cli 1.2.1

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 create or mact join that starts 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)

Run all CLI commands from a git checkout of your project (git init if needed).

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

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

# 3. Create a room — from the project repo: registers with the API, ensures frpc
#    (download if missing), installs the git post-commit hook, then starts tunnel + heartbeat
mact create --room demo --port 3000
#   → prints join_secret, admin_token, member_token
#   Use --no-live to skip tunnel/heartbeat; --no-hook to skip the hook; --no-tunnel for heartbeat-only.

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

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

# Optional: re-install only the post-commit hook (already done by create/join)
mact hook install --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).

The marketing homepage at / (full product name, PyPI, and GitHub: int33k/M-ACT) is served by this FastAPI app. If https://m-act.live/ still looks old, the droplet is running an older build: deploy the latest code and restart the API (Nginx already proxies / to uvicorn; there is no separate static index.html in the repo).

# On the server (adjust paths / venv / service name to match your setup)
cd /opt/mact   # or your clone of https://github.com/int33k/M-ACT
git pull origin main
./.venv/bin/pip install -e ".[server]"   # or: pip install -e .
sudo systemctl restart mact-server       # or: sudo systemctl restart uvicorn / your unit name
curl -sI https://m-act.live/ | grep -i cache-control   # should show no-store after deploy

CLI commands

Command	Description
mact --version	Print CLI version
mact init --developer <id>	Set developer identity
mact configure-frp ...	Configure FRP tunnel settings
mact create --room <id> --port <port> [...]	Create room; ensures frpc, installs post-commit hook, then tunnel + heartbeat unless --no-live / --no-hook / --no-tunnel
mact join --room <id> --port <port> --secret <s> [...]	Same auto-setup as create
mact leave --room <id>	Disconnect from a room
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	m-act.live	Wildcard subdomain routing ({room}.m-act.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	https://m-act.live	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=m-act.live and DNS *.m-act.live → server:

• Mirror: https://{room}.m-act.live/
• Dashboard: https://{room}.m-act.live/dashboard
• Tunnel vhosts: http://{dev}-{room}.tunnel.m-act.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.