> ## Documentation Index
> Fetch the complete documentation index at: https://agentstack.beeai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy Your Agents

> Package and deploy your agent to Agent Stack as a managed service

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 Stack installed ([Quickstart](/stable/introduction/quickstart))
* Agent wrapped with Agent Stack SDK ([Wrap Existing Agents](/stable/deploy-agents/wrap-existing-agents) or [Build New Agent](/stable/deploy-agents/building-agents))

## 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](https://github.com/i-am-bee/agentstack-starter) 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:

```bash theme={null}
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:

```dockerfile theme={null}
FROM python:3.13-alpine3.23
COPY --from=ghcr.io/astral-sh/uv:0.10.4 /uv /bin/
WORKDIR /app
ADD . .
RUN HOME=/tmp uv sync --no-cache --locked --link-mode copy
ENV PRODUCTION_MODE=true
CMD ["/app/.venv/bin/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:

```bash theme={null}
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:

```bash theme={null}
agentstack add https://github.com/i-am-bee/agentstack-starter
```

<Note>
  **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.
</Note>

## 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:

```bash theme={null}
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:

```bash theme={null}
agentstack list
```

Your agent should appear in the list with status information.

## Test Your Agent

Test via CLI:

```bash theme={null}
agentstack run my-agent "Hello!"
```

Or open the web UI:

```bash theme={null}
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:

```bash theme={null}
# 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:

<CardGroup cols={2}>
  <Card title="LLM Service" icon="rotate" href="/stable/agent-integration/llm-proxy-service">
    Change your agent's LLM at runtime and manage model connections dynamically
  </Card>

  <Card title="Agent Trajectory Visualization" icon="list" href="/stable/agent-integration/trajectory">
    Visualize your agent’s decision-making and interactions over time in the UI
  </Card>

  <Card title="Citations & Source Linking" icon="link" href="/stable/agent-integration/citations">
    Display references and link sources for transparency, directly in the UI
  </Card>

  <Card title="Structured Inputs (Forms)" icon="square-poll-horizontal" href="/stable/agent-integration/forms">
    Guide your users to provide consistent information with the form extension
  </Card>
</CardGroup>