Stakpak Agent CLI

让代码自动交付。

一款开源 Agent，全天候运行在你的机器上，让应用持续运行，仅在需要人工协助时通知你。享受 PaaS 的所有优势，无需担心供应商锁定。

:star: 帮助我们触达更多开发者，壮大 Stakpak 社区。为此仓库加星！

立即试用 Stakpak

curl -sSL https://stakpak.dev/install.sh | sh # install Stakpak
stakpak init # understand your apps and tech stack
stakpak autopilot up # start the autonomous agent, running 24/7 in the background

查看更多安装选项……

你不能把 DevOps 交给大多数 AI Agent。一个失误，就可能毁掉生产环境。 Stakpak 与众不同：

• 机密替换 - 大模型可以使用你的凭据，却永远无法看到它们
• Warden 防护措施 - 网络级策略会在破坏性操作执行前将其拦截
• 内置 DevOps 手册 - Stakpak Rulebooks 中精选的 DevOps 知识库

生成基础设施代码、调试 Kubernetes、配置 CI/CD、自动化部署，无需向大模型提供生产环境的密钥。

🤖 自动驾驶（全天候自治运行时）

使用新的生命周期别名，通过一条命令完成设置、启动或停止：

stakpak up        # alias for: stakpak autopilot up
stakpak down      # alias for: stakpak autopilot down

你也可以使用规范的子命令：

stakpak autopilot up
stakpak autopilot status
stakpak autopilot logs
stakpak autopilot down
stakpak autopilot doctor

自动驾驶的前置条件

在远程 VM 上运行自动驾驶之前：

• 必须安装 Docker，并确保当前用户可以访问
• 建议使用 2GB 以上 RAM，以确保自动驾驶与沙箱可靠运行
• 小型 Linux 主机强烈建议启用 Swap
• Linux 用户服务可能需要启用 linger，才能在注销后继续运行

现在，stakpak up 会在启动前运行预检；首次启动前，可使用 stakpak autopilot doctor 检查部署是否已准备就绪：

stakpak autopilot doctor
stakpak up

另请参阅：cli/README.md

统一配置（配置档案 + autopilot 接线）

• ~/.stakpak/config.toml：配置档案行为（model、allowed_tools、auto_approve、system_prompt、max_turns、提供商凭据）
• ~/.stakpak/autopilot.toml：运行时接线（schedules、channels、通知路由、服务/服务器设置）

在 schedules/channels 上使用 profile = "name"，并将行为配置保留在配置档案定义中。配置档案控制 Agent 的行为：模型、允许使用的工具、自动批准、系统提示词、最大轮次以及提供商凭据。通知路由只控制消息的送达位置。

Schedule 和 channel 的配置档案有意分开：

• schedule --profile monitoring：由该 schedule 启动的运行所使用的行为
• channel --profile ops：由传入的 Slack/Telegram/Discord 消息启动的会话所使用的行为
• notification --target "#ops"：schedule 通知的发送位置；它不会选择模型或工具

通知路由始终使用以下两个词：

• channel：传输方式，例如 slack、telegram 或 discord
• target：该传输方式中的目标位置，例如 Slack #ops 或 C1234567890

autopilot channel add ... --target 会设置默认通知路由。Schedules 会继承该路由，除非你添加 --notify-target 或 --notify-channel。

# default notification route: slack:#ops
stakpak autopilot channel add slack --bot-token "$SLACK_BOT_TOKEN" --app-token "$SLACK_APP_TOKEN" --profile ops --target "#ops"

# schedule runs with the monitoring profile and inherits the default route
stakpak autopilot schedule add health --cron '*/5 * * * *' --prompt 'Check health' --profile monitoring

# schedule still runs with monitoring, but notifies a different Slack target
stakpak autopilot schedule add deploy-watch --cron '*/15 * * * *' --prompt 'Watch deploys' --profile monitoring --notify-target "#deploys"

在 ~/.stakpak/autopilot.toml 中，同一配置表示如下：

[notifications]
channel = "slack"
target = "#ops"

[[schedules]]
name = "health"
cron = "*/5 * * * *"
prompt = "Check health"
profile = "monitoring"

[[schedules]]
name = "deploy-watch"
cron = "*/15 * * * *"
prompt = "Watch deploys"
profile = "monitoring"
notify_target = "#deploys"

Slack 支持的场景中可使用 Slack 公共频道名称（例如 #ops）。对于私有频道、私信和脚本，频道 ID 最可靠。

完整设置指南：cli/README.md

🔒 强化安全性

• 双向 TLS（mTLS） - 端到端加密的 MCP
• 动态密钥替换 - AI 无需查看实际值即可读取、写入和比较密钥
• 安全密码生成 - 生成具有可配置复杂度的加密安全密码
• 隐私模式 - 隐去 IP 地址和 AWS 账户 ID 等敏感数据

🛠️ 专为 DevOps 工作打造

• 异步任务管理 - 运行端口转发和服务器等后台命令，并妥善跟踪和取消
• 实时进度流 - 长时间运行的进程（Docker 构建、部署）实时流式传输进度更新
• 基础设施代码索引 - 自动对 Terraform、Kubernetes、Dockerfile 和 GitHub Actions 进行本地索引与语义搜索
• 文档研究 Agent - 内置技术文档、云服务提供商和开发框架的网页搜索
• 子 Agent - 用于代码探索和沙盒分析的专业研究 Agent，具有不同级别的工具访问权限（通过 --enable-subagents 标志启用）
• 批量消息批准 - 一次批准多个工具调用，让工作流执行更高效
• 可撤销的文件操作 - 自动备份所有文件修改，并支持恢复

🧠 自适应智能

• 规则手册 - 使用内部标准操作流程、操作手册和组织政策自定义 Agent 行为
• 持久化知识 - Agent 从交互中学习，记住事件、资源和环境详情，以适应你的工作流

安装

所有安装选项（Linux、MacOs、Windows）

查看文档

Homebrew（Linux 和 MacOS）

brew tap stakpak/stakpak
brew install stakpak

更新时可使用

brew update
brew upgrade stakpak

二进制发行版

从我们的 GitHub Releases 下载适用于你平台的最新二进制文件。

Docker

此镜像包含 Agent 执行日常 DevOps 任务可能需要的常用 CLI 工具，例如 docker、kubectl、aws cli、gcloud、azure cli 等。

docker pull ghcr.io/stakpak/agent:latest

用法

你可以使用自己的 Anthropic 或 OpenAI API 密钥、自定义 OpenAI 兼容端点，或使用 Stakpak API 密钥。

选项 A：使用 Stakpak API 密钥运行（无需银行卡）

只需运行 stakpak 并按照说明操作，即可创建新的 API 密钥。

stakpak

Brave 用户在创建 API 密钥时，自动重定向到 localhost 端口可能会遇到问题。如果你遇到这种情况：

从浏览器中复制新密钥，然后粘贴到终端中

非交互式设置（CI/脚本）

stakpak auth login --api-key $STAKPAK_API_KEY

或设置环境变量

export STAKPAK_API_KEY=<mykey>

查看当前账户（可选）

stakpak account

选项 B：不使用 Stakpak API 密钥运行

非交互式设置（CI/脚本）

# Anthropic
stakpak auth login --provider anthropic --api-key $ANTHROPIC_API_KEY

# OpenAI
stakpak auth login --provider openai --api-key $OPENAI_API_KEY

# Gemini
stakpak auth login --provider gemini --api-key $GEMINI_API_KEY

手动配置

使用以下配置之一创建 ~/.stakpak/config.toml：

选项 1：自带密钥（BYOK） — 使用你的 Anthropic/OpenAI API 密钥：

[profiles.byok]
provider = "local"

# Unified model preference field
model = "anthropic/claude-sonnet-4-5"

# Built-in providers - credentials can also be set via environment variables
# (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY)
[profiles.byok.providers.anthropic]
type = "anthropic"
api_key = "sk-ant-..."

[profiles.byok.providers.openai]
type = "openai"
api_key = "sk-..."

[profiles.byok.providers.gemini]
type = "gemini"
api_key = "..."

[settings]

选项 2：自带大模型 — 使用本地 OpenAI 兼容端点（例如 Ollama、LM Studio）：

[profiles.offline]
provider = "local"

# Custom provider models use the format: provider_key/model_name
model = "offline/qwen/qwen3-coder-30b"

# The provider key "offline" becomes the model prefix
[profiles.offline.providers.offline]
type = "custom"
api_endpoint = "http://localhost:11434/v1"
# api_key is optional for local providers

[settings]

选项 3：混合使用内置和自定义提供商：

[profiles.hybrid]
provider = "local"

# Unified model field (provider-prefixed)
model = "anthropic/claude-sonnet-4-5"

[profiles.hybrid.providers.anthropic]
type = "anthropic"
# Uses ANTHROPIC_API_KEY env var

[profiles.hybrid.providers.offline]
type = "custom"
api_endpoint = "http://localhost:11434/v1"

[settings]

Stakpak 会在交互式启动期间于后台应用可用更新。应用更新后，请重启所有长时间运行的 Stakpak 进程，以加载新的二进制文件。

然后使用你的配置文件运行：

stakpak --profile byok
# or
stakpak --profile offline
# or
stakpak --profile hybrid

启动 Stakpak Agent TUI

# Open the TUI
stakpak
# Resume execution from a checkpoint
stakpak -c <checkpoint-id>

使用 Docker 启动 Stakpak Agent TUI

docker run -it --entrypoint stakpak ghcr.io/stakpak/agent:latest
# for containerization tasks (you need to mount the Docker socket)
docker run -it \
   -v "/var/run/docker.sock":"/var/run/docker.sock" \
   -v "{your app path}":"/agent/" \
   --entrypoint stakpak ghcr.io/stakpak/agent:latest

MCP 模式

你可以将 Stakpak 用作安全的 MCP 代理，也可以通过 MCP 服务公开其经过安全加固的工具。

MCT 服务工具

• 本地模式（--tool-mode local） — 仅文件操作和命令执行（无需 API 密钥）
• 远程模式（--tool-mode remote） — AI 驱动的代码生成和搜索工具（需要 API 密钥）
• 组合模式（--tool-mode combined） — 同时使用本地和远程工具（默认，需要 API 密钥）

启动 MCP 服务

# Local tools only (no API key required, mTLS enabled by default)
stakpak mcp start --tool-mode local

# Remote tools only (AI tools optimized for DevOps)
stakpak mcp start --tool-mode remote

# Combined mode (default - all tools with full security)
stakpak mcp start

# Disable mTLS (NOT recommended for production)
stakpak mcp start --disable-mcp-mtls

MCP 服务的其他标志：

• --disable-secret-redaction — 不推荐；会以明文形式在控制台输出机密
• --privacy-mode — 对 IP 地址和 AWS 账户 ID 等其他私密数据进行脱敏
• --enable-slack-tools — 启用实验性的 Slack 工具

MCP 代理服务

Stakpak 还包含一个 MCP 代理服务，可通过配置文件复用连接，同时连接到多个上游 MCP 服务。

# Start MCP proxy with automatic config discovery
stakpak mcp proxy

# Start MCP proxy with explicit config file
stakpak mcp proxy --config-file ~/.stakpak/mcp.toml

# Disable secret redaction (NOT recommended – secrets will be printed in logs)
stakpak mcp proxy --disable-secret-redaction

# Enable privacy mode to redact IPs, account IDs, etc.
stakpak mcp proxy --privacy-mode

配置外部 MCP 服务

外部 MCP 服务在 mcp.toml（或 mcp.json）中配置，并由 stakpak mcp proxy 加载。

配置文件的查找顺序：

1. ~/.stakpak/mcp.toml 或 ~/.stakpak/mcp.json
2. .stakpak/mcp.toml 或 .stakpak/mcp.json（当前目录中的文件）
3. ./mcp.toml 或 ./mcp.json

通过命令行添加服务：

# Add a stdio MCP server
stakpak mcp add context7 --command npx --args "-y,@upstash/context7-mcp"

# Add a stdio MCP server with environment variables (repeat --env)
stakpak mcp add internal-tools --command npx --args "-y,@acme/internal-mcp" --env "MCP_API_KEY=<token>" --env "MCP_REGION=us-east-1"

# Add an HTTP MCP server
stakpak mcp add github --url https://api.githubcopilot.com/mcp --headers "Authorization=Bearer <token>"

# Inspect and manage servers
stakpak mcp list
stakpak mcp get github
stakpak mcp disable github
stakpak mcp enable github

# Start the proxy with configured external MCPs
stakpak mcp proxy

或者直接在 ~/.stakpak/mcp.toml 中定义服务：

[mcpServers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { MCP_API_KEY = "<token>", MCP_REGION = "us-east-1" }

[mcpServers.github]
url = "https://api.githubcopilot.com/mcp"
headers = { Authorization = "Bearer <token>" }

[mcpServers.optional]
command = "npx"
args = ["-y", "some-mcp-server"]
disabled = true

使用 disabled = true 可保留服务配置，但不加载它。

Agent 客户端协议（ACP）

ACP 是一种标准化协议，可让 AI Agent 直接与 Zed 等代码编辑器集成，提供无缝的 AI 驱动开发辅助。

Stakpak 中 ACP 提供的功能

• 实时 AI 聊天 — 与具备上下文感知能力的 AI 助手进行自然语言对话
• 实时代码分析 — AI 可实时读取、理解和修改你的代码库
• 工具执行 — AI 可运行命令、编辑文件、搜索代码并执行开发任务
• 会话持久化 — 在不同编辑器会话之间保留对话上下文
• 流式响应 — 实时 AI 响应并提供实时进度更新
• Agent 计划 — 可视化任务拆分和进度跟踪

安装与设置

1. 安装 Stakpak（如果尚未安装）
2. 配置 Zed Editor - 添加到 ~/.config/zed/settings.json：

{
  "agent_servers": {
    "Stakpak": {
      "command": "stakpak",
      "args": ["acp"],
      "env": {}
    }
  }
}

3. 启动 ACP Agent：

stakpak acp

4. 在 Zed 中使用 - 点击 Assistant（✨）→ + → New stakpak thread

规则手册管理

使用 Stakpak 规则手册管理标准操作流程（SOP）、操作手册和运行手册。规则手册可自定义 Agent 行为，并提供特定上下文的指导。

# List all rulebooks
stakpak rulebooks get
# or use the short alias
stakpak rb get

# Get a specific rulebook
stakpak rb get stakpak://my-org/deployment-guide.md

# Create or update a rulebook from a markdown file
stakpak rb apply my-rulebook.md

# Delete a rulebook
stakpak rb delete stakpak://my-org/old-guide.md

规则手册格式

规则手册是带有 YAML frontmatter 的 Markdown 文件：

---
uri: stakpak://my-org/deployment-guide.md
description: Standard deployment procedures for production
tags:
  - deployment
  - production
  - sop
---

# Deployment Guide

Your deployment procedures and guidelines here...

Shell 补全

为每个 stakpak 子命令、标志和参数启用 Tab 补全。

# Bash
echo 'source <(stakpak completion bash)' >> ~/.bashrc

# Elvish
echo 'eval (stakpak completion elvish | slurp)' >> ~/.elvish/rc.elv

# Fish
echo 'stakpak completion fish | source' > ~/.config/fish/completions/stakpak.fish

# Zsh
echo 'source <(stakpak completion zsh)' >> ~/.zshrc

# PowerShell
Add-Content -Path $PROFILE -Value 'stakpak completion powershell | Out-String | Invoke-Expression'

支持的 Shell：bash、elvish、fish、powershell、zsh。

Shell 模式

从输入栏显式执行系统命令。

查看 Shell 模式文档，了解后台执行与前台执行的详情。

平台测试

Windows

Windows CLI 功能的全面测试报告，包括安装、配置以及与 WSL2 和 Docker 的集成。

查看 Windows 测试报告

---

⭐ 喜欢我们正在打造的产品？

如果我们的 Agent 为你节省了时间，或让你的 DevOps 工作更轻松，
欢迎在 GitHub 上给我们点个星标——这对我们很有帮助！