QCA Quickstart — Qoder Cloud Agents Quickstart

A full-stack starter template for building AI agent applications with the Qoder Cloud Agents API. Clone, configure your API key, and run — your own multi-agent chat app in minutes.

What This Project Does

This is a reference implementation that demonstrates how to integrate the Qoder Cloud Agents (QCA) API into a full-stack web application. The server acts as a secure proxy between the React frontend and the QCA API, keeping your API key server-side while providing a rich conversational UI.

Key capabilities:

Multi-agent selection with detail inspection (model, system prompt, skills, tools, MCP servers)
SSE streaming responses with smooth typewriter animation
Markdown message rendering with syntax-highlighted code blocks
Tool call and thinking process visualization
File upload (drag-and-drop, up to 10 MB) with automatic session mounting
Agent-generated file download (PDF, PNG, DOCX, XLSX, etc.)
Session management (create, switch, archive, history replay)
Multi-user data isolation via trust-based login

Tech Stack

Frontend (client/): React 19, TypeScript 6, Vite 8, Tailwind CSS 4, Zustand 5, react-markdown 10, Vitest 4

Backend (server/): Express 5, TypeScript 5, tsx 4, dotenv 16

Monorepo: npm workspaces + concurrently

Architecture

┌─────────────┐     /api proxy      ┌─────────────┐    HTTPS     ┌──────────────────┐
│  React SPA  │ ──────────────────► │ Express API  │ ──────────► │  Qoder Cloud API │
│  :5173      │ ◄────────────────── │  :3001       │ ◄────────── │  api.qoder.com   │
└─────────────┘   Vite dev proxy    └─────────────┘  API Key auth └──────────────────┘

The frontend never touches the API key. All requests flow through the Express server, which injects the Authorization: Bearer <QODER_API_KEY> header. The SSE stream is piped through the server from the upstream API.

User identity is tracked via an X-Username header (trust-based, set by the frontend). This is a demo pattern — add real authentication for production use.

Quick Start

Prerequisites

Node.js >= 18.x (recommended: 22.x LTS)
npm >= 8.x
A Qoder API Key — get one at qoder.com → Settings → API Tokens

Step 1: Clone the repository

git clone https://github.com/kunlun322/qca-quickstart.git
cd qca-quickstart

Step 2: Configure environment variables

cp .env.example .env

Edit .env and replace the placeholder with your actual API key:

QODER_API_KEY=pt-your-api-key-here

This is the only environment variable you need. The API base URL (https://api.qoder.com/api/v1/cloud) is built in.

Step 3: Install dependencies

npm install

This installs dependencies for both client/ and server/ via npm workspaces.

Step 4: Start the application

npm run dev

This starts both services concurrently:

Service	URL	Description
Frontend	http://localhost:5173	React app with Vite HMR
Backend	http://localhost:3001	Express API server

Open http://localhost:5173 in your browser, enter any username to log in, select an agent, and start chatting.

The Vite dev server proxies all /api requests to the backend — no CORS configuration needed during development.

Start services individually (optional)

npm run dev:client    # Frontend only (Vite)
npm run dev:server    # Backend only (Express with tsx --watch)

Production Build

# Build frontend
cd client && npm run build    # Output: client/dist/

# Build backend
cd server && npm run build    # Output: server/dist/

# Run production server
cd server && npm start        # node dist/index.js

For production, serve the client/dist/ directory with any static file server (nginx, Caddy, etc.) and configure it to proxy /api requests to the Express backend.

Project Structure

qca-quickstart/
├── client/                    # Frontend React application
│   ├── src/
│   │   ├── pages/             # Page components (LoginPage, ConsolePage)
│   │   ├── components/        # UI components (ChatArea, ChatInput, MessageBubble, etc.)
│   │   ├── hooks/             # Custom hooks (useChat, useSession)
│   │   ├── stores/            # Zustand stores (authStore, chatStore, sessionStore)
│   │   ├── services/          # API client (api.ts), SSE client (sse.ts)
│   │   ├── types/             # TypeScript type definitions
│   │   └── utils/             # Utility functions
│   ├── public/                # Static assets
│   ├── vite.config.ts         # Vite config (API proxy to :3001)
│   └── package.json
├── server/                    # Backend Express service
│   ├── src/
│   │   ├── routes/            # API route handlers
│   │   │   ├── auth.ts        # POST /api/auth/login
│   │   │   ├── agents.ts      # POST /api/agents/list, /get, /api/skills/list
│   │   │   ├── sessions.ts    # POST /api/sessions/create, list, get, cancel, archive
│   │   │   ├── events.ts      # POST /api/sessions/:id/events, events/list, GET stream
│   │   │   ├── files.ts       # POST /api/files/upload, list, get, download-url
│   │   │   └── environments.ts # POST /api/environments/list
│   │   └── utils/             # Helpers
│   │       ├── env.ts         # dotenv loader + QODER_API_BASE constant
│   │       ├── qoderClient.ts # HTTP client for Qoder Cloud API
│   │       ├── extractApiKey.ts # Username extraction from X-Username header
│   │       └── userSessionStore.ts # File-based user-session store
│   └── package.json
├── .env.example               # Environment variable template
├── package.json               # Root monorepo config (npm workspaces + scripts)
└── LICENSE                    # Apache 2.0

API Reference

All endpoints are prefixed with /api and served by the Express backend on port 3001.

Method	Endpoint	Description
POST	`/api/auth/login`	Trust-based login (any username)
POST	`/api/agents/list`	List available agents
POST	`/api/agents/get`	Get agent details
POST	`/api/skills/list`	List agent skills
POST	`/api/environments/list`	List available environments
POST	`/api/sessions/create`	Create a new chat session
POST	`/api/sessions/list`	List sessions (per-user)
POST	`/api/sessions/get`	Get session details
POST	`/api/sessions/{id}/events`	Send a message event
POST	`/api/sessions/{id}/events/list`	Get event history
GET	`/api/sessions/{id}/events/stream`	SSE stream (real-time)
POST	`/api/sessions/{id}/resources`	Mount files to session
POST	`/api/files/upload`	Upload a file
POST	`/api/files/list`	List uploaded files
POST	`/api/files/download-url`	Get file download URL
GET	`/api/health`	Health check

SSE Event Types

The /api/sessions/{id}/events/stream endpoint emits these event types:

user.message · session.status_running · session.status_idle · session.error · agent.thinking · agent.message · agent.tool_use · agent.tool_result · agent.artifact_delivered

Troubleshooting

"QODER_API_KEY environment variable is required" → Ensure .env exists in the project root with a valid QODER_API_KEY=pt-... value.

Port already in use (EADDRINUSE) → Check if ports 5173 or 3001 are occupied: netstat -ano | findstr :3001 (Windows) or lsof -i :3001 (macOS/Linux). Kill the process or change the port via the PORT environment variable (backend) or client/vite.config.ts (frontend).

SSE connection fails / no response from agent → Verify: (1) both frontend and backend are running (npm run dev), (2) your API key is valid (check at qoder.com), (3) network can reach https://api.qoder.com.

No agents visible after login → Your Qoder account may not have any agents configured. Create agents at qoder.com.

File upload fails → Maximum file size is 10 MB. Check browser console for network errors and ensure the backend is running.

Configuration

Setting	Default	How to change
Frontend port	5173	Edit `client/vite.config.ts`
Backend port	3001	Set `PORT` environment variable
API base URL	`https://api.qoder.com/api/v1/cloud`	Edit `server/src/utils/env.ts`
API key	—	Edit `.env` file

License

Apache License 2.0

中文说明

基于 Qoder Cloud Agents API 的全栈快速启动模板。克隆、配置 API Key、运行——几分钟拥有自己的多 Agent 对话应用。

项目简介

这是一个参考实现，演示如何将 Qoder Cloud Agents (QCA) API 集成到全栈 Web 应用中。服务端作为 React 前端与 QCA API 之间的安全代理，API Key 仅存于服务端，前端永不接触密钥。

核心能力： 多 Agent 选择与详情查看（模型、系统提示词、技能、工具、MCP 服务器）、SSE 流式对话（打字机动画）、Markdown 消息渲染（代码高亮）、工具调用与思考过程展示、文件上传下载（拖拽上传，最大 10 MB）、会话管理（创建/切换/归档/历史回放）、多用户数据隔离。

技术栈

前端（client/）：React 19 + TypeScript 6 + Vite 8 + Tailwind CSS 4 + Zustand 5 + react-markdown 10 + Vitest 4

后端（server/）：Express 5 + TypeScript 5 + tsx 4 + dotenv 16

Monorepo：npm workspaces + concurrently

架构说明

┌─────────────┐     /api 代理       ┌─────────────┐    HTTPS     ┌──────────────────┐
│  React SPA  │ ──────────────────► │ Express API  │ ──────────► │  Qoder Cloud API │
│  :5173      │ ◄────────────────── │  :3001       │ ◄────────── │  api.qoder.com   │
└─────────────┘   Vite dev proxy    └─────────────┘  API Key 认证 └──────────────────┘

前端不接触 API Key。所有请求经过 Express 服务端，由服务端注入 Authorization: Bearer <QODER_API_KEY>。SSE 流由服务端从上游 API 管道透传。

用户身份通过 X-Username 请求头追踪（信任模式，前端设置）。这是演示模式——生产环境请添加真实认证。

快速开始

前置条件

Node.js >= 18.x（推荐 22.x LTS）
npm >= 8.x
一个有效的 Qoder API Key — 在 qoder.com → 设置 → API 令牌页面获取

第 1 步：克隆仓库

git clone https://github.com/kunlun322/qca-quickstart.git
cd qca-quickstart

第 2 步：配置环境变量

cp .env.example .env

编辑 .env，将占位符替换为你的实际 API Key：

QODER_API_KEY=pt-your-api-key-here

这是唯一需要配置的环境变量。API Base URL（https://api.qoder.com/api/v1/cloud）已内置。

第 3 步：安装依赖

npm install

通过 npm workspaces 同时安装 client/ 和 server/ 的依赖。

第 4 步：启动应用

npm run dev

同时启动两个服务：

服务	地址	说明
前端	http://localhost:5173	React 应用（Vite HMR）
后端	http://localhost:3001	Express API 服务

浏览器打开 http://localhost:5173，输入任意用户名登录，选择一个 Agent，开始对话。

Vite 开发服务器将所有 /api 请求代理到后端，开发阶段无需处理跨域。

分别启动（可选）

npm run dev:client    # 仅启动前端（Vite）
npm run dev:server    # 仅启动后端（Express + tsx --watch）

生产构建

# 构建前端
cd client && npm run build    # 产物：client/dist/

# 构建后端
cd server && npm run build    # 产物：server/dist/

# 运行生产后端
cd server && npm start        # node dist/index.js

生产环境下，用任意静态文件服务器（nginx、Caddy 等）托管 client/dist/，并配置 /api 反向代理到 Express 后端。

API 路由参考

所有端点以 /api 为前缀，由 Express 后端（端口 3001）提供服务。

方法	路径	说明
POST	`/api/auth/login`	信任登录（任意用户名）
POST	`/api/agents/list`	获取 Agent 列表
POST	`/api/agents/get`	获取 Agent 详情
POST	`/api/skills/list`	获取技能列表
POST	`/api/environments/list`	获取环境列表
POST	`/api/sessions/create`	创建新会话
POST	`/api/sessions/list`	获取会话列表（用户隔离）
POST	`/api/sessions/get`	获取会话详情
POST	`/api/sessions/{id}/events`	发送消息事件
POST	`/api/sessions/{id}/events/list`	获取事件历史
GET	`/api/sessions/{id}/events/stream`	SSE 流式订阅（实时）
POST	`/api/sessions/{id}/resources`	挂载文件到会话
POST	`/api/files/upload`	上传文件
POST	`/api/files/list`	获取文件列表
POST	`/api/files/download-url`	获取文件下载 URL
GET	`/api/health`	健康检查

SSE 事件类型

/api/sessions/{id}/events/stream 端点发射以下事件类型：

user.message · session.status_running · session.status_idle · session.error · agent.thinking · agent.message · agent.tool_use · agent.tool_result · agent.artifact_delivered

故障排查

"QODER_API_KEY environment variable is required" → 确保项目根目录存在 .env 文件，且包含有效的 QODER_API_KEY=pt-...。

端口被占用（EADDRINUSE） → 检查 5173 或 3001 端口：Windows netstat -ano | findstr :3001，macOS/Linux lsof -i :3001。关闭占用进程或通过 PORT 环境变量（后端）/ client/vite.config.ts（前端）修改端口。

SSE 连接失败 / Agent 无响应 → 确认：(1) 前后端均已启动（npm run dev），(2) API Key 有效（在 qoder.com 检查），(3) 网络可访问 https://api.qoder.com。

登录后看不到 Agent → 当前 Qoder 账号可能未配置 Agent，请在 qoder.com 创建。

文件上传失败 → 单文件最大 10 MB。检查浏览器控制台网络错误，确认后端运行正常。

配置项

配置	默认值	修改方式
前端端口	5173	编辑 `client/vite.config.ts`
后端端口	3001	设置 `PORT` 环境变量
API 地址	`https://api.qoder.com/api/v1/cloud`	编辑 `server/src/utils/env.ts`
API Key	—	编辑 `.env` 文件

许可证