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

​
Prerequisites

​
Containerize Your Agent

The agentstack-starter template includes everything you need:
  • Production-ready Dockerfile
  • GitHub Actions for automated builds
  • Agent Stack deployment configuration
Clone it and modify for your agent: 
git clone https://github.com/i-am-bee/agentstack-starter my-agent
cd my-agent
# Replace the example agent with your code
You can push your repository to GitHub and tag it to leverage the automated GitHub workflow to build the image directly in GitHub, without running Docker locally.

​
Option 2: Create Your Own Dockerfile

If you’re starting from scratch, create a Dockerfile: 
FROM python:3.12-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy agent code
COPY . .

# Configure server
ENV HOST=0.0.0.0
ENV PORT=10000
EXPOSE 10000

# Run agent server
CMD ["python", "server.py"]
Port Configuration: The SDK defaults to port 10000. Make sure your Dockerfile EXPOSE and ENV PORT match, and that your server.run() call uses the same port via environment variable.

​
Deploy to Agent Stack

​
One-Command Deployment

From your agent directory, run: 
agentstack add .
This automatically:
  1. ✓ Builds your Docker image locally
  2. ✓ Copies the image into Agent Stack’s VM
  3. ✓ Registers it as an available agent
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.
You can also deploy an agent directly from a GitHub repository. 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.

​
Example with --dockerfile

agentstack add --dockerfile /my-agent/path/to/Dockerfile "https://github.com/my-org/my-awesome-agents@main#path=/my-agent"

​
Verify Deployment

Check that your agent is registered: 
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

If you need more control over the build:
# Step 1: Build and copy to Agent Stack VM
agentstack build . --import

# Step 2: Register the agent
agentstack add agentstack.local/my-agent-abc123:latest
The --import flag (enabled by default) copies your Docker image from Docker Desktop into Agent Stack’s VM.
Test your Dockerfile builds without deploying:
agentstack build . --no-import
This creates the image in Docker Desktop but doesn’t copy it to Agent Stack. Useful for testing or if you plan to push to a registry instead.
# Custom image tag
agentstack build . --tag my-agent:v1.0.0 --import

# Build for multiple architectures
agentstack build . --multi-platform --import

# Use custom Dockerfile location
agentstack build . --dockerfile=./deploy/Containerfile --import

​
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