cli

<p align="center"> <picture> <source srcset="assets/stakpak-light.png" media="(prefers-color-scheme: dark)"> <img src="assets/stakpak-dark.png" width="400" /> </picture> </p> <h3 align="center">Ship your code, on autopilot.</h3> <p align="center"> An open source agent that lives on your machines 24/7, keeps your apps running, and only pings when it needs a human. All the upside of a PaaS, none of the lock-in. </p> <br /> <!-- Badges Section --> <p align="center"> <!-- Built With Ratatui --> <a href="https://ratatui.rs/"><img src="https://ratatui.rs/built-with-ratatui/badge.svg" /></a> <!-- License --> <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square" /> <!-- Release (latest GitHub tag) --> <img src="https://img.shields.io/github/v/release/stakpak/agent?style=flat-square" /> <!-- Build CI status (GitHub Actions) --> <img src="https://github.com/stakpak/agent/actions/workflows/ci.yml/badge.svg?style=flat-square" /> <!-- Downloads (GitHub releases total) --> <img src="https://img.shields.io/github/downloads/stakpak/agent/total?style=flat-square" /> <!-- Documentation --> <a href="https://stakpak.gitbook.io/docs/"><img src="https://img.shields.io/badge/Docs-Documentation-0A84FF?style=flat-square" /></a> <!-- Discord Community --> <a href="https://discord.gg/QTZjETP7GB"><img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a> :star: Help us reach more developers and grow the Stakpak community. Star this repo!  </p> ### Try Stakpak Now ```bash 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 ``` [For more installation options...](https://github.com/stakpak/agent#installation) You can't trust most AI agents with your DevOps. One mistake, and your production is toast. Stakpak is built differently: - **Secret Substitution** - The LLM works with your credentials without ever seeing them - **Warden Guardrails** - Network-level policies block destructive operations before they run - **DevOps Playbooks Baked-in** - Curated library of DevOps knowledge in Stakpak Rulebooks Generate infrastructure code, debug Kubernetes, configure CI/CD, automate deployments, without giving an LLM the keys to production. ### 🤖 Autopilot (24/7 Autonomous Runtime) Use the new lifecycle aliases for one-command setup/start/stop: ```bash stakpak up # alias for: stakpak autopilot up stakpak down # alias for: stakpak autopilot down ``` You can also use the canonical subcommands: ```bash stakpak autopilot up stakpak autopilot status stakpak autopilot logs stakpak autopilot down stakpak autopilot doctor ``` #### Autopilot prerequisites Before running autopilot on a remote VM: - Docker must be installed and accessible to the current user - 2GB+ RAM is recommended for reliable autopilot + sandbox runs - Swap is strongly recommended on small Linux hosts - Linux user services may require linger to survive logout `stakpak up` now runs preflight checks before startup, and `stakpak autopilot doctor` can be used as a deployment-readiness check before first boot: ```bash stakpak autopilot doctor stakpak up ``` See also: [cli/README.md](cli/README.md) #### Unified configuration (profiles + autopilot wiring) - `~/.stakpak/config.toml`: profile behavior (`model`, `allowed_tools`, `auto_approve`, `system_prompt`, `max_turns`, provider credentials) - `~/.stakpak/autopilot.toml`: runtime wiring (`schedules`, `channels`, notification routes, service/server settings) Use `profile = "name"` on schedules/channels and keep behavior inside profile definitions. Profiles control how the agent behaves: model, allowed tools, auto-approval, system prompt, max turns, and provider credentials. Notification routes only control where messages are delivered. Schedule and channel profiles are intentionally separate: - schedule `--profile monitoring`: behavior for runs started by that schedule - channel `--profile ops`: behavior for sessions started from inbound Slack/Telegram/Discord messages - notification `--target "#ops"`: where schedule notifications are sent; it does not choose the model or tools Notification routing uses two words everywhere: - `channel`: the transport, such as `slack`, `telegram`, or `discord` - `target`: the destination inside that transport, such as Slack `#ops` or `C1234567890` `autopilot channel add ... --target` sets the default notification route. Schedules inherit it unless you add `--notify-target` or `--notify-channel`. ```bash # 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" ``` In `~/.stakpak/autopilot.toml`, the same setup is represented as: ```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 public channel names such as `#ops` are accepted where Slack supports them. Channel IDs are most reliable for private channels, DMs, and scripts. Full setup guide: [cli/README.md](cli/README.md) ## 🔒 Security Hardened - **Mutual TLS (mTLS)** - End-to-end encrypted MCP - **Dynamic Secret Substitution** - AI can read/write/compare secrets without seeing actual values - **Secure Password Generation** - Generate cryptographically secure passwords with configurable complexity - **Privacy Mode** - Redacts sensitive data like IP addresses and AWS account IDs ## 🛠️ Built for DevOps Work - **Asynchronous Task Management** - Run background commands like port forwarding and servers with proper tracking and cancellation - **Real-time Progress Streaming** - Long-running processes (Docker builds, deployments) stream progress updates in real-time - **Infrastructure Code Indexing** - Automatic local indexing and semantic search for Terraform, Kubernetes, Dockerfile, and GitHub Actions - **Documentation Research Agent** - Built-in web search for technical documentation, cloud providers, and development frameworks - **Subagents** - Specialized research agents for code exploration and sandboxed analysis with different tool access levels (enabled with `--enable-subagents` flag) - **Bulk Message Approval** - Approve multiple tool calls at once for efficient workflow execution - **Reversible File Operations** - All file modifications are automatically backed up with recovery capabilities ## 🧠 Adaptive Intelligence - **Rule Books** - Customize agent behavior with internal standard operating procedures, playbooks, and organizational policies - **Persistent Knowledge** - Agent learns from interactions, remembers incidents, resources, and environment details to adapt to your workflow ## Installation ### All installation options (Linux, MacOs, Windows) [Check the docs](https://stakpak.gitbook.io/docs/get-started/installing-stakpak-cli) ### Homebrew (Linux & MacOS) ```bash brew tap stakpak/stakpak brew install stakpak ``` To update it you can use ```bash brew update brew upgrade stakpak ``` ### Binary Release Download the latest binary for your platform from our [GitHub Releases](https://github.com/stakpak/agent/releases). ### Docker This image includes the most popular CLI tools the agent might need for everyday DevOps tasks like docker, kubectl, aws cli, gcloud, azure cli, and more. ```bash docker pull ghcr.io/stakpak/agent:latest ``` ## Usage You can [use your own Anthropic or OpenAI API keys](#option-b-running-without-a-stakpak-api-key), [custom OpenAI compatible endpoint](#option-b-running-without-a-stakpak-api-key), or [a Stakpak API key](#option-a-running-with-a-stakpak-api-key). ### Option A: Running with a Stakpak API Key (no card required) Just run `stakpak` and follow the instructions which will create a new API key for you. ```bash stakpak ``` > Brave users may encounter issues with automatic redirects to localhost ports during the API key creation flow. If this happens to you: > > Copy your new key from the browser paste it in your terminal #### Non-interactive setup (CI/scripts) ```bash stakpak auth login --api-key $STAKPAK_API_KEY ``` #### Or set the environment variable ```bash export STAKPAK_API_KEY=<mykey> ``` #### View current account (Optional) ```bash stakpak account ``` ### Option B: Running Without a Stakpak API Key #### Non-interactive setup (CI/scripts) ```bash # 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 ``` #### Manual configuration Create `~/.stakpak/config.toml` with one of these configurations: **Option 1: Bring Your Own Keys (BYOK)** - Use your Anthropic/OpenAI API keys: ```toml [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] ``` **Option 2: Bring Your Own LLM** - Use a local OpenAI-compatible endpoint (e.g. Ollama, LM Studio): ```toml [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] ``` **Option 3: Mix Built-in and Custom Providers**: ```toml [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 applies available updates in the background during interactive startup. When an update is applied, restart any long-running Stakpak processes to pick up the new binary. Then run with your profile: ```bash stakpak --profile byok # or stakpak --profile offline # or stakpak --profile hybrid ``` ### Start Stakpak Agent TUI ```bash # Open the TUI stakpak # Resume execution from a checkpoint stakpak -c <checkpoint-id> ``` ### Start Stakpak Agent TUI with Docker ```bash 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 Modes You can use Stakpak as a secure MCP proxy or expose its security-hardened tools through an [MCP](https://modelcontextprotocol.io/) server. #### MCT Server Tools - **Local Mode (`--tool-mode local`)** - File operations and command execution only (no API key required) - **Remote Mode (`--tool-mode remote`)** - AI-powered code generation and search tools (API key required) - **Combined Mode (`--tool-mode combined`)** - Both local and remote tools (default, API key required) #### Start MCP Server ```bash # 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 ``` Additional flags for the MCP server: - `--disable-secret-redaction` – **not recommended**; prints secrets in plaintext to the console - `--privacy-mode` – redacts additional private data like IP addresses and AWS account IDs - `--enable-slack-tools` – enables experimental Slack tools #### MCP Proxy Server Stakpak also includes an MCP proxy server that can multiplex connections to multiple upstream MCP servers using a configuration file. ```bash # 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 ``` #### Configure External MCP Servers External MCP servers are configured in `mcp.toml` (or `mcp.json`) and loaded by `stakpak mcp proxy`. Config file discovery order: 1. `~/.stakpak/mcp.toml` or `~/.stakpak/mcp.json` 2. `.stakpak/mcp.toml` or `.stakpak/mcp.json` (from current directory) 3. `./mcp.toml` or `./mcp.json` Add servers via CLI: ```bash # 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 ``` Or define servers directly in `~/.stakpak/mcp.toml`: ```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 ``` Use `disabled = true` to keep a server configured without loading it. ### Agent Client Protocol (ACP) ACP is a standardized protocol that enables AI agents to integrate directly with code editors like Zed, providing seamless AI-powered development assistance. #### What ACP Offers with Stakpak - **Real-time AI Chat** - Natural language conversations with context-aware AI assistance - **Live Code Analysis** - AI can read, understand, and modify your codebase in real-time - **Tool Execution** - AI can run commands, edit files, search code, and perform development tasks - **Session Persistence** - Maintains conversation context across editor sessions - **Streaming Responses** - Real-time AI responses with live progress updates - **Agent Plans** - Visual task breakdown and progress tracking #### Installation & Setup 1. **Install Stakpak** (if not already installed) 2. **Configure Zed Editor** - Add to `~/.config/zed/settings.json`: ```json { "agent_servers": { "Stakpak": { "command": "stakpak", "args": ["acp"], "env": {} } } } ``` 3. **Start ACP Agent**: ```bash stakpak acp ``` 4. **Use in Zed** - Click Assistant (✨) → `+` → `New stakpak thread` ### Rulebook Management Manage your standard operating procedures (SOPs), playbooks, and runbooks with Stakpak Rulebooks. Rulebooks customize agent behavior and provide context-specific guidance. ```bash # 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 ``` #### Rulebook Format Rulebooks are markdown files with 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 Completion Enable tab-completion for every `stakpak` subcommand, flag, and argument. ```bash # 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' ``` Supported shells: `bash`, `elvish`, `fish`, `powershell`, `zsh`. ### Shell Mode Execute system commands explicitly from the input bar. [Check the Shell Mode docs](docs/shell_mode.md) for details on background vs foreground execution. ## Platform Testing ### Windows Comprehensive testing report for Windows CLI functionality, including installation, configuration, and integration with WSL2 and Docker. [View Windows Testing Report](platform-testing/windows-testing-report.md) --- ## ⭐ Like what we're building? If our Agent saves you time or makes your DevOps life easier, **consider giving us a star on GitHub — it really helps!** ## [](https://github.com/stakpak/agent/stargazers)