spec.md

Spynel Hugging Face Deployment and Integration Contract

Scope

This document is the source of truth for the Spynel deployment branch. Changes must remain modular and minimize invasive changes to Agent Zero core behavior.

Hugging Face Docker Space

• The root Docker image must run Agent Zero as a non-root UID/GID 1000 process.
• The WebUI must listen on 0.0.0.0:7860, and port 7860 must be the only required published port.
• Startup must not require chpasswd, SSH, cron, supervisor, sudo, privileged Docker flags, or another root-only service.
• The Space image must retain the base image's /ins/* installers and copy only the HF-specific entrypoint from docker/run/fs/; installer and entrypoint scripts must fail build-time integrity checks for Git LFS pointer text or a missing shebang before any installer executes.
• Agent Zero application files must be readable by UID 1000. Runtime state and Hugging Face, XDG, and Matplotlib cache directories must be writable by UID
• Kokoro, spaCy, their models, and other dependencies must be installed in a writable image-build layer. Runtime dependency installation must not be used to hide missing build dependencies or write into immutable image layers.
• Space startup errors must be fixed at their cause rather than suppressed.

Administrative Profile Creation

• Provide an authenticated, CSRF-protected API for explicitly creating profiles under usr/agents/ through existing profile persistence helpers.
• Validate profile names and prompt filenames, reject traversal/nested paths, reserved profiles, and duplicates, and preserve existing profile selection.
• Routing syntax must never invoke profile creation. An unknown routed profile must fail explicitly without creating a context or profile directory.

Spynel Profile and Routing

Ship a bundled spynel Agent Zero profile with this routing grammar:

• @profile: route to an agent profile.
• /sdk: route to an SDK gateway.
• @profile /sdk: send profile metadata through the selected SDK gateway.
• No routing tokens: Spynel handles the request locally.

External routing contracts:

• /sdk resolves only from SPYNEL_SDK_<SDK>_URL.
• A registered @profile resolves only from SPYNEL_AGENT_<PROFILE>_URL.
• External destinations must be credential-free HTTPS URLs registered through environment variables; user text must never supply or override a destination.
• Dispatch uses shell-free curl argv execution, bounded connect/overall timeouts, terminate/kill cleanup, structured polling, progress states, and useful failure information.

Internal routing contracts:

• An unregistered @profile may select only an existing Agent Zero profile.
• Delegation uses configurable same-container loopback transport, preferably SPYNEL_AGENT_ZERO_URL=http://127.0.0.1:7860, authenticated with SPYNEL_AGENT_ZERO_API_KEY. HTTPS remains mandatory for non-loopback URLs.
• The Hugging Face entrypoint must configure Agent Zero's existing API-key verifier from SPYNEL_AGENT_ZERO_API_KEY without printing the secret.
• Delegation creates a fresh context, selects the requested profile, submits the stripped task asynchronously, polls with meaningful progression, and returns the result.
• Unknown profiles fail before context creation and are never implicitly created.

Paperclip Skill

• Ship a Spynel-native Paperclip board-manager skill targeting https://leon4gr45-paperclip-founder.hf.space by default.
• Configuration uses PAPERCLIP_BASE_URL and optional PAPERCLIP_API_TOKEN.
• The helper permits credential-free HTTPS base URLs and confined /api/* paths, bounds timeouts, avoids shell interpolation, does not leak tokens, and preserves useful 401/403/404 response behavior.
• Live validation must use read-only requests unless disposable authenticated test data is explicitly available.

Colab Lifecycle CLI

Provide a CLI that starts Agent Zero in the background, checks /api/health, and stops the process group. It must handle stale PID files, graceful shutdown, and bounded forced termination fallback.

Required Validation

• Clean-build the actual root Docker image and run it without development bind mounts or privileged flags as UID/GID 1000.
• Verify /api/health, the UI root, authenticated API access, Spynel profile and profile-scoped skill discovery, administrative profile auth/CSRF, writable state/cache paths, and clean startup logs.
• Run internal Spynel delegation, explicit unknown-profile safety, controlled immediate/async HTTPS external fixtures, read-only live Paperclip checks, disposable profile creation, and the Colab lifecycle.
• Install the real framework dependencies and run the complete pytest suite plus focused Spynel, Python compilation, shell syntax, and diff checks.
• Do not claim Hugging Face readiness unless the image builds and the resulting non-root container successfully serves /api/health.