MDJourney Edge Agent

The MDJourney Edge Agent is a lightweight service for research workstations and local data servers. It watches filesystem events, validates the p_/d_ hierarchy, and publishes ingestion events to an MDJourney backend gateway.

This package is developed inside the MDJourney monorepo but is designed to remain independently installable and releasable on PyPI.

Installation

From PyPI

pip install mdjourney-agent

From source (local development)

cd edge-agent
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Quickstart

1. Configure the agent interactively:

mdjourney-agent configure

2. Run diagnostics:

mdjourney-agent doctor

3. Start monitoring:

mdjourney-agent run

Configuration

Configuration is loaded from:

• YAML: ~/.config/mdjourney/config.yaml
• legacy JSON fallback: ~/.config/mdjourney/config.json
• environment variables (take precedence)

Key settings include:

• AGENT_ID
• WATCH_PATH
• GATEWAY_URL
• GATEWAY_TOKEN
• Redis settings (REDIS_URL or REDIS_HOST/REDIS_PORT/REDIS_DB/REDIS_PASSWORD)

For full details, see:

• docs/configuration.md
• docs/operations.md
• docs/compatibility.md

Documentation for Maintainers

• Release runbook: docs/release.md
• Changelog: CHANGELOG.md

Troubleshooting

• 403 Forbidden: check that GATEWAY_TOKEN is valid.
• Permission denied: ensure user access to WATCH_PATH.
• Agent offline: verify gateway reachability and run mdjourney-agent doctor.