> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeus.agentspro.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# Website Development & Deployment

> Zeus Website — End-to-end web development from scaffolding to deployment

## Overview

Website is Zeus's **end-to-end web development capability** within Coding Mode. The agent can initialize web projects inside a sandbox, preview them in real-time, check code quality, and deploy to a persistent URL with one click.

Core capabilities:

* **Project Initialization** — Bootstrap Next.js / Vite projects inside an existing sandbox in seconds
* **Live Preview** — View the developing website in real-time via sandbox proxy URL
* **Code Checking** — TypeScript type checking + ESLint code quality validation
* **One-Click Deploy** — Deploy to a persistent `*.style.dev` URL via Freestyle API

***

## Architecture

```mermaid theme={null}
flowchart LR
    subgraph sandbox["Sandbox"]
        init["website_init<br/>Project Init"]
        dev["Dev Server<br/>Port 3000"]
        eslint["website_eslint<br/>Code Check"]
    end

    subgraph deploy["Deployment"]
        tool["website_deploy"]
        freestyle["Freestyle API"]
        url["*.style.dev<br/>Persistent URL"]
    end

    init --> dev
    dev -->|"live preview"| preview["Iframe Preview Panel"]
    eslint -->|"diagnostics"| agent["Agent"]
    tool -->|"collect files"| freestyle
    freestyle --> url
```

### Component Overview

| Component          | Location                                         | Role                                                 |
| ------------------ | ------------------------------------------------ | ---------------------------------------------------- |
| **Website Tools**  | `ai-backend/src/utils/tools/built_in/website.py` | `website_init` / `website_deploy` / `website_eslint` |
| **SandboxManager** | `ai-backend/src/services/sandbox.py`             | Sandbox lifecycle, web project bootstrap             |
| **Deploy API**     | `ai-backend/src/api/deploy.py`                   | Freestyle / Vercel / Server deploy routes            |
| **Frontend Route** | `web/src/app/api/deploy/route.ts`                | Proxies deploy requests to AI Backend                |

***

## Website Tools

In Coding Mode, the agent has access to three Website-specific tools:

### website\_init

Initializes a web project inside the existing sandbox. **Does not create a new sandbox** — all previous files are preserved.

| Parameter   | Type   | Default  | Description                        |
| ----------- | ------ | -------- | ---------------------------------- |
| `framework` | string | `nextjs` | Framework type: `nextjs` or `vite` |

**Execution flow:**

```mermaid theme={null}
sequenceDiagram
    participant Agent as Agent
    participant SM as SandboxManager
    participant Sandbox as Sandbox
    participant Preview as Preview Panel

    Agent->>SM: website_init(nextjs)
    SM->>Sandbox: mkdir + create-next-app
    SM->>Sandbox: pnpm add lucide-react framer-motion ...
    SM->>Sandbox: pnpm dev --port 3000 (background)
    SM->>SM: poll port readiness (max 60s)
    Sandbox-->>SM: port 3000 ready
    SM->>SM: sbx.get_host(3000)
    SM-->>SM: wait for external proxy URL
    SM-->>Agent: preview_url + project_files
    SM->>Preview: SSE website_ready event
```

**What gets initialized (Next.js):**

* `create-next-app@latest` — TypeScript + Tailwind + ESLint + App Router
* Extra dependencies: `lucide-react`, `framer-motion`, `recharts`, `zustand`, `sonner`
* Background `pnpm dev --port 3000`

### website\_deploy

Deploys the current web project to Freestyle for a persistent public URL.

| Parameter  | Type   | Default     | Description                                        |
| ---------- | ------ | ----------- | -------------------------------------------------- |
| `platform` | string | `freestyle` | Deploy platform: `freestyle` (default) or `vercel` |

**Execution flow:**

```mermaid theme={null}
sequenceDiagram
    participant Agent as Agent
    participant Tool as website_deploy
    participant Sandbox as Sandbox
    participant FS as Freestyle API

    Agent->>Tool: website_deploy(freestyle)
    Tool->>Sandbox: find project files (exclude node_modules etc.)
    Sandbox-->>Tool: file list
    Tool->>Sandbox: read each file content
    Sandbox-->>Tool: {path: content} dict
    Tool->>FS: POST /web/v1/deployment
    Note over Tool,FS: source: files<br/>config: build=true, domain=zeus-xxx.style.dev
    FS-->>Tool: deploymentId + domains
    Tool-->>Agent: persistent URL
    Tool->>Tool: SSE deploy_complete event
```

**Deployment features:**

* **Persistent URL** — `https://zeus-{session_id[:8]}.style.dev`
* **Auto Build** — Freestyle auto-detects framework (Next.js / Vite) and runs build
* **Domain Reuse** — Multiple deploys in the same session update the same domain mapping
* **Zero Config** — No user-provided tokens or server credentials needed

### website\_eslint

Checks web project code quality.

| Parameter    | Type               | Default | Description                                      |
| ------------ | ------------------ | ------- | ------------------------------------------------ |
| `file_paths` | list\[str] \| null | `null`  | File paths to check (null checks entire project) |

**Checks performed:**

1. **TypeScript type checking** — `tsc --noEmit --pretty`
2. **ESLint checking** — `next lint`

Returns error count, warning count, and detailed diagnostics.

***

## Deployment System

Zeus supports three deployment targets through a unified Deploy API:

| Target        | Endpoint                 | Features                                      | User Must Provide     |
| ------------- | ------------------------ | --------------------------------------------- | --------------------- |
| **Freestyle** | `POST /deploy/freestyle` | Persistent URL, sub-second deploy, auto build | Nothing (zero config) |
| **Vercel**    | `POST /deploy/vercel`    | Production-grade hosting                      | Vercel Token          |
| **Server**    | `POST /deploy/server`    | Custom server, Docker deploy                  | SSH credentials       |

### Freestyle Deployment

Freestyle is the default deployment target, providing:

* **Sub-second deploys** — API-first design, from call to live \< 1 second
* **Auto framework detection** — Supports Next.js, Vite, Expo, and more
* **Auto SSL** — `*.style.dev` domains come with HTTPS
* **Domain mapping** — Same domain can point to different deployments (updates create a new deployment and remap the domain)

**API call example:**

```python theme={null}
async with httpx.AsyncClient() as client:
    response = await client.post(
        "https://api.freestyle.sh/web/v1/deployment",
        headers={
            "Authorization": f"Bearer {FREESTYLE_API_KEY}",
            "Content-Type": "application/json",
        },
        json={
            "source": {
                "kind": "files",
                "files": files_dict,  # {relative_path: file_content}
            },
            "config": {
                "domains": ["zeus-abc12345.style.dev"],
                "build": True,
            },
        },
    )
```

### Deployment Flow (End-to-End)

```mermaid theme={null}
flowchart TD
    trigger["User clicks deploy / Agent calls website_deploy"]
    
    trigger --> collect["Collect project files from sandbox"]
    collect --> exclude["Exclude node_modules / .next / .git / dist"]
    exclude --> dict["Build files_dict: path to content"]
    
    dict --> freestyle["Freestyle API<br/>POST /web/v1/deployment"]
    freestyle --> build["Freestyle auto-detects framework and builds"]
    build --> domain["Domain mapping<br/>zeus-xxx.style.dev to deployment"]
    domain --> url["Return persistent URL"]
    url --> notify["SSE deploy_complete event to frontend"]
```

***

## Preview URL vs Deploy URL

| Dimension   | Sandbox Preview URL                               | Freestyle Deploy URL                   |
| ----------- | ------------------------------------------------- | -------------------------------------- |
| Format      | Depends on Provider (e.g. `https://{id}.e2b.app`) | `https://zeus-{session[:8]}.style.dev` |
| Lifecycle   | While sandbox is alive (max 1 hour)               | Persistent until manually removed      |
| Purpose     | Real-time development preview                     | Sharing, showcasing, production use    |
| Updates     | HMR auto-refresh                                  | Requires redeployment                  |
| Performance | Dev mode (slower)                                 | Production build (optimized)           |

***

## Configuration

### Environment Variables

| Variable                 | Description                                 | Default                               |
| ------------------------ | ------------------------------------------- | ------------------------------------- |
| `FREESTYLE_API_KEY`      | Freestyle API key (required for deployment) | —                                     |
| `SANDBOX_PROVIDER`       | Sandbox provider type                       | `e2b`                                 |
| `SANDBOX_TIMEOUT`        | Sandbox timeout in seconds                  | `3600`                                |
| `E2B_API_KEY`            | E2B API key (required for E2B provider)     | —                                     |
| `E2B_SANDBOX_TEMPLATE`   | E2B template name                           | `zeus-nextjs`                         |
| `OPENSANDBOX_SERVER_URL` | OpenSandbox server URL                      | `http://localhost:8000`               |
| `OPENSANDBOX_IMAGE`      | OpenSandbox sandbox image                   | `opensandbox/code-interpreter:v1.0.1` |

### Getting a Freestyle API Key

1. Visit [admin.freestyle.sh](https://admin.freestyle.sh/) and sign up
2. Get your API Key from the Dashboard
3. Add to `apps/ai-backend/.env`:

```bash theme={null}
FREESTYLE_API_KEY=your_api_key_here
```

### Free Tier Limits

| Resource        | Free Limit |
| --------------- | ---------- |
| Concurrent VMs  | 10         |
| Managed Domains | 5          |
| Repositories    | 500        |
| Deploys         | 500/month  |

***

## Use Cases

| Scenario          | Tool Chain                                                               |
| ----------------- | ------------------------------------------------------------------------ |
| Rapid Prototyping | `website_init` → AI writes code → live preview → `website_deploy`        |
| Landing Page      | `website_init` → AI generates page → `website_eslint` → `website_deploy` |
| Component Demo    | `website_init` → AI writes components → share `*.style.dev` URL          |
| Iterative Dev     | Dev preview → modify code → `website_eslint` check → redeploy (same URL) |