Skip to main content
Once you’ve wrapped your agent with the Agent Stack server, you need to containerize it and deploy it, so that Agent Stack can run it as a managed service.

​
Prerequisites

​
Agent Deploy Process

To deploy your agent to Agent Stack, you need to create a github repository with your agent and then deploy from that repository to Agent Stack.

​
1. Create an Agent github repository

You can quickly create an agent repository by using the Agent Stack starter template. The agentstack-starter template includes everything you need:
  • Production-ready Dockerfile
  • GitHub Actions for automated builds
  • Agent Stack deployment configuration
Clone it and modify it for your agent as follows: 
git clone https://github.com/i-am-bee/agentstack-starter my-agent
cd my-agent
# Replace the example agent with your code
Alternatively, if you want to start from scratch, you can create your own github repository. You will need to include a Dockerfile with the following information: 
FROM python:3.13-slim-trixie
COPY --from=ghcr.io/astral-sh/uv:0.7.15 /uv /bin/

ENV UV_LINK_MODE=copy \
    PRODUCTION_MODE=true

ADD . /app
WORKDIR /app

RUN uv sync --no-cache --locked --link-mode copy

ENV PRODUCTION_MODE=true \
    PATH="/app/.venv/bin:$PATH" \
    HOME=/tmp

CMD ["uv", "run", "--no-sync", "server"]

​
2. Deploy your Agent to Agent Stack

To deploy from your my-agent github repo, run the following with your organization name substituted for myorg: 
agentstack add https://github.com/myorg/my-agent
This command automatically:
  1. ✓ Builds your Docker image from github using the provided Dockerfile in the github root directory
  2. ✓ Copies the image into Agent Stack’s VM
  3. ✓ Registers it as an available agent
As a specific example, to deploy the agentstack-starter example agent without modification, you can issue the following command: 
agentstack add https://github.com/i-am-bee/agentstack-starter
Why “copy into VM”? Agent Stack runs in an isolated VM (Lima on Mac/Linux, WSL on Windows). Even though Docker Desktop builds your image, Agent Stack needs it copied into its VM to run it. The add command handles this automatically.

​
Github Deploy Options

The agentstack add command supports various URL formats to specify the repository, version, and location of your agent’s code. The supported formats include:
  • Basic URL: https://github.com/myorg/myrepo
  • Git Protocol URL: git+https://github.com/myorg/myrepo
  • URL with .git suffix: https://github.com/myorg/myrepo.git
  • URL with Version Tag: https://github.com/myorg/myrepo@v1.0.0
  • URL with Branch Name: https://github.com/myorg/myrepo@my-branch
  • URL with Subfolder Path: https://github.com/myorg/myrepo#path=/path/to/agent
  • Combined Formats: https://github.com/myorg/myrepo.git@v1.0.0#path=/path/to/agent
  • Enterprise GitHub: https://github.mycompany.com/myorg/myrepo

​
Example

To deploy an agent from a specific branch and subfolder, you would run: 
agentstack add "https://github.com/my-org/my-awesome-agents@main#path=/my-agent"
This command tells Agent Stack to:
  1. Fetch the main branch of the my-awesome-agents repository.
  2. Look for the agent’s Dockerfile and source code in the /my-agent directory.
  3. Build the Docker image and register it with the platform.

​
Verify Deployment

You can check that your agent is registered by running: 
agentstack list
Your agent should appear in the list with status information.

​
Test Your Agent

Test via CLI: 
agentstack run my-agent "Hello!"
Or open the web UI: 
agentstack ui
Your agent will be available at http://127.0.0.1:8333

​
Advanced Options

​
Two-step build process

If you need more control over the build: 
# Step 1: Build and copy to Agent Stack VM
agentstack build https://github.com/myorg/myrepo

# Step 2: Register the agent
agentstack add agentstack.local/my-agent-abc123:latest

​
Next Steps

Now that your agent is deployed, enhance it with extensions:

LLM Service

Change your agent’s LLM at runtime and manage model connections dynamically

Agent Trajectory Visualization

Visualize your agent’s decision-making and interactions over time in the UI

Citations & Source Linking

Display references and link sources for transparency, directly in the UI

Structured Inputs (Forms)

Guide your users to provide consistent information with the form extension