deployment.md

OpenOperator Hugging Face Space Deployment & Acceptance Contract

1. System Invariants

OpenOperator enforces a strict separation between immutable application code and persistent user/runtime state:

green GitHub SHA
       ==
HF snapshot
       ==
/git/agent-zero
       ==
/a0 application code

while:

/a0/usr

remains persistent, mutable user state containing settings, goals, workdirs, logs, and usr/.env.

---

2. Exact Application Code Synchronization

During container startup (docker/run/fs/ins/copy_A0.sh), exact application code is synchronized:

rsync -a --delete --no-owner --no-group --exclude='/usr' /git/agent-zero/ /a0/

• Application code in /a0 is kept perfectly in sync with the build snapshot /git/agent-zero.
• Obsolete application files removed from newer commits are pruned from /a0.
• The user directory /a0/usr (and all subdirectories /a0/usr/*) is strictly excluded from deletion or overwrite.

---

3. Deployment Secret Mapping & Bridge

Hugging Face Space Secrets arrive as process environment variables. Upon application startup, helpers/runtime_secrets.py normalizes and bridges these secrets into /a0/usr/.env with strict 0600 permissions.

Secret Mapping Table

Space Secret Variable	Canonical Runtime Variable(s)	Purpose
SPYNEL_AGENT_ZERO_API_KEY	SPYNEL_AGENT_ZERO_API_KEY	Agent Zero internal API authentication (X-API-KEY)
HUGGINGFACE_TOKEN	HF_TOKEN	Hugging Face CLI (hf) & remote Hugging Face MCP authorization
GITHUB_PAT	GH_TOKEN, GITHUB_TOKEN	GitHub repository inspection, PR management & Git operations

Model Provider Secrets

Environment Variable	Canonical Runtime Setting	Purpose
COMPATIBLE_URL	chat.api_base	OpenAI-compatible LLM endpoint URL
COMPATIBLE_MODEL	chat.name	OpenAI-compatible model name
BLABLADOR_API_KEY	API_KEY_OTHER	Model API key stored securely outside presets in .env

Critical Credential Distinctions

• HF_TOKEN (Hugging Face token) is NOT the LLM model API key.
• HF_TOKEN is NOT the Spynel API key (SPYNEL_AGENT_ZERO_API_KEY).
• GITHUB_PAT is NOT the Hugging Face token.

Secret Hygiene & Rotation Rules

1. Space process environment variables override stale persisted values in usr/.env upon container restart.
2. Secret values are NEVER printed, logged, returned in /health, or exposed via settings APIs.
3. Diagnostic endpoints report boolean presence status only ({"spynel_api_key": true, "hf_token": true, "github_token": true}).

---

4. Deployed Source SHA Identity

Every deployment snapshot includes /openoperator-build.json containing:

{
  "source_sha": "<full-github-commit-sha>"
}

The application exposes this identity via:

• GET /health -> {"status": "ok", "sha": "<full-github-commit-sha>"}

Acceptance smoke testing compares GET /health's reported SHA against the target green commit SHA.

---

5. Hugging Face MCP Client Integration

OpenOperator connects to Hugging Face's official remote MCP server as a client:

• Endpoint: https://huggingface.co/mcp
• Transport: Streamable HTTP (type: "streamable-http")
• Header Configuration: "Authorization": "Bearer ${ENV:HF_TOKEN}"

Safe Secret Interpolation

• helpers/mcp_handler.py substitutes ${ENV:VAR_NAME} placeholders in memory at request time.
• Placeholders match ^[A-Z_][A-Z0-9_]*$ strictly. Arbitrary code execution or eval is prohibited.
• Serialized settings.json, UI outputs, and logs preserve the literal placeholder ${ENV:HF_TOKEN} and never log expanded secret tokens.
• No local MCP daemon or additional listening port is executed (only public port 7860).

---

6. Modern hf CLI Tooling

The modern hf CLI (huggingface_hub[cli]) is installed at image build time in /opt/venv-a0/bin/hf:

• Available on system PATH.
• Authenticates seamlessly via HF_TOKEN in environment.
• Commands utilized by OpenOperator:
  • hf auth whoami
  • hf spaces info OWNER/SPACE
  • hf spaces logs OWNER/SPACE
  • hf spaces logs --build OWNER/SPACE
  • hf spaces secrets list OWNER/SPACE

---

7. Specialist Profile Organization

OpenOperator includes 19 native specialist profiles under /a0/agents/:

1. developer - Software architecture & master orchestration
2. hacker - Security research & parallel hypothesis testing
3. spynel - External API routing & task dispatch
4. reviewer - Read-only code & spec review
5. tester - Test suite execution & evidence verification
6. tiny-coder - Bounded 1-3 file patch implementation
7. debugger - Failure localization & falsifiable hypotheses
8. integrator - API contracts & protocol verification
9. frontend-qa - UI contrast & browser behavior verification
10. evals - Benchmark evaluation & performance metrics
11. shipper - Release preparation & production approval gate
12. launch - Launch storyboard & release notes
13. performance - Concurrency profiling & latency analysis
14. security - Surface security auditing & credential checks
15. refactorer - Structural changes & technical debt reduction
16. maintainer - Dependency updates & environment maintenance
17. data-engineer - Data pipeline & schema engineering
18. docs - Verified technical documentation
19. repository-manager - Git, GitHub PR, and Hugging Face Space management

repository-manager Policy

• Default Mode: Read-only inspection (git status, git log, git diff, hf spaces info, hf spaces logs, hf spaces secrets list).
• Mutation Policy: Pushes, branch deletions, PR merges, Space variable changes, and deployments require explicit authorization.

---

8. Deployment & Acceptance Procedure

Deployment Execution

To deploy a verified green GitHub commit SHA to Hugging Face Space Leon4gr45/openoperator:

export HF_TOKEN="<write-scoped-hf-token>"
python3 scripts/deploy_hf_space.py --space Leon4gr45/openoperator --sha <green-commit-sha>

Live Acceptance Verification

Once the Space rebuilds, run the acceptance smoke test:

export SPYNEL_AGENT_ZERO_API_KEY="<deployment-secret>"
export EXPECTED_OPENOPERATOR_SHA="<green-commit-sha>"
python3 scripts/smoke_hf_openoperator.py --mode full --expected-sha <green-commit-sha>

Required Live Verification Checklist:

• Health status == PASS (GET /health)
• Deployed SHA matches expected GitHub commit SHA
• Specialist Profiles == PASS (all 19 profiles discoverable)
• Required Skills == PASS (all 23 skills present)
• Spynel Routing == PASS (@repository-manager, @reviewer, etc.)
• Goal Delegation == PASS (/goal execution with specialist profile)
• Unknown Profile Safety == PASS (404 on unknown profiles)
• API Token Masking == PASS (mcp_server_token == "************")