How to Deploy ByteDance’s Open‑Source Coze AI Agent Platform for Personal and Enterprise Use

Release Overview

On 2025‑07‑26 ByteDance announced the open‑source release of its AI Agent development platform Coze (also called “扣子”). The release includes Coze Studio for AI Agent development and Coze Loop for operations, both licensed under Apache‑2.0, which permits unrestricted use, modification, and commercial deployment.

Architecture

Coze Studio follows a micro‑service architecture built on domain‑driven design (DDD). The backend is implemented in Go, the frontend uses React + TypeScript, and the system relies on internal high‑concurrency frameworks CloudWeGo, Hertz, and Eino.

Key layers of the backend:

API layer (/backend/api) – HTTP endpoints built with Hertz, request/response handling, middleware.

Application layer (/backend/application) – Composes domain objects and infrastructure implementations, provides service APIs.

Domain layer (/backend/domain) – Core business logic, domain entities, value objects, workflow rules.

Cross‑domain (anti‑corruption) layer (/backend/crossdomain) – Defines and implements interfaces that isolate the domain from external systems.

Infrastructure contracts (/backend/infra/contract) – Interfaces for external dependencies such as storage, cache, message queue, configuration.

Infrastructure implementations (/backend/infra/impl) – Concrete implementations of the contracts (e.g., MySQL, Redis, Milvus, RocketMQ).

Utility packages (/backend/pkg) – Dependency‑free helper functions usable by any layer.

Frontend code resides under frontend/ and implements the UI with React components and TypeScript.

Supported Model Services

Ark (火山方舟)

OpenAI

DeepSeek

Claude

Ollama

Qwen

Gemini

Installation & Environment Setup

Prepare the host: install Docker and Docker‑Compose. If image pulls are slow, create a daemon.json file with a registry‑mirrors array, e.g.

{
  "registry-mirrors": [
    "https://docker.registry.cyou",
    "https://docker-cf.registry.cyou",
    "https://dockercf.jsdelivr.fyi",
    "https://docker.jsdelivr.fyi",
    "https://dockertest.jsdelivr.fyi",
    "https://mirror.aliyuncs.com",
    "https://dockerproxy.com",
    "https://mirror.baidubce.com",
    "https://docker.m.daocloud.io",
    "https://docker.nju.edu.cn",
    "https://docker.mirrors.sjtug.sjtu.edu.cn",
    "https://docker.mirrors.ustc.edu.cn",
    "https://mirror.iscas.ac.cn",
    "https://docker.rainbond.cc"
  ]
}

Clone the source code:

git clone https://github.com/coze-dev/coze-studio.git

Configure a large‑model provider (example uses OpenAI GPT‑4o):

cd coze-studio
cp backend/conf/model/template/model_template_openai.yaml backend/conf/model/openai.yaml

Edit backend/conf/model/openai.yaml to set the fields id, meta.conn_config.api_key, and meta.conn_config.model. The file also contains comments for switching between Azure and standard OpenAI endpoints.

Start all services with Docker‑Compose (all profiles):

cd docker
cp .env.example .env
docker compose --profile "*" up -d

Optional RAG embedding variables can be added to .env:

# OpenAI embedding configuration
export OPENAI_EMBEDDING_BASE_URL=""
export OPENAI_EMBEDDING_MODEL=""
export OPENAI_EMBEDDING_API_KEY=""
export OPENAI_EMBEDDING_BY_AZURE=true
export OPENAI_EMBEDDING_API_VERSION=""
export OPENAI_EMBEDDING_DIMS=1024
export OPENAI_EMBEDDING_REQUEST_DIMS=1024

Wait for containers to start. Verify the backend by checking the log: docker logs coze-server When the log contains Container coze-server Started, the service is ready.

Open the UI at http://localhost:8888/. Register with any username/password to access the dashboard.

Containers

coze-server – backend service

coze-mysql – MySQL database

coze-redis – Redis cache

coze-milvus – vector database

coze-rocketmq-namesrv – RocketMQ name server

coze-rocketmq-broker – RocketMQ broker

coze-elasticsearch – Elasticsearch

coze-kibana – Kibana UI

coze-minio – object storage

coze-etcd – etcd key‑value store

Example Usage

After the UI is available, click “New” → “Create Agent”. In the example the agent is prompted to write a poem; the generated output demonstrates the zero‑code agent creation flow.

A workflow can be built by dragging components from the left panel. The article shows a workflow for intent classification, connecting a LLM node, a custom code node, and a decision node. The platform also provides prompt templates that can be selected when creating an agent.

Plugins are listed under the “Explore” → “Plugins” page. Plugins marked “未授权” require additional credential configuration; unmarked plugins can be invoked directly via API.

Project Structure (selected)

├── backend/                # Backend services
│   ├── api/                # HTTP handlers (Hertz)
│   ├── application/        # Application layer
│   ├── conf/               # Configuration files
│   ├── crossdomain/        # Anti‑corruption layer
│   ├── domain/             # Core business logic
│   ├── infra/              # Infrastructure contracts & impl
│   ├── pkg/                # Utility packages (no external deps)
│   └── types/              # Type definitions
├── frontend/               # React + TypeScript UI
│   ├── apps/                # Application entry points
│   ├── config/             # Build & lint configs
│   ├── infra/              # Frontend infrastructure
│   └── packages/           # Shared UI components
├── docker/                 # Docker Compose files
└── idl/                    # Interface definition files

Model Configuration Details

Each model configuration lives under backend/conf/model/. The template directory provides ready‑made YAML files for common providers. Required fields for a model entry are:

id – Integer identifier, globally unique, must be non‑zero.

meta.conn_config.api_key – API key for the model service.

meta.conn_config.model – Model identifier used by the service (e.g., gpt-4o for OpenAI).

References

Repository: https://github.com/coze-dev/coze-studio

Wiki (installation, quick start, plugin configuration, etc.): https://github.com/coze-dev/coze-studio/wiki