# Deployment Agent Guidelines & Best Practices for Hugging Face Spaces

## 1. Deployment Configuration

### Target Space
- **Profile:** `Leon4gr45`
- **Space:** `twenty`
- **Full Identifier:** `Leon4gr45/twenty`
- **Frontend Port:** `7860` (mandatory for Hugging Face Spaces)

### Deployment Method
- **Docker SDK** is used for full flexibility (containerizing Agent Zero with Python 3.12+, Flask, Socket.IO, XFCE desktop, etc.).

### HF Token
- The HF access token is provided at execution time via the environment variable `HF_TOKEN`.
- Never hardcode the token. Always read it from the environment or pass it dynamically.

### Required Files
- `Dockerfile` configuring port 7860 and image setup.
- `README.md` with Hugging Face YAML frontmatter:
  ```yaml
  ---
  title: Agent Zero
  sdk: docker
  app_port: 7860
  ---
  ```
- `.hfignore` or `.gitignore`
- `Agent.md` (this file)

---

## 2. API Exposure and Documentation

### Mandatory Endpoints
- **/health**
  - Path: `/api/health` or `/health`
  - Method: GET / POST
  - Purpose: Returns HTTP 200 readiness status for Hugging Face container health checks.
- **/api-docs**
  - Path: `/api/api-docs` or `/api/api_docs`
  - Method: GET / POST
  - Documents all exposed endpoints.

### Exposed Functional Endpoints
- `/api/message`: Send synchronous message to agent.
- `/api/api_message`: External API endpoint with `X-API-KEY` authentication.

---

## 3. Deployment & Monitoring Workflow

1. **Pre-deployment cleanse:** Clear former space files on Hugging Face before pushing the repository.
2. **Push to Space:** Sync codebase to `https://huggingface.co/spaces/Leon4gr45/twenty`.
3. **Monitor logs:**
   - Build logs (SSE): `curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/twenty/logs/build"`
   - Run logs (SSE): `curl -N -H "Authorization: Bearer <HF_TOKEN>" "https://huggingface.co/api/spaces/Leon4gr45/twenty/logs/run"`
4. **Fix & Redeploy:** Address build or runtime errors promptly and redeploy until the space transitions to running status.