# Develop and deploy sites with an AI Agent

AstraFlow Site Space combines UCloud Sandbox with AI Agents. You can describe your requirements in natural language and let an Agent such as Codex, Claude Code, or OpenCode generate code, install dependencies, start services, and deploy the site in the cloud.

Common use cases include:

- Dashboards, data displays, and operations panels
- Landing pages, utility pages, and other websites
- Model usage, request log, or billing dashboards powered by the AstraFlow Management API
- Lightweight interactive games such as Snake

> This page uses `<connection-key>` as a placeholder. A connection key grants access only to its corresponding site. Do not include a real connection key in a code repository, screenshot, or other public content.

## Prerequisites

Before you begin, make sure that your local machine has:

- Node.js and `npx`, used to install Agent skills
- An AI Agent that supports skills, such as Codex, Claude Code, or OpenCode

## Step 1: Create a site

Sign in to AstraFlow, open [Site Space](https://astraflow.ucloud.cn/modelverse/site-space), and click **Create Site**. Follow the on-screen instructions to configure the site name, environment variables, API Key, and access code, and then create the site.

Expand **Advanced configuration** to configure computing resources. The CPU / memory ratio supports `1:1`, `1:2`, and `1:4`. CPU defaults to 2 cores and must be an even number. Memory is calculated automatically based on the selected ratio, up to 8 GiB. This configuration cannot be changed after the site is created. The advanced configuration area also displays a database note: PostgreSQL is pre-installed, but the database is not started by default. When you need to persist data, connect the Agent and tell it to use the pre-installed database for storage.

![Configure and create a site](https://cdnv2-cache.udelivrs.com/2026/09/d71e369bfe9fb5a0f21f41001567caa1_1789033425660.png)

## Step 2: Get the remote development instructions

After the site is created, find it in the site list and click **Connect**.

![View the remote development and site connection instructions](https://cdnv2-cache.udelivrs.com/2026/08/000809b1b89e5d35cb170cad661adff0_1787192382724.png)

The page displays the connection method and connection key for the current site. You will provide this connection key to your local AI Agent in a later step.

## Step 3: Prepare a local development directory

Create a separate local development directory and enter it:

```bash
mkdir -p /path/to/site-dev
cd /path/to/site-dev
```

> Replace `/path/to/site-dev` with the directory you want to use. We recommend using a separate directory for each site so that the Agent does not accidentally read or modify another project.

## Step 4: Install the Agent skills

Run the following command in the development directory:

```bash
npx skills add ucloud/ucloud-sandbox-cli -s astraflow-api -s ucloud-sandbox-site
```

This command installs two skills:

| Skill | Purpose |
| --- | --- |
| `ucloud-sandbox-site` | Connect to Site Space, manage files, generate code, start services, and deploy the site |
| `astraflow-api` | Call the AstraFlow Management API to query models, request logs, bills, orders, and other data |

## Step 5: Connect the AI Agent to the site

Start your Agent in the current directory. For example, to start Codex, run:

```bash
codex
```

Send the following prompt to the Agent, replacing the placeholder with the connection key shown after you click **Connect**:

```text
Connect to the AstraFlow site <connection-key>
```

Following the skill instructions, the Agent checks the CLI, verifies the site identity, and tests the connection. After the Agent confirms that it is connected, you can describe what you want to build.

## Step 6: Describe your site requirements

After the connection is established, describe your requirements in natural language. For example:

```text
Build a Snake game for me.
```

For more accurate results, describe the page's purpose, target users, preferred visual style, data sources, and main interactions in your initial prompt.

The Agent generates the code, installs dependencies, builds the project, starts the service, and verifies access. Normally, you do not need to perform these steps manually. If the Agent asks for permission to overwrite files, delete content, or perform another high-risk operation, verify the affected scope before approving it.

## Manage and develop Site Space with MCP

The Site Space MCP exposes site creation, management, development, and deployment capabilities as MCP tools. It allows AI Agents to manage the full site lifecycle through natural language and is suitable for enterprise multi-site development and management.

- Currently, only `cn-wlcb` is supported.

The MCP service supports two deployment options:

- **UCloud-hosted service:** Connect directly to the remote MCP endpoint provided by UCloud without deploying the service yourself.
- **Self-hosted service:** Run the MCP service locally or on your own server with Docker.

Before you begin, prepare the site region, UCloud project ID, and UCloud API public and private keys. You can create or view API credentials in [UCloud API Key Management](https://console.ucloud.cn/uapi/apikey).

> The UCloud API private key is highly sensitive. Do not commit a real key to a code repository or include it in prompts, screenshots, or logs. We recommend using sub-account credentials whose permissions are limited to the current task.

### Option 1: Use the UCloud-hosted service

Add the following configuration to your Agent's MCP configuration file, replacing the header placeholders with your actual values:

```json
{
  "mcpServers": {
    "ucloud-sandbox": {
      "type": "http",
      "url": "https://mcp.<region>.sandbox.ucloudai.com/mcp",
      "headers": {
        "X-UCLOUD-Region": "cn-wlcb",
        "X-UCLOUD-Project-Id": "org-xxx",
        "X-UCLOUD-Public-Key": "xxx",
        "X-UCLOUD-Private-Key": "xxx"
      }
    }
  }
}
```

| Parameter | Description |
| --- | --- |
| `url` | UCloud-hosted MCP endpoint. The example uses the `cn-wlcb` region. |
| `X-UCLOUD-Region` | Site region, such as `cn-wlcb`. |
| `X-UCLOUD-Project-Id` | UCloud project ID, such as `org-xxx`. |
| `X-UCLOUD-Public-Key` | UCloud API public key. |
| `X-UCLOUD-Private-Key` | UCloud API private key. |

### Option 2: Self-host with Docker

First, set the API credentials in the current terminal:

```bash
export UCLOUD_PUBLIC_KEY='<your PublicKey>'
export UCLOUD_PRIVATE_KEY='<your PrivateKey>'
```

Then start the MCP service:

```bash
docker run --rm \
  -p 8080:8080 \
  -e UCLOUD_REGION=cn-wlcb \
  -e UCLOUD_PROJECT_ID=org-xxxxxxxx \
  -e UCLOUD_PUBLIC_KEY="$UCLOUD_PUBLIC_KEY" \
  -e UCLOUD_PRIVATE_KEY="$UCLOUD_PRIVATE_KEY" \
  uhub.service.ucloud.cn/agent-sandbox/sandbox-mcp:latest
```

Replace `UCLOUD_REGION` and `UCLOUD_PROJECT_ID` with your actual values. Docker removes the container when the command exits. The API credentials are passed through environment variables and are not stored in the example command or image.

After the service starts, configure your Agent to use the local MCP endpoint:

```json
{
  "mcpServers": {
    "ucloud-sandbox": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

If the MCP service runs on another host, replace `127.0.0.1` with an address that the Agent can access, and restrict access through a firewall or reverse proxy. Do not expose an MCP service without access controls directly to the public internet.

### Use MCP

After configuring the service, restart or reload the Agent. You can then invoke the `ucloud-sandbox` MCP service with natural-language prompts. For example:

```text
Use the ucloud-sandbox MCP service to list the sites available to the current account.
```

You can also ask the Agent to create or manage a site:

```text
Use the ucloud-sandbox MCP service to create a site for me.
```

The Agent uses the tools exposed by MCP to guide you through selecting an API Key, entering the site information, and confirming the operation. Before authorizing an irreversible operation such as deleting a site, verify the target and the affected scope.

## Build a data dashboard with the AstraFlow Management API

If the site needs to display model usage, inference request logs, billing data, or other account data, ask the Agent to call the AstraFlow Management API through the `astraflow-api` skill.

### 1. Get UCloud API credentials

Go to [UCloud API Key Management](https://console.ucloud.cn/uapi/apikey) to create or view your `PublicKey` and `PrivateKey`.

> These are account-level UCloud `PublicKey` and `PrivateKey` credentials used to sign AstraFlow Management API requests. They are not a site connection key or the Bearer API Key used for model inference.

### 2. Configure site environment variables

When creating or editing the site, add the following entries under environment variables:

| Variable | Value |
| --- | --- |
| `UCLOUD_PUBLIC_KEY` | UCloud API public key |
| `UCLOUD_PRIVATE_KEY` | UCloud API private key |

![Configure the UCloud API public and private keys for the site](https://cdnv2-cache.udelivrs.com/2026/08/fa8f08d79a7333dab9546c34ab2d9af9_1787192382716.png)

> `UCLOUD_PRIVATE_KEY` is a highly sensitive credential. Inject it only through site environment variables. Do not put it in prompts, frontend code, code repositories, or logs. The frontend must not hold or use the private key directly. The site backend should read the environment variable, calculate the request signature, and call the API.

The AstraFlow Management API also typically requires a service region (`Region`) and project ID (`ProjectId`). You can provide the actual values in your prompt or configure them as additional site environment variables. If you are unsure which values to use, ask the Agent to query the available region and project lists first. A sub-account must provide `ProjectId`.

### 3. Connect to the site and the AstraFlow API

When starting a new Agent session, you can use the following prompt:

```text
Connect to the AstraFlow site <connection-key> and use the site environment variables UCLOUD_PUBLIC_KEY and UCLOUD_PRIVATE_KEY to connect to the AstraFlow Management API. Do not output or log the credentials, or send them to the frontend.
```

After connecting, describe the data dashboard you want. For example:

```text
Call the AstraFlow Management API and build a dashboard showing today's model usage, including model names, request counts, and usage trends. Use the fields actually returned by the log or billing API, and provide clear messages when no data is available or a request fails.
```

## Custom domain management

Site Space supports two types of custom domains: independent domains and company domains. An independent domain is best for binding a complete domain to a single site. A company domain is best when you want to configure a domain suffix once and then assign access addresses to individual sites.

To use your own company domain, click **Settings** for the site in the site list, and then click **Bind Domain** in the **Custom Domain** section.

For an independent domain, the binding process has three steps:

1. **Enter a domain:** Enter the domain you want to bind. We recommend using a subdomain such as `demo.example.com`. Do not include `http://`, `https://`, or a path.
2. **Configure DNS:** Click **Generate DNS Record**. The page displays a CNAME record. Copy it to the DNS management page of your domain provider. For example, for `demo.example.com`, the host record is `demo` and the record value is `custom.cn-wlcb.sandbox.ucloudai.com`.
3. **Verify and activate:** After configuring DNS, return to the page and click **Verify Configuration**. DNS propagation can take several minutes. After verification succeeds, the site displays its custom-domain URL.

![Bind a custom domain](https://cdnv2-cache.udelivrs.com/2026/08/4e40b29bc3a3cffa752242a273f628db_1787192382736.png)

You must own the domain and have permission to manage its DNS records. AstraFlow does not purchase the domain on your behalf. The platform uses the Let's Encrypt ACME protocol to issue and automatically renew a free HTTPS certificate. This is a DV certificate and does not verify company identity. **Do not use the domain for payments, financial transactions, or other sensitive services.** Let's Encrypt applies certificate issuance rate limits, so avoid changing or repeatedly binding domains too frequently.

After verification succeeds, the access URL changes to the custom domain. The HTTPS certificate may initially show **Pending Issuance** and then change to **Enabled** after issuance completes. Click **Manage Domain** to view:

- **HTTPS certificate:** Pending issuance or active.
- **DNS status:** For example, `CNAME · Configured Correctly`.
- **Visit Site:** Open the current custom domain.

To use a different domain, click **Change Domain**, and then configure and verify DNS again. The current domain remains accessible until the new domain is successfully bound.

![Manage a bound custom domain](https://cdnv2-cache.udelivrs.com/2026/08/f0c5644a5c2dc2927c17c73862b5757d_1787192382689.png)

### Company domain management

In the site list, click **Company domains** to open **Company domain management**. This feature lets you configure a domain suffix once and then have sites use it as needed.

#### Add a company domain

Before adding a company domain, configure a company wildcard domain DNS record for the domain at your domain provider: set the record type to CNAME, the host record to `*`, and the record value to the platform domain shown on the page. After DNS takes effect, enter a suffix in **Company domain suffix** that contains no `*`, protocol, or path, such as `apps.example.com`, and click **Add domain**.

![Add a company domain](https://cdnv2-cache.udelivrs.com/2026/09/7c30f496ed5d27c5db1b3a9fd4f6ebbf_1789033425666.png)

#### View company domains

Expand **Added company domains** to view the number of domains and the list of added domains. Each domain is displayed as `*.<company-domain-suffix>`. When the status is **Added and available for sites**, you can select that suffix when you bind a domain to a site.

#### Edit a company domain

In **Added company domains**, find the target domain and click **Edit**, then change the domain suffix and click **Save**. The new suffix also cannot contain `*`, a protocol, or a path. Before you make the change, make sure that you have configured the wildcard CNAME record required on the page for the new suffix at your domain provider.

#### Delete a company domain

In **Added company domains**, find the target domain and click **Delete**, then click **Delete** again in the confirmation prompt. After you delete a company domain, new sites can no longer use it.

#### Bind a company domain to a site

In the **Custom Domain** section of a site, click **Bind Domain** and then select **Use company domain**. First select a configured company domain suffix, and then enter the access address prefix. The prefix defaults to the current sandbox ID and can be edited. After you confirm the binding, the full access address is `<prefix>.<company-domain-suffix>`. Because the wildcard DNS record is already configured in Company domain management, you do not need to configure DNS separately for this domain when binding it to the site.

![Bind a company domain to a site](https://cdnv2-cache.udelivrs.com/2026/09/147ceee512045c5013547347e1b47c7f_1789033425656.png)

### Unbind a custom domain

If you no longer want to use the custom domain, click **Unbind** under **Manage Domain**:

1. Read the notice and confirm that visitors will no longer be able to use the custom domain. The site content is not deleted, and the platform's default URL remains available.
2. Delete the corresponding DNS record at your domain provider so that the domain no longer points to AstraFlow.
3. Enter the confirmation text requested by the console, and click **Confirm Unbind**.

![Manage the custom domain and unbind it](https://cdnv2-cache.udelivrs.com/2026/08/f0c5644a5c2dc2927c17c73862b5757d_1787192382689.png)

## Access control

Click **Settings** for a site to configure its sharing method and IP restrictions under **Access Settings**. Click **Save Changes** for the new settings to take effect.

### Sharing methods

| Sharing method | Access rule |
| --- | --- |
| Internal sharing | Only people who have both the site link and access code can visit the site. The access code must contain 6 to 12 letters or numbers. |
| Public sharing | Anyone with the site link can visit it directly, and search engines can index the site. You must bind a custom domain before enabling public sharing. |

### IP restrictions

| Restriction | Access rule |
| --- | --- |
| No IP restriction | Allow requests from any IP address. |
| Custom allowlist | Allow access only from IP addresses on the list. |
| Custom blocklist | Reject access from IP addresses on the list. |

Allowlist and blocklist entries support individual IPv4 addresses, IP address ranges, and CIDR blocks. Enter one item per line. For example:

```text
192.168.1.1
192.168.1.10-192.168.1.100
192.168.1.0/24
```

![Configure sharing methods and IP restrictions](https://cdnv2-cache.udelivrs.com/2026/08/8b09ef624876706e66cad3fcdc74ffae_1787192382699.png)

## Access a deployed site

After deployment, the Agent verifies the service within the site and returns the actual access URL. Open the URL in a browser to visit the site.

After a successful deployment, the site status in the AstraFlow console changes to **Online**. You can also open the site directly from the console.

![The site status is Online](https://cdnv2-cache.udelivrs.com/2026/08/6d7e14e3fc5050dceca88755fed30e5b_1787192382708.png)

> If the Agent returns a URL but the page does not open, ask it to continue checking the service process, port 80, listening address, and service logs. Do not consider deployment complete until the Agent confirms that the site is accessible from within the site environment.