Specification: Manual Slop Headless Backend

Overview

Transform Manual Slop into a decoupled, container-friendly backend service. This track enables the core AI orchestration and tool execution logic to run without a GUI, exposing its capabilities via a secured REST API optimized for an Unraid Docker environment.

Goals

Decouple the GUI logic (Dear PyGui, ImGui) from the core AI and Tool logic.
Implement a lightweight REST API server (FastAPI) to handle AI interactions.
Ensure full compatibility with Unraid Docker networking and configuration patterns.
Maintain the "Human-in-the-Loop" safety model through a remote confirmation mechanism.

Functional Requirements

1. Headless Mode Lifecycle

Startup: Provide a --headless flag or [headless] section in manual_slop.toml to skip GUI initialization.
Dependencies: Ensure the app can start in environments without an X11/Wayland display or GPU.
Service Mode: Support running as a persistent background daemon/service.

2. REST API (FastAPI)

Status/Health: /status and /health endpoints for Docker/Unraid monitoring.
AI Interface: /generate and /stream endpoints to interact with configured AI providers.
Tool Management: Endpoints to list and execute tools (PowerShell/MCP).
Session Support: Manage conversation history and project context via API.

3. Security & Authentication

API Key: Require a X-API-KEY header for all sensitive endpoints.
Unraid Integration: API keys should be configurable via Environment Variables (standard for Unraid templates).

4. Remote Confirmation Mechanism

Challenge/Response: When a tool requires execution, the API should return a "Pending Confirmation" state.
Webhook/Poll: Support a mechanism (e.g., a /confirm/{id} endpoint) for the future frontend to approve/deny actions.

Non-Functional Requirements

Performance: Headless mode should use significantly less memory/CPU than the GUI version.
Logging: Use standard Python logging for Docker-compatible stdout/stderr output.
Portability: Must run reliably inside a standard python:3.11-slim or similar Docker image.

Acceptance Criteria

Manual Slop starts successfully with --headless and no display environment.
API is accessible via a configurable port (e.g., 8000).
All API requests are rejected without a valid API Key.
AI generation works via REST endpoints, returning structured JSON or a stream.
Tool execution is successfully blocked until a separate "Confirm" API call is made.

Out of Scope

Building the actual Unraid GUI frontend (React/Vue/etc.).
Multi-user authentication (OIDC/OAuth2).
Native Unraid .plg plugin development (focusing on Docker).

2.7 KiB Raw Blame History