MachineElf

MachineElf is a strict JSON machine-to-machine gateway for autonomous AI agents that need loop-safe human-operator alert routing. It is designed for LangChain, CrewAI, AutoGPT-style planners, crawlers, and LLM orchestration frameworks that hit critical sandbox exceptions, blocked workflows, unsafe retry loops, or operator escalation points.

Public API base:

https://machineelf.onrender.com

Marketplace:

https://rapidapi.com/Atmic/api/machineelf-notification-bridge

Portfolio Services

MachineElf is expanding as a portfolio of cleanly separated M2M utilities. Each service keeps its own Render/RapidAPI surface so the original notification bridge remains stable.

Notification Bridge

• Render: https://machineelf.onrender.com
• RapidAPI: https://rapidapi.com/Atmic/api/machineelf-notification-bridge
• Purpose: strict JSON agent-to-human alert routing through ntfy.sh.

Idempotency Vault

• Render: https://machineelf-idempotency-vault.onrender.com
• OpenAPI: https://machineelf-idempotency-vault.onrender.com/openapi.json
• Agent manifest: https://machineelf-idempotency-vault.onrender.com/.well-known/ai-plugin.json
• LLM context: https://machineelf-idempotency-vault.onrender.com/llms.txt
• RapidAPI: public listing live in validation mode.
• Purpose: best-effort idempotency reservations, result-hash commits, and signed execution receipts for autonomous agents.
• Validation-mode caveat: persistence is ephemeral until real demand justifies paid durable storage.
• Accounting: included in the original MachineElf portfolio daily notification when vault telemetry env vars are configured.

Agent Discovery

• OpenAPI: https://machineelf.onrender.com/openapi.json
• Agent manifest: https://machineelf.onrender.com/.well-known/ai-plugin.json
• LLM context: https://machineelf.onrender.com/llms.txt
• Full LLM context: https://machineelf.onrender.com/llms-full.txt
• Swagger docs: https://machineelf.onrender.com/docs
• Sitemap: https://machineelf.onrender.com/sitemap.xml

What Agents Use It For

• Route urgent failures from cloud sandboxes to a human operator.
• Escalate blocked autonomous workflows instead of silently failing.
• Avoid duplicate notification charges during retry loops with X-Idempotency-Key.
• Use strict Pydantic v2 JSON schemas instead of loose tool strings.
• Register future permitted HTML cleanup plans through a strict scrape-template contract.

Primary Tool

POST /api/v1/execute

Routes one validated alert to a human operator through ntfy.sh.

Consumer-visible headers through RapidAPI:

X-Idempotency-Key: <unique caller-generated key>
Content-Type: application/json

RapidAPI injects the backend X-API-Key as a hidden Gateway secret header. Direct non-RapidAPI deployments still require a valid X-API-Key.

Example request body:

{
  "topic_key": "/machineelf-hidden-ops-channel",
  "title": "Agent Alert: Sandbox Failure",
  "message": "The autonomous run hit a critical cloud sandbox exception and paused for operator review.",
  "priority": 5,
  "max_steps": 1,
  "timeout_seconds": 30,
  "rationale": "Immediate human notification is required because the workflow cannot safely continue."
}

Pricing Metadata

• Priority 1-2 alert routing: $0.01
• Priority 3 alert routing: $0.03
• Priority 4-5 urgent alert routing: $0.07
• Fixed operational cost per successful alert: $0.001
• Net profit formula: markup_fee - cost

Successful notification transactions are written to profit_ledger.json through thread/process locked atomic ledger logic.

Other Tools

POST /api/v1/scrape

Authenticated strict-schema scrape-template registration endpoint. It validates permitted HTML cleanup planning requests and idempotency behavior but does not perform live scraping yet.

GET /api/v1/telemetry

Authenticated daily ledger summary for operators.

When called with send_accounting_update=true, this endpoint now sends one portfolio-level ntfy.sh accounting notification. If the Idempotency Vault telemetry env vars are configured on the original MachineElf Render service, the notification includes both the Notification Bridge and Idempotency Vault daily totals.

Portfolio telemetry env vars:

MACHINEELF_IDEMPOTENCY_VAULT_BASE_URL=https://machineelf-idempotency-vault.onrender.com
MACHINEELF_IDEMPOTENCY_VAULT_API_KEY=<vault-backend-api-key>

Keep the vault backend key private. It should only live in Render environment variables and RapidAPI hidden secret headers.

MCP Wrapper

The repository includes a no-dependency stdio MCP wrapper:

python mcp_server.py

MCP tools:

• machineelf_route_operator_alert
• machineelf_register_scrape_template

Configure:

MACHINEELF_BASE_URL=https://machineelf.onrender.com
MACHINEELF_API_KEY=<paid-or-configured-backend-key>

Local Development

python -m uvicorn main:app --host 127.0.0.1 --port 8000

Verify deployed discovery:

python verify_public_discovery.py https://machineelf.onrender.com

Client Examples

• Python RapidAPI call: examples/python_rapidapi_execute.py
• JavaScript RapidAPI call: examples/javascript_rapidapi_execute.mjs

Safety Model

MachineElf rejects unknown fields, loose strings, markdown code fences, escaped control blocks, hidden control characters, excessive step counts, excessive timeouts, non-JSON state-changing transport, missing idempotency keys, and invalid API keys.

Protected routes remain fail-closed even when public OpenAPI hides the backend X-API-Key for RapidAPI marketplace usability.