Service Management API

Manage Momentry core services, including start, stop, and health check operations.

Overview

Service Management API provides endpoints for: - Start Service: Launch inference services (e.g., MBE) - Stop Service: Terminate running services - Health Check: Monitor service status

Endpoints

POST /api/v2/service/start

Auth: Required

Scope: system-level

Start a Momentry service.

Request Parameters

Field	Type	Required	Default	Description
name	string	Yes	—	Service name (e.g., "mbe")
model	string	No	—	Model path or name
port	number	No	8080	Service port

Example

# Start MBE service with default model
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

# Start MBE service with custom model and port
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mbe",
    "model": "/Users/accusys/models/gemma-4-12b-it-Q4_K_M.gguf",
    "port": 8080
  }'

Response (200)

{
  "result": "started",
  "pid": 12345
}

Field	Type	Description
result	string	"started" or "failed"
pid	number	Process ID if successful
error	string	Error message if failed

Implementation Details

File: /Users/accusys/momentry_core/src/api/service_management.rs

Process: 1. Validates service name (currently only "mbe" supported) 2. Checks if port is already in use 3. Stops existing process on that port 4. Spawns llama-server with specified model 5. Waits up to 60 seconds for service to be ready 6. Returns process ID on success

Supported Services: - "mbe" - MarkBase Engine (llama.cpp server)

---

POST /api/v2/service/stop

Auth: Required

Scope: system-level

Stop a running service.

Request Parameters

Field	Type	Required	Default	Description
name	string	Yes	—	Service name (e.g., "mbe")

Example

# Stop MBE service
curl -s -X POST "$API/api/v2/service/stop" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

Response (200)

Success:

{
  "result": "stopped"
}

Failure:

{
  "result": "failed",
  "error": "No service running on port 8080"
}

Field	Type	Description
result	string	"stopped" or "failed"
error	string	Error message if failed

Implementation Details

File: /Users/accusys/momentry_core/src/api/service_management.rs

Process: 1. Validates service name 2. Finds process ID by port (8080) 3. Sends kill signal 4. Returns success/failure

---

GET /api/v1/mbe/health

Auth: Public

Scope: system-level

Check MBE (MarkBase Engine) health status.

Request Parameters

None

Example

# Check MBE health
curl -s "$API/api/v1/mbe/health"

Response (200)

Online:

{
  "status": "ok",
  "model": "gemma-4-12b-it-Q4_K_M.gguf",
  "uptime": 3600
}

Offline:

{
  "status": "offline"
}

Field	Type	Description
status	string	"ok" or "offline"
model	string	Model name if online
uptime	number	Uptime in seconds (currently always 0)

Implementation Details

File: /Users/accusys/momentry_core/src/api/service_management.rs

Process: 1. Checks if port 8080 is in use 2. Calls /v1/models endpoint 3. Extracts model name from response 4. Returns health status

Health Check Endpoint: http://127.0.0.1:8080/v1/models

---

Error Codes

Code	HTTP	When
E401	401	Missing or invalid API key
E400	400	Invalid service name
E500	500	Service start/stop failed

---

Usage Patterns

Start Service → Check Health

# Start MBE
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

# Wait a few seconds
sleep 5

# Check health
curl -s "$API/api/v1/mbe/health"

Stop Service → Verify Stopped

# Stop MBE
curl -s -X POST "$API/api/v2/service/stop" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

# Check health (should be offline)
curl -s "$API/api/v1/mbe/health"

Restart Service

# Stop if running
curl -s -X POST "$API/api/v2/service/stop" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

# Wait for cleanup
sleep 3

# Start with new configuration
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe", "port": 8080}'

---

Configuration

Default Settings

MBE (llama-server): - Port: 8080 - Model: /Users/accusys/models/gemma-4-12b-it-Q4_K_M.gguf - mmproj: /Users/accusys/models/mmproj-F16.gguf - Binary: /Users/accusys/llama.cpp/build/bin/llama-server

Launch Parameters:

llama-server \
  -m <model_path> \
  --mmproj <mmproj_path> \
  --host 0.0.0.0 \
  --port 8080 \
  -ngl 99 \
  -c 8192 \
  --temp 0.1 \
  -b 4096 \
  -ub 4096

Environment Variables

The start process sets: - PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

---

Related Documentation

• Health API
• MarkBase Documentation
• LLM Services Guide

---

Common Issues

Service Fails to Start

Symptoms: {"result": "failed", "error": "..."}

Possible Causes: 1. Model file not found 2. Port already in use by another process 3. Insufficient permissions 4. Binary not found

Solution:

# Check model file exists
ls -la /Users/accusys/models/gemma-4-12b-it-Q4_K_M.gguf

# Check port availability
lsof -i :8080

# Check binary exists
ls -la /Users/accusys/llama.cpp/build/bin/llama-server

Health Check Returns "offline"

Symptoms: {"status": "offline"}

Possible Causes: 1. Service not started 2. Service crashed after startup 3. Network/firewall issue

Solution:

# Start service
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe"}'

# Check process status
ps aux | grep llama-server

# Check logs
tail -f ~/momentry_core/logs/momentry_3002.log

Service Keeps Restarting

Symptoms: PID changes frequently, service unstable

Possible Causes: 1. Out of memory 2. Model too large 3. Hardware issue

Solution:

# Check memory usage
top -pid $(pgrep -f llama-server)

# Try smaller model or reduce parameters
curl -s -X POST "$API/api/v2/service/start" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "mbe", "model": "<smaller_model_path>"}'

---

Version History

Version	Date	Changes
1.0	2026-10-24	Initial documentation