Quickstart

Get Agent Stack up and running in minutes. Then explore running pre-built agents.

Prerequisites

• Basic terminal/command line experience
• LLM API key (OpenAI, Anthropic, Gemini, watsonx, or free via OpenRouter / Groq) or Ollama (requires a powerful computer)
• Fast internet (2–3GB download)

Installation

Linux & macOS

One-Line Install

Open the terminal and run this command to install Agent Stack:

sh -c "$(curl -LsSf https://raw.githubusercontent.com/i-am-bee/agentstack/install/install.sh)"

The installer sets up uv and the agentstack-cli on your host machine. Agent Stack uses a virtual machine (managed via a bundled Lima binary) to keep your host machine clean. The Kubernetes cluster running the Agent Stack server, agent containers, and associated storage and services live entirely inside the VM and not on your host directly.

For details on what happens under the hood, refer to the Manual Install section or read the install.sh source code.

Manual Install

1. Install uv

   Follow the installation instructions. Agent Stack uses uv to manage its own internal Python environment.

2. Linux only: Install QEMU

   On Linux, Lima requires QEMU. Install it via these (instructions).

3. Install Agent Stack

   Open a new terminal and run:

   uv python install --quiet --python-preference=only-managed --no-bin 3.13 && uv tool install --refresh --force --python-preference=only-managed --python=3.13 agentstack-cli && agentstack self install
   

   Follow the interactive prompts to finish setup and optionally start the VM.

Windows

Windows support is experimental and requires Windows 11 22H2 or later. For the best experience, we recommend Linux or macOS.

1. Install WSL

   Open PowerShell as Administrator and run:

   wsl.exe --update
   

   Follow the instructions displayed, if any, and continue by running:

   wsl.exe --install
   

   The command output may instruct you to restart your PC. Do so, and afterwards run the same command again. It may take up to two restarts to complete the installation process.

   WSL is properly set up once you reach a working Linux shell. You can verify this by running wsl.exe without arguments. Once you have a working shell, you can close it and proceed to the next step.

   Even though WSL2 is required, Agent Stack CLI can’t be installed inside WSL2. All subsequent commands should be run from Windows PowerShell.

2. Install uv

   Open PowerShell and run:

   Installation script (recommended)

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

   Winget

   winget install astral-sh.uv
   uv tool update-shell
   

   Scoop

   scoop install uv
   uv tool update-shell
   

   Chocolatey

   choco install uv
   uv tool update-shell
   

   Close and reopen your terminal after installation.

3. Configure Ollama (optional)

   If you plan to use Ollama, we recommend installing the Windows app.

   In the Ollama app settings, it’s necessary to enable “Expose Ollama to the network” in order for it to be accessible by Agent Stack. After enabling this option, you may get a firewall prompt where you need to select “Allow”.

4. Configure local agents

   Run in PowerShell:

   setx HOST 0.0.0.0
   

   Close and reopen your terminal after this.

   This will make local agents accessible over the local network, which is needed for Agent Stack to access them. When running local agents, you may encounter firewall prompts where you need to select “Allow”.

5. Install Agent Stack

   Run in PowerShell:

   uv python install --quiet --python-preference=only-managed --no-bin 3.13; uv tool install --refresh --force --python-preference=only-managed --python=3.13 agentstack-cli; agentstack self install
   

   Follow the interactive prompts to finish the installation and setup.

Usage

agentstack ui                          # Launch web interface
agentstack list                        # See what agents are available
agentstack run chat "Hi, who are you"  # Send a message to chat agent
agentstack run chat                    # Try interactive mode
agentstack info chat                   # View agent details
agentstack --help                      # See all options

Platform Management

agentstack platform start        # Start platform
agentstack model setup           # Configure LLM provider
agentstack platform stop         # Stop (keeps data)
agentstack platform delete       # Delete all data

Version & Upgrades

If you are having issues with these commands, you may be running an old version of Agent Stack. Run the one-line install script above to upgrade to the latest version.

agentstack self version          # Check version
agentstack self upgrade          # Update
agentstack self uninstall        # Remove completely