Skip to content

2. Quickstart

Jump to bottom
kidkidkid edited this page Aug 25, 2025 · 15 revisions

This document demonstrates how to install and deploy the latest version of Coze Loop.

Method 1: Deploy with Docker (Docker Compose)

Before you begin

Please ensure that your software and hardware environment meets the following requirements:

Projects Note
Hardware It is recommended to use a hardware configuration with at least 2 cores and 4 GB of RAM.
Go * Go 1.24.0 or later is installed.
Configure GOPATH, and add ${GOPATH}/bin to the PATH environment variable to ensure that installed binary tools can be found and executed.
Docker Before you begin, install Docker, Docker Compose, and start the Docker service. For detailed instructions, refer to the Docker documentation:

* macOS: It is recommended to install using Docker Desktop. Refer to the Docker Desktop For Mac installation guide.
* Linux: Refer to the Docker installation guide and the Docker Compose installation guide.
* Windows: It is recommended to install using Docker Desktop. Refer to the Docker Desktop For Windows installation guide.
Model Online model services such as OpenAI or Volcengine Ark have been enabled. For the current list of supported model services, refer to Model configuration.

Install Coze Loop

Step 1: Obtain the source code

Run the following command to obtain the latest version of the Coze Loop source code.

# clone the code  
git clone https://github.com/coze-dev/coze-loop.git

cd coze-loop

Step 2: Configure a model

Before officially installing the Coze Loop open-source version, you need to prepare the models you wish to use; otherwise, when you access the Coze Loop open-source version, you will not be able to select models to start prompt debugging or evaluation. Here, the OpenAI and Volcengine Ark models are used as examples to demonstrate the procedure for configuring model files. You can quickly configure models to install and test the open-source version of Coze Loop. For Llama and other models, you can refer to the Model Configuration documentation to complete the configuration file.

  1. Edit the file release/deployment/docker-compose/conf/model_config.yaml and modify the api_key and model fields. The following content shows how to configure the Volcengine Ark Cici model and the OpenAI model in the Coze Loop open-source version. Overwrite the original file with the following content, then modify the api_key and model, replacing them with your OpenAI and Volcengine Ark model configuration parameters.

The release/deployment/docker-compose/conf/model_config_example/ directory also provides example configurations for mainstream models supported by Coze Loop, which can be used as a reference.

models:
  - id: 1
    name: "doubao"
    frame: "eino"
    protocol: "ark"
    protocol_config:
      base_url: ""    # Default is https://ark.cn-beijing.volces.com/api/v3/; If using Byteplus ModelArk，use https://ark.ap-southeast.bytepluses.com/api/v3/
      api_key: "***"  # Ark model API Key. For users in China, refer to the Volcengine Ark documentation at https://www.volcengine.com/docs/82379/1541594; for users outside China, refer to the BytePlus ModelArk documentation at https://docs.byteplus.com/en/docs/ModelArk/1361424?utm_source=github&utm_medium=readme&utm_campaign=coze_open_source
      model: "***"    # Ark model Endpoint ID. For users in China, refer to the Volcengine Ark documentation at https://www.volcengine.com/docs/82379/1099522; for users outside China, refer to the BytePlus ModelArk documentation at https://docs.byteplus.com/en/docs/ModelArk/model_id?utm_source=github&utm_medium=readme&utm_campaign=coze_open_sourceendpoint
    param_config:
      param_schemas:
        - name: "temperature"
          label: "生成随机性"
          desc: "调高温度会使得模型的输出更多样性和创新性，反之，降低温度会使输出内容更加遵循指令要求但减少多样性。建议不要与 “Top p” 同时调整。"
          type: "float"
          min: "0"
          max: "1.0"
          default_val: "0.7"
        - name: "max_tokens"
          label: "最大回复长度"
          desc: "控制模型输出的 Tokens 长度上限。通常 100 Tokens 约等于 150 个中文汉字。"
          type: "int"
          min: "1"
          max: "4096"
          default_val: "2048"
        - name: "top_p"
          label: "Top P"
          desc: "生成时选取累计概率达 top_p 的最小 token 集合，集合外 token 被排除，平衡多样性与合理性。"
          type: "float" #
          min: "0.001"
          max: "1.0"
          default_val: "0.7"
  - id: 2
    name: "openapi"
    frame: "eino"
    protocol: "openai"
    protocol_config:
      api_key: "***"  # OpenAI API Key
      model: "***"    # OpenAI 模型 ID
    param_config:
      param_schemas:
        - name: "temperature"
          label: "生成随机性"
          desc: "调高温度会使得模型的输出更多样性和创新性，反之，降低温度会使输出内容更加遵循指令要求但减少多样性。建议不要与 “Top p” 同时调整。"
          type: "float"
          min: "0"
          max: "1.0"
          default_val: "0.7"
        - name: "max_tokens"
          label: "最大回复长度"
          desc: "控制模型输出的 Tokens 长度上限。通常 100 Tokens 约等于 150 个中文汉字。"
          type: "int"
          min: "1"
          max: "4096"
          default_val: "2048"
        - name: "top_p"
          label: "Top P"
          desc: "生成时选取累计概率达 top_p 的最小 token 集合，集合外 token 被排除，平衡多样性与合理性。"
          type: "float" #
          min: "0.001"
          max: "1.0"
          default_val: "0.7"
  1. Save the file.

Step 3: Start the service

Run the following commands to quickly deploy the open-source version of Coze Loop using Docker Compose.

# Start the service (default: development mode)
# Run in the coze-loop/ directory
make compose-up

During deployment, you will see the following log messages, indicating that Coze Loop has started successfully.

coze-loop-app              | 2025/08/11 09:01:00.501154 engine.go:681: [Debug] HERTZ: Method=GET    absolutePath=/ping                     --> handlerName=github.com/coze-dev/coze-loop/backend/api/handler.Ping (num=2 handlers)
coze-loop-app              | 2025/08/11 09:01:00.506913 engine.go:409: [Info] HERTZ: Using network library=netpoll
coze-loop-app              | 2025/08/11 09:01:00.514110 transport.go:150: [Info] HERTZ: HTTP server listening on address=[::]:8888
coze-loop-app              | ************************************************************************
coze-loop-app              | ****************************** Completed! ******************************
coze-loop-app              | ************************************************************************

Step 4: Access the Coze Loop open-source version

After starting the service, open a browser and visit http://localhost:8082 to access Coze Loop open-source edition. At this point, you have successfully deployed the Coze Loop open-source version and can now experience the various features and services of Coze Loop. Image

Method 2: Kubernetes deployment (Helm Chart)

Before you begin

Ensure that the software and hardware environment of the physical nodes in your Kubernetes cluster meets the following requirements:

Projects Note
Hardware It is recommended to use physical nodes with at least 2 CPU cores and 4 GB of RAM.
Model Online model services such as OpenAI and Volcengine Ark have been enabled. For a list of currently supported model services, refer to Model configuration.
Tools Kubectl and Helm have been installed.

Deploy Coze Loop using Kubernetes

Step 1: Obtain a Helm Chart package

Run the following command to obtain the latest version of the Coze Loop source code.

Retrieve Helm Chart packages
helm pull oci://docker.io/cozedev/coze-loop --version 1.0.0-helm
Extract files
tar -zxvf coze-loop-1.0.0-helm.tgz
# Delete compressed files
rm -f coze-loop-1.0.0-helm.tgz
Enter the Helm Chart directory
cd coze-loop

Step 2: Configure a model

  1. Edit the release/deployment/helm-chart/umbrella/conf/model_config.yaml file and modify the api_key and model fields. The following content demonstrates how to configure the Volcengine Ark Cici model and the OpenAI model in the open-source version of Coze Loop. Overwrite the original file with the following content, then modify the api_key and model parameters, replacing them with your own OpenAI and Volcengine Ark model configuration values.

The conf/model_config_example/ directory also provides example configurations for mainstream models supported by Coze Loop, which can be used for reference.

models:
  - id: 1
    name: "doubao"
    frame: "eino"
    protocol: "ark"
    protocol_config:
      base_url: ""    # Default is https://ark.cn-beijing.volces.com/api/v3/; If using Byteplus ModelArk，use https://ark.ap-southeast.bytepluses.com/api/v3/
      api_key: "***"  # Ark model API Key. For users in China, refer to the Volcengine Ark documentation at https://www.volcengine.com/docs/82379/1541594; for users outside China, refer to the BytePlus ModelArk documentation at https://docs.byteplus.com/en/docs/ModelArk/1361424?utm_source=github&utm_medium=readme&utm_campaign=coze_open_source
      model: "***"    # Ark model Endpoint ID. For users in China, refer to the Volcengine Ark documentation at https://www.volcengine.com/docs/82379/1099522; for users outside China, refer to the BytePlus ModelArk documentation at https://docs.byteplus.com/en/docs/ModelArk/model_id?utm_source=github&utm_medium=readme&utm_campaign=coze_open_sourceendpoint
    param_config:
      param_schemas:
        - name: "temperature"
          label: "生成随机性"
          desc: "调高温度会使得模型的输出更多样性和创新性，反之，降低温度会使输出内容更加遵循指令要求但减少多样性。建议不要与 “Top p” 同时调整。"
          type: "float"
          min: "0"
          max: "1.0"
          default_val: "0.7"
        - name: "max_tokens"
          label: "最大回复长度"
          desc: "控制模型输出的 Tokens 长度上限。通常 100 Tokens 约等于 150 个中文汉字。"
          type: "int"
          min: "1"
          max: "4096"
          default_val: "2048"
        - name: "top_p"
          label: "Top P"
          desc: "生成时选取累计概率达 top_p 的最小 token 集合，集合外 token 被排除，平衡多样性与合理性。"
          type: "float" #
          min: "0.001"
          max: "1.0"
          default_val: "0.7"
  - id: 2
    name: "openapi"
    frame: "eino"
    protocol: "openai"
    protocol_config:
      api_key: "***"  # OpenAI API Key
      model: "***"    # OpenAI 模型 ID
    param_config:
      param_schemas:
        - name: "temperature"
          label: "生成随机性"
          desc: "调高温度会使得模型的输出更多样性和创新性，反之，降低温度会使输出内容更加遵循指令要求但减少多样性。建议不要与 “Top p” 同时调整。"
          type: "float"
          min: "0"
          max: "1.0"
          default_val: "0.7"
        - name: "max_tokens"
          label: "最大回复长度"
          desc: "控制模型输出的 Tokens 长度上限。通常 100 Tokens 约等于 150 个中文汉字。"
          type: "int"
          min: "1"
          max: "4096"
          default_val: "2048"
        - name: "top_p"
          label: "Top P"
          desc: "生成时选取累计概率达 top_p 的最小 token 集合，集合外 token 被排除，平衡多样性与合理性。"
          type: "float" #
          min: "0.001"
          max: "1.0"
          default_val: "0.7"
  1. Save the file.

Step 3: Configure Ingress

Ingress is used to expose services to external networks. You need to configure the templates/ingress.yaml file in the project directory according to the actual situation of the cluster, modify parameters such as ingressClassName yourself, and configure elements including class, instance, host, and IP allocation.

Step 4: Deploy and start the service

Run the following commands to quickly deploy the open-source version of Coze Loop using Helm.

Execute in the coze-loop/ directory
make helm-up
# After the service deployment is complete, check the status of cluster pods
make helm-pod
Check the service startup logs; if both app and nginx are running normally, deployment is successful
make helm-logf-app
make helm-logf-nginx

During the deployment process, you will see the following log messages, indicating that Coze Loop has started successfully.

coze-loop-app              | 2025/08/11 09:01:00.501154 engine.go:681: [Debug] HERTZ: Method=GET    absolutePath=/ping                     --> handlerName=github.com/coze-dev/coze-loop/backend/api/handler.Ping (num=2 handlers)
coze-loop-app              | 2025/08/11 09:01:00.506913 engine.go:409: [Info] HERTZ: Using network library=netpoll
coze-loop-app              | 2025/08/11 09:01:00.514110 transport.go:150: [Info] HERTZ: HTTP server listening on address=[::]:8888
coze-loop-app              | ************************************************************************
coze-loop-app              | ****************************** Completed! ******************************
coze-loop-app              | ************************************************************************

Step 5: Access the Coze Loop open-source version

At this point, you have successfully deployed the Coze Loop open-source version and can now experience all the features and services of Coze Loop. After starting the service, use the domain name and URL assigned to you by your cluster to access the Coze Loop open-source edition via your browser. Image

Deep customization of Kubernetes deployment logic

The source code for the Helm Chart deployment logic is located in the https://github.com/coze-dev/coze-loop.git repository, under the release/deployment/helm-chart directory. You are free to customize the code logic.

  1. Customize code logic in the release/deployment/helm-chart directory.
  2. In the root directory coze-loop/, run the command make helm-chart-deps to update the local chart package.
  3. Run the command make helm-up to deploy the customized code logic to the default cluster in kubectl for validation. You can run the make helm-help command to view the usage of all packaged Helm commands.

A local Minikube Kubernetes deployment

You can also use the Minikube tool to quickly set up a single-node Kubernetes cluster locally and deploy Coze Loop. This method allows you to verify the deployment process locally, making it easier to develop, test, and experience Coze Loop locally.

Before you begin

Projects Note
Hardware It is recommended to use at least 4 cores and 8 GB of RAM. If you need to run many other tasks simultaneously, it is recommended to use a system with at least 8 CPU cores and 16 GB of RAM.
Docker Install Docker and Docker Compose in advance, and start the Docker service. For detailed instructions, refer to the Docker documentation:
* macOS: It is recommended to use Docker Desktop for installation. Refer to the Docker Desktop For Mac installation guide.
* Linux: Refer to the Docker installation guide and the Docker Compose installation guide.
* Windows: It is recommended to install using Docker Desktop. Refer to the Docker Desktop For Windows installation guide.
Docker resource configuration It is recommended to use 4 cores and 8 GB of RAM or higher.
If you are running many other tasks simultaneously, it is recommended to use at least an 8-core CPU and 16 GB of RAM. For configuration instructions, refer to the tutorial.
Minikube Minikube has been installed. It is a tool for simulating a Kubernetes cluster on a PC.
Minikube resource configuration It is recommended to use 4 cores and 8 GB of RAM or higher.
If you run many other tasks concurrently, it is recommended to use hardware with at least 8 CPU cores and 16 GB of memory. You can execute the following commands to allocate resources to Minikube:
Shell <br> minikube config set cpus 8 <br> minikube config set memory 16384 <br>

Deploy Coze Loop using Minikube

  1. Run the following commands in your local project to start Minikube and enable the tunnel.

    Configure host
sudo vim /etc/hosts
# Add the following content
127.0.0.1 open.coze-loop.minikube

Run the following commands in the coze-loop/ directory of the Helm chart package to start the Minikube cluster
make minikube-start 

Enable the Minikube tunnel so that it can be accessed via localhost
Run in the coze-loop/ directory of the helm chart package. This operation will block the current terminal until the tunnel is actively closed.
make minikube-tunnel

  2. Run the following commands to deploy and start Coze Loop.

    Run in the coze-loop/ directory
make helm-up-exp-minikube-bundle
After the service deployment is complete, check the status of the cluster pods
make helm-pod
Check service startup logs to confirm successful deployment
make helm-logf-app
make helm-logf-nginx

  3. Access Coze Loop. At this point, you have successfully deployed the Coze Loop open-source version. After starting the service, use a browser to visit http://open.coze-loop.minikube to experience various features and services of Coze Loop. Among them, the domain name open.coze-loop.minikube is the default domain name. You can also modify the values.yaml file in the project root directory to change it to a business-related domain name.

Model validation service

After successfully deploying the Coze Loop open-source version, you can refer to the following steps to verify whether Coze Loop can successfully call the model service.

  1. Register an account by following the prompts on the page, and log in to Coze Loop. Caution: If deploying on a public network, restrict the list of users who can register.
  2. Click Playground in the left navigation bar.

Image

  1. In the model configuration area, view the model list and confirm that the available models are exactly the same as those configured in Step 2.

Image

  1. Select any model, open a chat in the preview and debugging area on the right, and check whether the model responds normally.

Image

  1. Click Trace in the left navigation bar to view trace information reported during debugging.

Image

If all of the above steps can be completed successfully and there are no errors on the page, it means that the open-source version of Coze Loop has been successfully deployed and can invoke model services successfully.

Experience the Coze Loop open source version

After successfully installing and accessing the open-source version of Coze Loop, you can experience the basic features of the open-source version of Coze Loop.

  • Prompt development and debugging: Coze Loop provides a complete prompt development workflow; refer to the documentation to develop and debug prompts on the open-source platform.
  • Evaluation: The evaluation functionality of Coze Loop provides standard evaluation data management, an automated assessment engine, and comprehensive experiment result statistics. Refer to the documentation to initiate an evaluation experiment.
  • Trace reporting and queries: Coze Loop supports automatic reporting of prompt debugging sessions created on the platform, integration with mainstream AI frameworks, and one-click Trace reporting. Refer to the documentation for instructions on reporting traces.

FAQ

Docker Compose & Helm Chart image retrieval failed

Solution 1: Manually retrieve images and redeploy

Retrieving an image using the docker pull command has a higher success rate compared to using the docker compose up command.

docker pull cozedev/coze-loop:1.0.0 & \
docker pull nginx:1.28.0 & \
docker pull redis:8.2.0 & \
docker pull mysql:9.4.0 & \
docker pull clickhouse/clickhouse-server:latest & \
docker pull minio/minio:RELEASE.2025-06-13T11-33-47Z & \
docker pull apache/rocketmq:5.3.3 & \
docker pull moby/buildkit:v0.23.0 & \
docker pull golang:1.24-alpine & \
docker pull node:20.13.1-alpine & \
docker pull alpine:3.22.0 & \
wait
Run in the coze-loop/ directory
make compose-up

Solution 2: Configure a mirror source proxy or an accelerator

If solution 1 does not resolve your issue, you can try solution 2: configure a mirror source proxy or an acceleration service, then redeploy. If some image repositories do not synchronize the corresponding version tags in a timely manner, it will result in Coze Loop being unable to pull the latest image. If you encounter similar issues, please try switching to a different mirror source.

  1. Configure the image registry mirror in /etc/docker/daemon.json.

    {
   "registry-mirrors": [
      "***",
      "***",
      "***"
   ]
}

  2. Restart Docker Engine.

    # Linux
sudo systemctl daemon-reload && sudo systemctl restart docker

# MacOS/Windows在 Docker Desktop 的 Resources 中变更完后，点击 Apply & Restart 按钮重启

A port conflict error occurs during deployment

In the current version, the Docker Compose network as a whole only exposes three ports externally. All other services can only communicate with each other within the Docker Compose network and are not exposed externally. If a port conflict error occurs during deployment, you can identify the conflicting service based on the error message, manually edit the release/deployment/docker-compose/.env file to assign an available port to the affected service, and then restart the corresponding service. The methods for modifying the ports for each service are as follows:

Services Default port Modification methods
coze-loop-nginx The default port for external access to the Coze Loop website is 8082.
1. In the release/deployment/docker-compose/.env file, modify the configuration variable COZE_LOOP_NGINX_PORT and change it to another unused port.
2. Run the make compose-restart-nginx command to restart the Nginx service.
coze-loop-app The default port for Open API is 8888.
1. In the release/deployment/docker-compose/.env file, change the configuration variable COZE_LOOP_APP_OPENAPI_PORT to another available port.
2. Run the command make compose-restart-app to restart the app service.
The debug port for single-step debugging defaults to 40000. 1. In the release/deployment/docker-compose/.env file, change the configuration variable COZE_LOOP_APP_DEBUG_PORT to another unused port.
2. Run the command make compose-restart-app to restart the app service.

Home

Clone this wiki locally