tmpl/multi-agent-mux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: document .mam.env config file, legacy migration path, and save loop reports

Browse Source
This commit is contained in:
Godopu
2026-08-04 21:43:00 +09:00
parent 7d54fd8104
commit 2ff8b2c4a9
9 changed files with 531 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
BOOTSTRAP.md
+17 -8
View File
@@ -42,33 +42,39 @@ The human developer bootstrapped the workspace by running:
curl -fsSL https://git.godopu.com/tmpl/multi-agent-mux/raw/branch/main/deploy/install.sh | bash
```
The installer verified system dependencies, staged the repository, copied the runtime `.agents/` scaffolding and documentation files (including this `BOOTSTRAP.md`), and set up the default `.env` and `.venv` environments.
The installer verified system dependencies, staged the repository, copied the runtime `.agents/` scaffolding and documentation files (including this `BOOTSTRAP.md`), and set up the default `.mam.env` and `.venv` environments.
> [!NOTE]
> **Verify Only**: AI agents reading this guide must **not** attempt to run the installation script again. Proceed directly to configuration and verification steps.
---
## 3. Environment Configuration (.env)
## 3. Environment Configuration (.mam.env)
To set up the messaging broker and execution paths, you must create and modify a local environment configuration file (`.env`).
To set up the messaging broker and execution paths, you must create and modify a local environment configuration file (`.mam.env`).
> [!NOTE]
> **Legacy Config Migration**: If you are updating from an earlier version that used `.env`, MAM will continue to read `.env` as a fallback. However, we recommend migrating to `.mam.env` via `./deploy/generate-env.sh --migrate-legacy`.
### Step 3.1: Run the Generation Script
Run the environment template copy script provided in the project root:
```bash
# Automatically copy .env.example to .env (does not overwrite if it already exists)
# Automatically copy .mam.env.example to .mam.env (does not overwrite if it already exists)
./deploy/generate-env.sh
# To force overwrite and create a backup of the existing .env:
# To force overwrite and create a backup of the existing .mam.env:
./deploy/generate-env.sh --force
# To explicitly migrate an existing legacy .env to .mam.env:
./deploy/generate-env.sh --migrate-legacy
```
### Step 3.2: Modify Environment Variables
Open the generated `.env` file to configure settings as needed.
Open the generated `.mam.env` file to configure settings as needed.
> [!NOTE]
> The default `.env` file generated by `generate-env.sh` has all environment variables commented out. If left commented out, the system defaults to using relative paths (`.mam/`, etc.) relative to the local project root, and the public MQTT broker. You can use it as-is without uncommenting anything.
> The default `.mam.env` file generated by `generate-env.sh` has all environment variables commented out. If left commented out, the system defaults to using relative paths (`.mam/`, etc.) relative to the local project root, and the public MQTT broker. You can use it as-is without uncommenting anything.
1. **MQTT Broker Setup (`MQTT_BROKER`)**:
* The default broker is HiveMQ's public sandbox broker (`broker.hivemq.com`). However, for production work where security and privacy are critical, we strongly recommend changing this to a private broker address.
@@ -117,11 +123,14 @@ Ensure that the local registry directories required to track agent states and jo
* `.mam/jobs/`: Holds detailed metadata files for registered asynchronous jobs.
* `.mam/delegate_job_logs/`: Holds the audit logs (`events.ndjson`) for all backplane events published by agents.
2. **Git Ignore Configuration (`.gitignore`)**:
* When initializing a new project, verify that the following entries are configured in `.gitignore` to prevent committing local runtimes to the repository. The exception `!.env.example` must be kept to preserve the template:
* When initializing a new project, verify that the following entries are configured in `.gitignore` to prevent committing local runtimes to the repository. The exception `!.mam.env.example` must be kept to preserve the template:
```text
.env
.env.*
!.env.example
.mam.env
.mam.env.*
!.mam.env.example
.mam/
.venv/
__pycache__/