mng/vendor-multiple

README.md

@@ -229,7 +229,7 @@ You can interact with `mng` via the terminal (run `mng --help` to learn more).
 `mng` uses robust open source tools like SSH, git, and tmux to run and manage your agents:
 
 - **[agents](libs/mng/docs/concepts/agents.md)** are simply processes that run in [tmux](https://github.com/tmux/tmux/wiki) sessions, each with their own `work_dir` (working folder) and configuration (ex: secrets, environment variables, etc)
-- [agents](libs/mng/docs/concepts/agents.md) run on **[hosts](libs/mng/docs/concepts/hosts.md)**--either locally (by default), or special environments like [Modal](https://modal.com) [Sandboxes](https://modal.com/docs/guide/sandboxes) (`--in modal`) or [Docker](https://www.docker.com) [containers](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) (`--in docker`).  Use `--host <name>` to target an existing host.
+- [agents](libs/mng/docs/concepts/agents.md) run on **[hosts](libs/mng/docs/concepts/hosts.md)**--either locally (by default), or special environments like [Modal](https://modal.com) [Sandboxes](https://modal.com/docs/guide/sandboxes) (`--provider modal`) or [Docker](https://www.docker.com) [containers](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/) (`--provider docker`).  Use the `agent@host` address syntax to target an existing host.
 - multiple [agents](libs/mng/docs/concepts/agents.md) can share a single [host](libs/mng/docs/concepts/hosts.md).
 - [hosts](libs/mng/docs/concepts/hosts.md) come from **[providers](libs/mng/docs/concepts/providers.md)** (ex: Modal, AWS, docker, etc)
 - [hosts](libs/mng/docs/concepts/hosts.md) help save money by automatically "pausing" when all of their [agents](libs/mng/docs/concepts/agents.md) are "idle". See [idle detection](libs/mng/docs/concepts/idle_detection.md) for more details.

apps/minds/README.md

@@ -1,54 +1,30 @@
 # minds
 
-Run your own persistent, specialized AI agents
+Run your own Minds: self-improving, proactive, persistent, specialized AI agents
 
 ## Overview
 
-minds is an application that makes it easy to create and run persistent, specialized AI agents that are *fully* yours.
+`Minds` makes it easy to create AI agents that are *fully* yours:
 
-Each mind is a collection of persistent `mng` agents that, together, form a single higher-level "agent" from the perspective of the end-user. A mind *must*:
-
-1. Serve a web interface (so that it is easy for users to interact with them)
-2. Support chat input/output (able to receive messages from the user and generate responses)
-
-Other than that, the design of each mind is completely open -- you can customize the agent's behavior, the data it has access to, and the way it responds to messages in any way you want.
-
-## Terminology
-
-- **mind**: a collection of persistent mng agents (called **role agents**) that serve a web interface and support chat input/output. The role agents coordinate through shared event streams in a common git repo. Each mind is identified by its `AgentId` and is labeled with `mind=true` for discovery via `mng list`. The mind has a repo directory at `~/.minds/<agent-id>/`. The agent type can be specified in `minds.toml` or defaults to `claude-mind`.
-- **role agent**: a standard mng agent that fulfills a specific role within a mind (e.g., thinking, working, verifying). Each role agent is created via `mng create`, appears in `mng list`, and has its own lifecycle. Multiple instances of the same role can run simultaneously (e.g., several workers).
-- **supporting service**: a background process running alongside a role agent (e.g., watchers, web server). These are *not* mng agents -- they don't appear in `mng list` and have no lifecycle state. They are infrastructure provisioned automatically by the mind plugin.
-- **forwarding server**: a local process (started via `mind forward`) that handles authentication and proxies web traffic from the user's browser to the appropriate mind's web server. Since a user may have *multiple minds* running simultaneously, the forwarding server multiplexes access to all of them through a single local endpoint, handling discovery, routing, and authentication centrally. The forwarding server can also create new minds from git repositories.
-
-## Architecture
-
-The forwarding server provides:
-- Authentication via one-time codes and signed cookies
-- A landing page listing all accessible minds (or a creation form if none exist)
-- Agent creation from git repositories via a web form or API
-- Reverse proxying of HTTP and WebSocket traffic to individual mind web servers using Service Worker-based path rewriting
-
-Each mind may run one or more web servers on separate ports. The forwarding server multiplexes access to all of them under path prefixes (e.g. `/agents/{agent_id}/{server_name}/`). Navigating to `/agents/{agent_id}/` shows a listing of all available servers for that agent.
+- **[Create](TK):** start new Minds instantly! Run them locally or remotely.
+- **[Access](TK):** chat with your Minds from anywhere via the web interface, or just message them on whatever platform you like.
+- **[Manage](TK):** understand what your Minds are doing; stop, restart, or delete them anytime.
+- **[Upgrade](TK):** allow your Mind to improve itself without losing its memories or conversation history.
 
 ## Getting started
 
 ```bash
-# Start the forwarding server
-mind forward
-
-# Visit http://localhost:8420 in your browser
-# If no agents exist, you'll see a form to create one from a git URL
-# The agent will be created and you'll be redirected to it automatically
-```
+# install the Minds application...
+curl -fsSL https://raw.githubusercontent.com/imbue-ai/mng/main/apps/minds/scripts/install.sh | bash
 
-## Creating agents
+# Start the server...
+mind
 
-Agents can be created in two ways:
-
-1. **Via the web UI**: Visit the forwarding server. If no agents exist, you'll see a creation form. Enter a git repository URL and submit. You can also pre-fill the URL via query parameter: `http://localhost:8420/?git_url=https://github.com/user/repo`
-
-2. **Via the API**: POST to `/api/create-agent` with a JSON body containing `git_url`. Poll `/api/create-agent/{agent_id}/status` for creation progress.
+# and a new Mind will be automatically created for you!
+```
 
-## Design
+## Learn more
 
-See [./docs/design.md](./docs/design.md) for more details on the design principles and architecture of minds.
+- [How it works](./docs/overview.md)
+- [Glossary of key concepts](./docs/mind/glossary.md)
+- [Design principles and mind architecture](./docs/design.md)

apps/minds/docs/design.md

@@ -1,6 +1,6 @@
 # Overview
 
-See the [README](../README.md) for an overview of what minds are and the terminology used throughout.
+See the [README](../README.md) for an overview of what minds are and see [the glossary](./mind/glossary.md) for terminology used throughout.
 
 # Relationship to mng
 
@@ -29,6 +29,29 @@ The agent type is passed directly to `mng create --type <type>` during creation.
 agent_type = "elena-code"
 ```
 
+## Vendor repos
+
+During agent creation, external repositories can be added as git subtrees under `vendor/` in the mind's directory. This is configured via `[[vendor]]` entries in `minds.toml`. Each entry must specify either a remote `url` or a local `path`, and can optionally pin a specific git `ref` (defaults to the current HEAD).
+
+Local repos must be "clean" (no uncommitted changes or untracked files) before they can be vendored.
+
+When no `[[vendor]]` section exists, the system falls back to vendoring the `mng` repo (using the local checkout in development mode, or the GitHub URL otherwise).
+
+```toml
+# minds.toml
+
+# Vendor the mng repo from GitHub at a specific commit
+[[vendor]]
+name = "mng"
+url = "https://github.com/imbue-ai/mng.git"
+ref = "abc123"
+
+# Vendor a local repo (must be clean)
+[[vendor]]
+name = "my-lib"
+path = "/path/to/local/repo"
+```
+
 ## Settings
 
 Minds read per-mind settings from `minds.toml` in the agent work directory (`$MNG_AGENT_WORK_DIR/minds.toml`). This file is optional -- if it does not exist, all settings use their built-in defaults.
@@ -54,8 +77,9 @@ See [the forwarding server design doc](../imbue/minds/forwarding_server/README.m
 When a user visits the forwarding server and no agents exist, they are shown a creation form where they can provide a git repository URL. The forwarding server:
 
 1. Clones the repository to `~/.minds/<agent-id>/`
-2. Resolves the agent type from `minds.toml` (or uses `claude-mind` as default)
-3. Runs `mng create --type <type> --id <id> --in-place --label mind=true` to start the agent
+2. Loads settings from `minds.toml` (agent type, vendor repos, etc.)
+3. Adds configured vendor repos as git subtrees (or defaults to vendoring mng)
+4. Runs `mng create --type <type> --id <id> --in-place --label mind=true` to start the agent
 4. Redirects the user to the newly created agent (the user is already authenticated via the global session)
 
 Agent creation is also available via the `/api/create-agent` API endpoint, which accepts a JSON body with `git_url` and returns the agent ID for status polling.

apps/minds/docs/mind/glossary.md

@@ -0,0 +1,8 @@
+# Glossary
+
+There are several key concepts to understand when working with minds:
+
+- **mind**: a collection of persistent mng agents (called **role agents**) that serve a web interface and support chat input/output. The role agents coordinate through shared event streams in a common git repo. Each mind is identified by its `AgentId` and is labeled with `mind=true` for discovery via `mng list`. The mind has a repo directory at `~/.minds/<agent-id>/`. The agent type can be specified in `minds.toml` or defaults to `claude-mind`.
+- **role agent**: a standard mng agent that fulfills a specific role within a mind (e.g., thinking, working, verifying). Each role agent is created via `mng create`, appears in `mng list`, and has its own lifecycle. Multiple instances of the same role can run simultaneously (e.g., several workers).
+- **supporting service**: a background process running alongside a role agent (e.g., watchers, web server). These are *not* mng agents -- they don't appear in `mng list` and have no lifecycle state. They are infrastructure provisioned automatically by the mind plugin.
+- **forwarding server**: a local process (started via `mind forward`) that handles authentication and proxies web traffic from the user's browser to the appropriate mind's web server. Since a user may have *multiple minds* running simultaneously, the forwarding server multiplexes access to all of them through a single local endpoint, handling discovery, routing, and authentication centrally. The forwarding server can also create new minds from git repositories.

apps/minds/docs/overview.md

@@ -0,0 +1,26 @@
+# How it works
+
+Each mind is a collection of persistent `mng` agents that, together, form a single higher-level "agent" from the perspective of the end-user. A mind *must*:
+
+1. Serve a web interface (so that it is easy for users to interact with them)
+2. Support chat input/output (able to receive messages from the user and generate responses)
+
+Other than that, the design of each mind is completely open -- you can customize the agent's behavior, the data it has access to, and the way it responds to messages in any way you want.
+
+## Architecture
+
+The forwarding server provides:
+- Authentication via one-time codes and signed cookies
+- A landing page listing all accessible minds (or a creation form if none exist)
+- Agent creation from git repositories via a web form or API
+- Reverse proxying of HTTP and WebSocket traffic to individual mind web servers using Service Worker-based path rewriting
+
+Each mind may run one or more web servers on separate ports. The forwarding server multiplexes access to all of them under path prefixes (e.g. `/agents/{agent_id}/{server_name}/`). Navigating to `/agents/{agent_id}/` shows a listing of all available servers for that agent.
+
+## Creating agents
+
+Agents can be created in two ways:
+
+1. **Via the web UI**: Visit the forwarding server. If no agents exist, you'll see a creation form. Enter a git repository URL and submit. You can also pre-fill the URL via query parameter: `http://localhost:8420/?git_url=https://github.com/user/repo`
+
+2. **Via the API**: POST to `/api/create-agent` with a JSON body containing `git_url`. Poll `/api/create-agent/{agent_id}/status` for creation progress.

apps/minds/docs/user_story.md

@@ -1,11 +1,11 @@
 This is the primary flow for how a user would create a mind for the first time:
 
-1. User starts the forwarding server: `mind forward`
+1. User starts the forwarding server: `mind`
 2. The server prints a one-time login URL to the terminal
 3. User visits the login URL to authenticate (sets a global session cookie)
 4. Since no agents exist, the landing page shows a creation form with a git URL field (can also be pre-filled via `/?git_url=...`)
 5. User enters the git URL and clicks Create
-6. The forwarding server clones the repository, resolves the agent type from `minds.toml` (or uses `claude-mind`), generates an agent ID, moves the repo to `~/.minds/<agent-id>/`, and runs `mng create --type <type> --id <id> --in-place --label mind=true`
+6. The forwarding server clones the repository, loads settings from `minds.toml`, adds configured vendor repos as git subtrees, resolves the agent type (or uses `claude-mind`), generates an agent ID, and runs `mng create --type <type> --id <id> --in-place --label mind=true`
 7. While creating, the user sees a progress page that polls for status
 8. When creation completes, the user is redirected to their mind's web interface at `/agents/<agent-id>/web/`
 

apps/minds/imbue/minds/errors.py

@@ -31,6 +31,12 @@ class MngCommandError(MindError):
 
 
 class VendorError(MindError):
-    """Raised when vendoring mng into a mind repo fails."""
+    """Raised when vendoring a repo into a mind fails."""
+
+    ...
+
+
+class DirtyRepoError(VendorError):
+    """Raised when a local vendor repo has uncommitted changes or untracked files."""
 
     ...

apps/minds/imbue/minds/forwarding_server/agent_creator.py

@@ -32,11 +32,13 @@
 from imbue.minds.errors import GitCloneError
 from imbue.minds.errors import MngCommandError
 from imbue.minds.errors import VendorError
+from imbue.minds.forwarding_server.vendor_mng import default_vendor_configs
 from imbue.minds.forwarding_server.vendor_mng import find_mng_repo_root
-from imbue.minds.forwarding_server.vendor_mng import vendor_mng
+from imbue.minds.forwarding_server.vendor_mng import vendor_repos
 from imbue.minds.primitives import AgentName
 from imbue.minds.primitives import GitUrl
 from imbue.mng.primitives import AgentId
+from imbue.mng_claude_mind.data_types import ClaudeMindSettings
 from imbue.mng_claude_mind.settings import load_settings_from_path
 from imbue.mng_llm.settings import SETTINGS_FILENAME
 
@@ -115,23 +117,20 @@ def clone_git_repo(
         )
 
 
-def resolve_agent_type(repo_dir: Path) -> str:
-    """Resolve agent type from minds.toml in the repo, falling back to DEFAULT_AGENT_TYPE.
+def load_creation_settings(repo_dir: Path) -> ClaudeMindSettings:
+    """Load ClaudeMindSettings from minds.toml in the repo, falling back to defaults.
 
-    If the repo contains a minds.toml with an agent_type field, uses that value.
-    Otherwise returns DEFAULT_AGENT_TYPE ('claude-mind').
+    Returns the parsed settings (with defaults for any missing values).
+    Used during agent creation to read both agent_type and vendor config.
     """
     settings_path = repo_dir / SETTINGS_FILENAME
     try:
-        settings = load_settings_from_path(settings_path)
+        return load_settings_from_path(settings_path)
     except FileNotFoundError:
-        return DEFAULT_AGENT_TYPE
+        return ClaudeMindSettings()
     except (tomllib.TOMLDecodeError, ValidationError, OSError) as e:
-        logger.warning("Failed to parse {}, using default agent type: {}", settings_path, e)
-        return DEFAULT_AGENT_TYPE
-    if settings.agent_type is not None:
-        return settings.agent_type
-    return DEFAULT_AGENT_TYPE
+        logger.warning("Failed to parse {}, using defaults: {}", settings_path, e)
+        return ClaudeMindSettings()
 
 
 def run_mng_create(
@@ -273,11 +272,15 @@ def _create_agent_background(
                 log_queue.put("[minds] Cloning {}...".format(git_url))
                 clone_git_repo(GitUrl(git_url), mind_dir, on_output=emit_log)
 
-                log_queue.put("[minds] Vendoring mng...")
+                settings = load_creation_settings(mind_dir)
+
                 mng_repo_root = find_mng_repo_root()
-                vendor_mng(mind_dir, mng_repo_root, on_output=emit_log)
+                vendor_configs = settings.vendor if settings.vendor else default_vendor_configs(mng_repo_root)
+
+                log_queue.put("[minds] Vendoring {} repo(s)...".format(len(vendor_configs)))
+                vendor_repos(mind_dir, vendor_configs, on_output=emit_log)
 
-                agent_type = resolve_agent_type(mind_dir)
+                agent_type = settings.agent_type if settings.agent_type is not None else DEFAULT_AGENT_TYPE
                 parsed_name = AgentName(agent_name)
 
                 with self._lock:

apps/minds/imbue/minds/forwarding_server/agent_creator_test.py

@@ -7,11 +7,10 @@
 from imbue.minds.errors import GitCloneError
 from imbue.minds.forwarding_server.agent_creator import AgentCreationStatus
 from imbue.minds.forwarding_server.agent_creator import AgentCreator
-from imbue.minds.forwarding_server.agent_creator import DEFAULT_AGENT_TYPE
 from imbue.minds.forwarding_server.agent_creator import clone_git_repo
 from imbue.minds.forwarding_server.agent_creator import extract_repo_name
+from imbue.minds.forwarding_server.agent_creator import load_creation_settings
 from imbue.minds.forwarding_server.agent_creator import make_log_callback
-from imbue.minds.forwarding_server.agent_creator import resolve_agent_type
 from imbue.minds.primitives import GitUrl
 from imbue.minds.testing import init_and_commit_git_repo
 from imbue.mng.primitives import AgentId
@@ -43,23 +42,34 @@ def test_extract_repo_name_falls_back_to_mind() -> None:
     assert extract_repo_name(".git") == "mind"
 
 
-def test_resolve_agent_type_returns_default_when_no_toml(tmp_path: Path) -> None:
-    assert resolve_agent_type(tmp_path) == DEFAULT_AGENT_TYPE
+def test_load_creation_settings_returns_defaults_when_no_toml(tmp_path: Path) -> None:
+    settings = load_creation_settings(tmp_path)
+    assert settings.agent_type is None
 
 
-def test_resolve_agent_type_reads_from_minds_toml(tmp_path: Path) -> None:
+def test_load_creation_settings_reads_agent_type(tmp_path: Path) -> None:
     (tmp_path / "minds.toml").write_text('agent_type = "custom-type"\n')
-    assert resolve_agent_type(tmp_path) == "custom-type"
+    settings = load_creation_settings(tmp_path)
+    assert settings.agent_type == "custom-type"
 
 
-def test_resolve_agent_type_returns_default_for_toml_without_agent_type(tmp_path: Path) -> None:
-    (tmp_path / "minds.toml").write_text("[some_section]\nkey = 1\n")
-    assert resolve_agent_type(tmp_path) == DEFAULT_AGENT_TYPE
+def test_load_creation_settings_returns_defaults_for_toml_without_agent_type(tmp_path: Path) -> None:
+    (tmp_path / "minds.toml").write_text('[chat]\nmodel = "claude-sonnet-4-6"\n')
+    settings = load_creation_settings(tmp_path)
+    assert settings.agent_type is None
 
 
-def test_resolve_agent_type_returns_default_for_malformed_toml(tmp_path: Path) -> None:
+def test_load_creation_settings_returns_defaults_for_malformed_toml(tmp_path: Path) -> None:
     (tmp_path / "minds.toml").write_text("not valid toml {{{")
-    assert resolve_agent_type(tmp_path) == DEFAULT_AGENT_TYPE
+    settings = load_creation_settings(tmp_path)
+    assert settings.agent_type is None
+
+
+def test_load_creation_settings_reads_vendor_config(tmp_path: Path) -> None:
+    (tmp_path / "minds.toml").write_text('[[vendor]]\nname = "mng"\nurl = "https://github.com/imbue-ai/mng.git"\n')
+    settings = load_creation_settings(tmp_path)
+    assert len(settings.vendor) == 1
+    assert settings.vendor[0].name == "mng"
 
 
 # -- clone_git_repo tests --