Docs

🜂 MatrixSwarm Deployment Guide (Phoenix GUI)

By matrixswarm

October 27, 2025 AT 02:56 PM (updated: 5 days ago)

Get the project if you don't already have it; You need both MatrixOS and Phoenix GUI; one can't be used without the other: Phoenix MatrixOS

I. Unlock the Vault
Before any deployment, Phoenix must load your cryptographic vault — this is where all keys, directives, and deployments live.

1. Launch Phoenix.
The cockpit opens in a locked state showing the “🔐 Unlock” button.

2. Select Vault → Enter Password → Unlock.
This opens a secure JSON vault via the VaultPasswordDialog, decrypts it using your password, and emits a vault.unlocked event — triggering the control panel to refresh deployments.

3. Once unlocked, the top bar (“Phoenix Control Panel”) becomes active. It’ll show:

🔌 Connect  | 🌐 Connections  | 📄 Directives |  🔐 Vault (for re-locking or reopening)


Connect - when you've made a deployment, this is where you launch and connect.
Connection Manager - this is where you add connection details for your agents, that will be stamped into your deployments, forging the directive templates.
Directives - add, edit, delete templates (directive templates); deployments - add, delete, deploy, take directive templates and stamp them with data taken from
                   information provided in the 'connection manager'
Vault - close the currently open vault and exit

II. Create or Import a Directive Template

Directives describe your deployment topology — agents, services, and watchers.

1. Click 📄 Directives on the control panel.
This opens the Directive Manager.

2. Inside the manager:

  - Load an existing directive file (JSON or Python).

  - .py directives expose a matrix_directive dict — e.g., from /boot_directives/matrix.py.

  - Or paste new JSON directly into the editor panel.

 3. Click Save to Vault. 
    Phoenix assigns it a unique directive_xxxxxx ID and stores it under vault_data["directives"]

III. Assign Connections (Network Manager)

Before deployment, agents must know which connection profiles they’ll use.

1. Click 🌐 Connections on the control panel.
   This opens the Connection Manager Dialog, where you define protocols (HTTPS, WSS, Telegram, Discord, etc.).

2. During deployment, Phoenix automatically launches a Connection Assignment Dialog.
    Each agent is listed with its protocol tag. Select the matching connection from the dropdown until each row is “✅ resolved”.

 - This step verifies required fields using the CERT_INJECTION_MAP, ensuring certs and endpoints exist before encryption.

IV. Mint and Preview the Deployment

1. In Directive Manager, select a saved directive and click Deploy.
    Phoenix begins a guided process (DirectiveManagerDialog.deploy_directive).

2. Enter a friendly label for your deployment. 
   This becomes its runtime name and will appear in your vault under deployments.

3. Phoenix now:

- Wraps each agent (agent_connection_wrapper, agent_cert_wrapper, etc.).
- Injects certs and keys per the mapping rules.
- Merges configs and crypto material in-place to form a runtime directive (mint_directive_for_deployment).

4. You’ll see a Directive Encryption Staging Window.
    This allows you to preview the full assembled directive before encryption.

V. Encrypt and Store

1. Upon confirming the preview, Phoenix encrypts the directive bundle (generate_swarm_encrypted_directive) with a one-time swarm AES key, then saves:

   - The encrypted directive to /boot_directives/{deployment_label}.enc.json

    - The swarm key to /boot_directives/keys/{deployment_label}.key.

2. Upload the Swarm Key file and directive to your MatrixOS server. On a centos machine, the path would be /matrix/boot_directive for the directive and /matrix/boot_directive/keys/.
   To launch, e.g.
   
  matrixd boot --universe my-ai-universe
 
  You do not have to keep the key on the drive, you can launch using the swarm key directly, e.g.

  matrixd boot --universe my-ai-universe   --swarm_key PegPrgjMgRz9xmThzSy/gaw4fCtsH20JvCQv0jvg+7A=

  Note: if you use the swarm_key on the command line, you need to manually start it every time you boot your server.

3. Metadata about the deployment — including swarm key, certs, agent map, and timestamps — is written back into the vault using mint_deployment_metadata().

4. Once saved, the deployment will appear under “Deployed Directives” in the manager list.

VI. Connect and Operate

1. Return to the Phoenix Control Panel.

2. Select your newly minted deployment from the dropdown.

3. Click 🔌 Connect to launch a Session Window.

Each session opens as an embedded child process (run_session) inside the cockpit — complete with Agent Tree, Log Panel, and Inspector.

From here, you can:

 - View agent logs (📄 Agent Logs)

 - Inspect configurations

 - Monitor threads and processes via Agent Detail Panel.

 - Custom Panels for Different Agents you get from us or make yourself.

🜂 MatrixSwarm Deployment Guide (Phoenix GUI)

II. Create or Import a Directive Template

III. Assign Connections (Network Manager)

IV. Mint and Preview the Deployment

V. Encrypt and Store

VI. Connect and Operate

Comments 0

Leaving Matrixswarm for External Site

Flagged Content

Members that favorited