multi-agent-mux/deploy/README.md

🚀 Multi-Agent Mux (MAM) Deployment & Gitea Integration

This directory contains packaging templates and installation scripts to deploy the Multi-Agent Mux framework into workspaces hosted on Gitea (or GitHub).

---

📁 Deployment Directory Structure

• install.sh: A self-contained, idempotent remote shell installer (via curl) that checks system requirements (tmux, python3), detects NFS/network filesystem mounts, sets up a local python virtual environment (.venv), and initializes environment configuration (.env).
• install_mam.sh: A local-clone installer that copies rules/skills (.agents/), AGENTS.md, and sets up environment bootstrap on target projects.
• generate-env.sh: Environment configuration bootstrap helper.
• INSTALL.md: Detailed installation and quick-start user manual.
• plugin.json: Metadata declaration file to register MAM as an installable plugin for AI Agent coding platforms (such as Claude Code, Antigravity, or other TUI clients).
• gitea-ci.yml: CI/CD pipeline definition template for Gitea Actions (running ShellCheck linting on bash scripts, validation on python scripts, and compilation tests).

---

📦 How to Install and Deploy

1. Simple One-Liner Installation (from Gitea repository)

Once you push this repository to your Gitea instance, users can install it in their local workspace directory by running:

curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash

Alternatively, if they have cloned the repository, they can execute:

bash deploy/install.sh

2. Local-Clone Installation

If you already have cloned this repository locally, you can port MAM to other local target projects:

bash deploy/install_mam.sh --target /path/to/your/project

Refer to INSTALL.md inside this directory for the full instructions and workflows.

Note

The local-clone installer does not ship update.sh/remove.sh to targets. To enable in-place updates, re-run the remote installer (curl ... | bash) or copy deploy/update.sh + deploy/remove.sh manually.

3. Custom Fork / Private Mirror Installations

If you run a private mirror or fork, you can override the source URLs during installation using environment variables:

# Installing from a custom mirror (pipe prepends must be applied to the bash command)
curl -fsSL https://my-mirror.example.com/.../install.sh \
  | MAM_REPO_URL=https://my-mirror.example.com/me/multi-agent-mux.git \
    MAM_ARCHIVE_URL=https://my-mirror.example.com/me/multi-agent-mux/archive/main.tar.gz \
    bash

# Updating an existing workspace against a mirror
MAM_INSTALLER_URL=https://my-mirror.example.com/.../install.sh bash deploy/update.sh

4. Registering as a Workspace Plugin

To register these skills globally or for a specific workspace:

• Workspace Level: Copy the .agents/ folder into your project root.
• Global Level (Gemini/Antigravity): Register the plugin path in your global config file at ~/.gemini/config/skills.json:

  {
    "entries": [
      { "path": "/absolute/path/to/multi-agent-mux/.agents/skills" }
    ]
  }
  

---

🤖 Gitea Actions CI/CD Setup

To automate testing and script linting on your Gitea repository:

1. Ensure Gitea Actions is enabled on your Gitea instance.
2. Copy the Gitea CI workflow to your workspace's workflow folder:

   mkdir -p .gitea/workflows
   cp deploy/gitea-ci.yml .gitea/workflows/ci.yml
   

3. Commit and push to your Gitea repository. The pipeline will validate shell syntax and python file compilation on every push to main and pull requests.