Your Agent Boots. Phoenix Still Doesn’t Know It Exists.

Description and use

After aligning the agent source with a matching Phoenix meta-file, the agent appears in the workspace palette, can be configured, and runs correctly.

Problem

A MatrixOS agent starts and emits a beacon, yet Phoenix’s swarm workspace cannot detect it because the contract between the agent source and Phoenix metadata is incomplete.

Outcome

After aligning the agent source with a matching Phoenix meta-file, the agent appears in the workspace palette, can be configured, and runs correctly.

Workflow

• Create a Python package in MatrixOS with the same snake_case name as the agent and implement the required lifecycle methods.
• Ensure environment paths (SITE_ROOT, AGENT_PATH) are inserted into sys.path before imports.
• Import necessary mixins and utilities (BootAgent, ReflexAlertMixin, interruptible_sleep, etc.).
• Define the Agent class with __init__, worker_pre, post_boot, and worker methods, using config defaults and emitting a beacon.
• Create a Phoenix meta-file agents_meta/shift_scribe.json with name matching the agent package.
• Populate the JSON with required fields (name, description, config_schema, defaults, etc.).
• Add optional configuration editors and custom panels in Phoenix’s matrix_gui directories if needed.
• Verify that Phoenix reads the JSON, adds the agent to the palette, and can launch it.
• Run the agent to confirm it reports liveness and performs its task.

Evidence

A MatrixOS agent can start, emit a beacon, and do useful work—while Phoenix’s swarm workspace still has no idea it exists.

Source

The metadata file belongs to the agent type, not to each swarm instance. Phoenix reads the JSON files in agents_meta to populate the agent palette.

Source