# Agent Runtime

**Repository Path**: ai-vibe-engineering/agent-runtime

## Basic Information

- **Project Name**: Agent Runtime
- **Description**: 为 Agent 提供统一的执行环境与生命周期管理
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-22
- **Last Updated**: 2026-01-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentRuntime - AI-Powered Full-Stack Development Platform

## 🚀 概述

AgentRuntime 提供一个带有 Claude Code 和 PostgreSQL 的沙盒环境 —— 一切您需要的全栈开发工具。

AgentRuntime 会自动为您设置以下项目，1 分钟内即可使用：
- Next.js 环境，配备 shadcn/ui
- 专用 PostgreSQL（预配置）
- Claude Code Router（预配置）
- 一个实时域名


### ✨ 核心特性

AgentRuntime 旨在使用 AI 为中心的方法简化整个全栈开发生命周期。通过一个高度编排的自包含开发沙箱交付其核心功能：

* **预配置的 AI 开发环境：**
    * 配置了一个完整的、可立即使用的开发环境，包含 **Next.js**、**shadcn/ui** 和 **Claude Code Router (CCR)**。
    * 通过 `ccr code` 命令提供强大的 AI 编码辅助。
    * 自动配置并注入重要的 AI 相关环境变量，让 AI 代理能够立即开始编码，无需手动设置。

* **隔离的 PostgreSQL 数据库配置：**
    * 为每个项目自动创建一个专用和隔离的 **PostgreSQL** 数据库实例，使用 **KubeBlocks**。
    * 数据库连接字符串作为环境变量 (`DATABASE_URL`) 安全注入开发环境，确保 AI 可以访问和配置持久层。

* **自动化的公共端点和域名映射：**
    * 自动分配和管理多个可访问的子域名（**HTTPS 入口带 SSL 终止**）。
    * 这些子域名配置为映射到您希望公开的特定应用程序端口（例如端口 3000、5000、8080），提供即时的外部访问以进行测试和实时开发。

* **通过 Web 终端进行自然语言交互：**
    * 通过内置的 **Web 终端 (ttyd)** 使用自然语言指令执行所有核心开发和配置任务。
    * 这提供了与 AI 工程师交互的直接、低摩擦界面，接收代码、运行命令和监控开发过程。

* **灵活的项目级配置：**
    * 支持在每个项目中独立配置 **系统提示词 (System Prompt)**、**GitLab 集成** 和 **CCR 参数**。
    * 这些配置会自动注入到 Sandbox 环境变量中（如 `SYSTEM_PROMPT`, `GITLAB_URL`），使 Agent 能感知项目特定的上下文。

* **无缝 GitHub 仓库集成：**
    * 该平台设计为易于与外部 **GitHub 仓库** 关联。
    * 通过将 AI 生成的代码连接到您首选的源代码控制工作流程，促进标准代码仓库管理、版本控制和协作。

* **自动化高可用部署：**
    * 项目可以从开发沙箱自动部署到高可用生产环境，利用底层的 **Kubernetes** 基础设施。
    * 这旨在抽象掉部署的复杂性，让 AI 管理从开发到实时应用的过渡。

## 🛠️ 技术栈

### 前端
- **框架**: Next.js 15.5.4 (App Router)
- **语言**: TypeScript
- **样式**: Tailwind CSS v4
- **UI 组件**: Shadcn/UI
- **状态管理**: React Hooks

### 后端
- **运行时**: Node.js
- **API**: Next.js API Routes
- **数据库 ORM**: Prisma
- **认证**: NextAuth v5 with GitHub OAuth

### 基础设施
- **容器编排**: Kubernetes
- **数据库**: PostgreSQL (via KubeBlocks)
- **Web 终端**: ttyd
- **容器镜像**: agent-runtime-sandbox (包含 CCR 和国内源优化的自定义镜像)

## 📦 安装

### 前置要求

- Node.js 20.x 或更高版本
- Docker（用于构建镜像）
- Kubernetes 环境：
  - **选项 A（本地推荐）**: Minikube
  - **选项 B（单节点推荐）**: K3s
- GitHub OAuth 应用凭据

### 部署（零污染集群内）

我们提供两个自动化脚本在 Kubernetes 集群内部署 AgentRuntime，保持您的主机干净。

#### 方案一：Minikube（开发）
适用于 Windows/Mac/Linux 上的本地开发。
```bash
bash deploy-minikube.sh
```

#### 方案二：K3s（Linux 单节点）
适用于 Linux 服务器（例如 Ubuntu/CentOS）。此脚本自动处理 K3s 安装、中国镜像和注册表配置。
```bash
# 必须以 root 身份运行
sudo bash deploy-k3s.sh
```

### k3s 部署步骤详解

以下是 `deploy-k3s.sh` 脚本执行的详细步骤：

1. **前置检查与安装**
   - 检查是否以 root 权限运行脚本
   - 确认 Docker 已安装
   - 如果 Helm 未安装，则自动安装

2. **安装 K3s (使用中国镜像)**
   - 从 Rancher 中国镜像源安装 K3s
   - 自动配置以加快国内下载速度

3. **配置镜像仓库**
   - 设置 Docker 镜像仓库的中国镜像（docker.1ms.run, docker.xuanyuan.me）
   - 重启 K3s 以应用配置

4. **构建和导入 Docker 镜像**
   - 构建 AgentRuntime 主应用镜像 (`agentruntime:local`)
   - 构建 Sandbox 镜像 (`agent-runtime-sandbox:latest`)
   - 将构建的镜像导入到 K3s 的 containerd 中

5. **安装 KubeBlocks**
   - 添加 KubeBlocks Helm 仓库
   - 下载并应用 KubeBlocks CRD
   - 安装 KubeBlocks 0.9.0 版本

6. **安装 PostgreSQL 数据库**
   - 使用 Helm 从 OCI 镜像安装 PostgreSQL
   - 配置用户名、密码和数据库名称

7. **部署 AgentRuntime 资源**
   - 应用 RBAC 权限配置
   - 部署 AgentRuntime 应用
   - 配置 KUBECONFIG 环境变量
   - 重启部署以应用配置

8. **初始化数据库模式**
   - 创建并运行数据库初始化 Job
   - 使用 Prisma 推送数据库模式

### GitHub OAuth 设置
部署后，配置 OAuth 凭据：
```bash
# Minikube
kubectl set env deployment/agentruntime GITHUB_CLIENT_ID="xxx" GITHUB_CLIENT_SECRET="xxx"

# K3s
k3s kubectl set env deployment/agentruntime GITHUB_CLIENT_ID="xxx" GITHUB_CLIENT_SECRET="xxx" --kubeconfig /etc/rancher/k3s/k3s.yaml
```

### 环境设置（传统主机安装）

1. 克隆仓库：
```bash
git clone https://github.com/FullstackAgent/agent-runtime.git
cd agent-runtime
```

2. 安装依赖：
```bash
pnpm install
```

3. 设置环境变量：

创建 `.env.local` 文件：
```env
# 数据库
DATABASE_URL="postgresql://user:password@localhost:5432/fullstackagent"

# NextAuth
NEXTAUTH_URL="http://localhost:3000"
NEXTAUTH_SECRET="your-nextauth-secret"
AUTH_TRUST_HOST=""

# GitHub OAuth（替换为您的实际值）
GITHUB_CLIENT_ID=""
GITHUB_CLIENT_SECRET=""


# 任务
DATABASE_LOCK_DURATION_SECONDS=""
MAX_DATABASES_PER_RECONCILE=""

SANDBOX_LOCK_DURATION_SECONDS=""
MAX_SANDBOXES_PER_RECONCILE=""

# k8s 资源
RUNTIME_IMAGE=""

# aiproxy
AIPROXY_ENDPOINT=""
ANTHROPIC_BASE_URL=""
```

7. 运行开发服务器：
```bash
pnpm run dev
```

打开 [http://localhost:3000](http://localhost:3000) 访问应用程序。

### 数据库模式

prisma/schema.prisma

## 🚢 部署

### Kubernetes 资源

该平台为每个项目创建以下 Kubernetes 资源：

1. **数据库集群** (KubeBlocks)：
   - PostgreSQL 14.8.0
   - 3Gi 存储
   - 自动生成凭据

2. **沙箱部署**：
   - 自定义 agent-runtime-sandbox 镜像
   - 集成 Claude Code Router，使用 `ccr code` 命令
   - Web 终端 (ttyd) 在端口 7681
   - CCR UI 在端口 3456
   - 应用端口：3000、5000、8080

3. **服务和入口**：
   - Pod 网络的内部服务
   - 带 SSL 终止的 HTTPS 入口（应用、终端、CCR UI）
   - CCR UI 通过 `ccr-<sandbox>.<domain>` 暴露
   - 终端的 WebSocket 支持

### 资源限制

每个沙箱的默认资源分配：
- CPU: 200m 限制，20m 请求
- 内存: 256Mi 限制，25Mi 请求
- 存储: 数据库 3Gi

## 🔧 开发

### 项目结构

```
agent-runtime/
├── app/                    # Next.js App Router 页面
│   ├── api/               # API 路由
│   ├── projects/          # 项目管理页面
│   └── layout.tsx         # 根布局
├── components/            # React 组件
│   ├── ui/               # Shadcn/UI 组件
│   └── ...               # 功能组件
├── lib/                   # 核心库
│   ├── auth.ts           # NextAuth 配置
│   ├── db.ts             # Prisma 客户端
│   ├── kubernetes.ts     # Kubernetes 服务
│   └── github.ts         # GitHub 集成
├── prisma/               # 数据库模式
├── yaml/                 # Kubernetes 模板
└── public/               # 静态资源
```

### 关键服务

#### KubernetesService (`lib/kubernetes.ts`)
- 管理所有 Kubernetes 操作
- 创建数据库和沙箱
- 处理 Pod 生命周期管理

#### 认证 (`lib/auth.ts`)
- GitHub OAuth 集成
- 会话管理
- 用户授权

#### 数据库 (`lib/db.ts`)
- Prisma ORM 配置
- 连接池

## 📚 API 文档

### 沙箱管理

#### 创建沙箱
```http
POST /api/sandbox/[projectId]
Content-Type: application/json

{
  "envVars": {
    "KEY": "value"
  }
}
```

#### 获取沙箱状态
```http
GET /api/sandbox/[projectId]
```

#### 删除沙箱
```http
DELETE /api/sandbox/[projectId]
```

### 项目管理

#### 创建项目
```http
POST /api/projects
Content-Type: application/json

{
  "name": "project-name",
  "description": "Project description"
}
```

## 🔒 安全

- **认证**: GitHub OAuth 确保只有授权用户才能访问平台
- **隔离**: 每个沙箱都在自己的 Kubernetes 命名空间中运行
- **密钥管理**: 敏感数据存储在 Kubernetes 密钥中
- **网络策略**: 沙箱相互隔离
- **资源限制**: 防止资源耗尽攻击

### 开发设置

1. Fork 仓库
2. 创建功能分支
3. 进行修改
4. 运行测试：`npm test`
5. 提交拉取请求

## 📄 许可证

该项目根据 MIT 许可证授权 - 请参阅 [LICENSE](LICENSE) 文件了解详情。

## 🙏 致谢

- [Anthropic](https://www.anthropic.com/) 提供 Claude Code
- [Fulling](https://github.com/FullstackAgent/fulling) 提供 AI 开发平台
- [ttyd](https://github.com/tsl0922/ttyd) 提供 Web 终端