Skip to content
Klutch.sh Docs

Deploying an Agenta App

Introduction

Agenta is an open-source platform for building, evaluating, and deploying LLM-powered applications. It provides a web UI and API for managing prompts, workflows, and model configurations, along with tools for experimentation, A/B testing, and monitoring generative AI behavior.

Deploying Agenta on Klutch.sh with a Dockerfile gives you a self-hosted control plane for your AI workflows, running on infrastructure you manage. This guide walks through creating a Docker-based Agenta deployment, configuring persistent storage, pushing your project to GitHub, and deploying it through the Klutch.sh dashboard at klutch.sh/app, plus sample code for calling Agenta-hosted endpoints.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub account (GitHub is the only supported git source)
  • Docker installed locally for testing (optional but recommended)
  • Basic familiarity with Python or Node.js and HTTP APIs
  • Optional: external services such as a database or vector store if your Agenta workflows depend on them

Project Setup for Agenta

1. Create a Project Directory

Create and initialize a repository for your Agenta deployment:

Terminal window
mkdir agenta-klutch
cd agenta-klutch
git init

2. Plan Your Agenta Data Directory

Agenta needs to persist configuration, experiments, and potentially metadata for your LLM applications. For this guide, you’ll configure Agenta to store state under /var/agenta/data inside the container. On Klutch.sh, this directory will be mapped to a persistent volume, so your settings survive redeployments.

Creating a Dockerfile for Agenta

Klutch.sh automatically detects a Dockerfile in your repository’s root directory and uses it for deployment. There’s no separate toggle for Docker in the Klutch.sh UI, and you don’t specify a custom Dockerfile path—the platform discovers and builds from Dockerfile when it exists.

The example below shows a Python-based Agenta-style service exposing a web UI and API on port 3000.

Create a file named Dockerfile in the project root:

FROM python:3.12-slim


ENV DEBIAN_FRONTEND=noninteractive


WORKDIR /app


# Install system dependencies as needed (git, build tools, etc.)
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
      curl \
      ca-certificates \
      build-essential && \
    rm -rf /var/lib/apt/lists/*


# Copy dependency file (if you use requirements.txt)
COPY requirements.txt ./requirements.txt
RUN pip install --no-cache-dir -r requirements.txt


# Copy application code
COPY . .


# Configure Agenta data directory
ENV AGENTA_DATA_DIR=/var/agenta/data
RUN mkdir -p /var/agenta/data


# Expose HTTP port for Agenta UI and API
ENV PORT=3000
EXPOSE 3000


# Start the Agenta-style server (FastAPI/Starlette/Uvicorn example)
CMD ["uvicorn", "agenta_app:app", "--host", "0.0.0.0", "--port", "3000"]

Adjust the CMD, module name (agenta_app:app), and dependencies to match your actual Agenta setup or fork. The key point is that your container listens on port 3000 and stores persistent state under /var/agenta/data.

Example Agenta-Style FastAPI App

If you don’t already have an Agenta application, you can start with a simple FastAPI-based API that represents a minimal Agenta-like service.

Create a requirements.txt in your project root:

fastapi==0.115.0
uvicorn[standard]==0.30.0
python-dotenv==1.0.1

Then create agenta_app.py:

from fastapi import FastAPI
from pydantic import BaseModel
import os
import json
from pathlib import Path


app = FastAPI(title="Agenta Demo", version="1.0.0")


DATA_DIR = Path(os.getenv("AGENTA_DATA_DIR", "/var/agenta/data"))
DATA_DIR.mkdir(parents=True, exist_ok=True)
PROMPTS_FILE = DATA_DIR / "prompts.json"




class PromptConfig(BaseModel):
    name: str
    description: str | None = None
    template: str




def load_prompts() -> list[dict]:
    if not PROMPTS_FILE.exists():
        return []
    return json.loads(PROMPTS_FILE.read_text(encoding="utf-8"))




def save_prompts(prompts: list[dict]) -> None:
    PROMPTS_FILE.write_text(json.dumps(prompts, indent=2), encoding="utf-8")




@app.get("/api/prompts")
def list_prompts():
    return load_prompts()




@app.post("/api/prompts")
def create_prompt(prompt: PromptConfig):
    prompts = load_prompts()
    prompts.append(prompt.model_dict())
    save_prompts(prompts)
    return prompt




@app.post("/api/evaluate")
def evaluate_prompt(prompt: PromptConfig, input_text: str):
    # Placeholder: in a real Agenta deployment you'd call an LLM here
    generated = prompt.template.replace("{{input}}", input_text)
    return {
        "prompt_name": prompt.name,
        "input": input_text,
        "output": generated,
    }

This simple service stores prompt configurations in a JSON file under AGENTA_DATA_DIR and includes a stubbed evaluation endpoint you can later replace with real LLM calls.

Optional: Local Testing with Docker

Before deploying to Klutch.sh, test your Agenta container locally:

Terminal window
docker build -t agenta-klutch .


docker run -d \
  --name agenta-test \
  -p 3000:3000 \
  -e AGENTA_DATA_DIR=/var/agenta/data \
  -v "$(pwd)/agenta-data:/var/agenta/data" \
  agenta-klutch

Then open http://localhost:3000/docs to view the automatically generated FastAPI docs and test endpoints.

For more complex local setups involving additional services (databases, vector stores, or background workers), you can use Docker Compose on your local machine. Docker Compose is only for local development; Klutch.sh does not deploy via Docker Compose.

Pushing Your Agenta Project to GitHub

Once your Agenta code and Dockerfile are ready, push them to a GitHub repository:

Terminal window
git add .
git commit -m "Initial Agenta Docker setup for Klutch.sh"
git branch -M main
git remote add origin https://github.com/your-username/agenta-klutch.git
git push -u origin main

Klutch.sh will use this repository as the source for building and deploying your Agenta app.

Creating an Agenta App on Klutch.sh

With your repository on GitHub, you can now create the Agenta app in the Klutch.sh dashboard.

Connect the GitHub Repository

  1. Sign in at klutch.sh/app.
  2. Navigate to Create Project and create a project (for example, agenta-platform).
  3. Go to Create App and:
    • Choose GitHub as the git source.
    • Select your Agenta repository and the branch to deploy (for example, main).

Klutch.sh will automatically detect the Dockerfile in the repository root and use it for the build.

Traffic Type and Internal Port

  • Traffic Type: Select HTTP (Agenta exposes an HTTP API and often a web UI).
  • Internal Port: Set to 3000, matching the PORT and EXPOSE 3000 configuration in your Dockerfile.

This ensures HTTP traffic from your app’s URL is routed correctly to the Agenta server inside the container.

Environment Variables on Klutch.sh

In the app’s Environment section, configure the runtime environment:

  • PORT – set to 3000 (or keep the Dockerfile default if you do not override it).
  • AGENTA_DATA_DIR – set to /var/agenta/data so the service writes state into your mounted volume.
  • Any provider-specific variables you need (for example, OPENAI_API_KEY, ANTHROPIC_API_KEY, or other API keys used in your LLM workflows).

If you choose to deploy without a Dockerfile and rely on Nixpacks, you can customize commands via environment variables:

  • BUILD_COMMAND – override the default build command that Nixpacks runs.
  • START_COMMAND – override the default start command for Nixpacks-generated images.

Set these environment variables in the Klutch.sh dashboard when you need to customize Nixpacks behavior for non-Docker deployments.

Attaching Persistent Volumes

Agenta needs persistent storage for prompt configurations, experiment results, and other metadata. Without persistent volumes, you risk losing configuration whenever you redeploy.

In the app’s Storage/Volumes section, add:

  • Agenta Data Volume
    • Mount path: /var/agenta/data
    • Size: Choose based on your usage—for example, 5 GiB or 10 GiB to start, scaling up as your experiments and logs grow.

This volume ensures that files stored in /var/agenta/data (e.g., prompts.json and other stateful assets) are preserved across restarts and deployments.

Sample Client Code: Calling an Agenta Endpoint

Once your Agenta app is deployed, it will be available at a URL like:

https://example-app.klutch.sh

You can interact with it from any HTTP client. Below are examples for calling the /api/evaluate endpoint defined earlier.

JavaScript (Node or Browser) Example

async function evaluatePrompt() {
  const payload = {
    prompt: {
      name: 'support-reply',
      description: 'Basic canned reply example',
      template: 'Agent reply: {{input}}',
    },
    input_text: 'Thank you for reaching out! How can we help you today?',
  };


  const response = await fetch('https://example-app.klutch.sh/api/evaluate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });


  if (!response.ok) {
    throw new Error(`Agenta evaluation failed: ${response.status}`);
  }


  const result = await response.json();
  console.log('Agenta evaluation result:', result);
}


evaluatePrompt().catch((err) => {
  console.error('Error calling Agenta endpoint', err);
});

Python Example

import requests


BASE_URL = "https://example-app.klutch.sh"


payload = {
    "prompt": {
        "name": "travel-itinerary",
        "description": "Outline a short weekend itinerary",
        "template": "Plan: {{input}}",
    },
    "input_text": "A 3-day weekend trip to the mountains.",
}


response = requests.post(f"{BASE_URL}/api/evaluate", json=payload)


if response.ok:
    data = response.json()
    print("Agenta evaluation:", data)
else:
    print("Error:", response.status_code, response.text)

You can integrate these calls into your backend services or frontends to route requests through your Agenta instance on Klutch.sh.

Verifying Your Deployment

After the deployment completes:

  1. Visit your app URL:

    https://example-app.klutch.sh/docs

  2. Confirm that:

    • The API documentation (if using FastAPI) loads correctly.
    • You can create and list prompts using the /api/prompts endpoint.
    • Calls to /api/evaluate return responses as expected.
    • Prompts and results persist after restarting the app, confirming that the /var/agenta/data volume is working.

If you see errors, review the logs in the Klutch.sh dashboard and double-check environment variables, internal port settings, and volume mount paths.

Troubleshooting

API or UI Not Accessible

  • Ensure the app’s Traffic Type is set to HTTP.
  • Verify the internal port is 3000 and matches the EXPOSE 3000 directive in the Dockerfile.
  • Check deployment logs for Python, Uvicorn, or framework-level errors.

State Not Persisting

  • Confirm that a persistent volume is attached with mount path /var/agenta/data.
  • Ensure AGENTA_DATA_DIR is set to /var/agenta/data so the service writes into the mounted directory.
  • Verify that the volume size is sufficient and that the container has permissions to write to the directory.

Build or Dependency Failures

  • Make sure requirements.txt includes all required packages for your Agenta app.
  • Confirm that file paths in the Dockerfile (requirements.txt, agenta_app.py) match your repository structure.
  • Review build logs in Klutch.sh for missing dependencies or syntax errors.
  • Learn more about deployments in Deployments.
  • Understand traffic types, ports, and routing in Networking.
  • Explore persistent storage options in Volumes.
  • Browse the rest of the platform docs at Klutch.sh Documentation.
  • For Agenta-specific features and best practices, refer to the official project repository and documentation for the version you’re using.

Deploying an Agenta app on Klutch.sh with a Dockerfile gives you a powerful, customizable AI orchestration layer that you fully control. With a clean Dockerfile, properly configured internal port, and a persistent volume for /var/agenta/data, you can build and operate a robust Agenta deployment on Klutch.sh and integrate it into your production LLM workflows with confidence.