Skip to main content

Quick Start: Self-Hosting Agenta

This guide explains how to set up Agenta on your local machine using Docker Compose, either using the default port 80 or a custom port.

tip

Looking to deploy on Kubernetes instead? See the Deploy on Kubernetes guide for Helm chart installation.

Prerequisites​

  • Docker installed on your machine (Download Docker)

  • Permission to reach the Docker daemon socket, /var/run/docker.sock. It is owned by root and the docker group. Run the commands below as root, prefix them with sudo, or add your user to the docker group:

    sudo usermod -aG docker $USER

    Then open a new login shell so the group applies. A member of the docker group can start a container that mounts the host filesystem, which makes the group equivalent to root on that machine.

Quick Setup (Port 80)​

  1. Clone Agenta:
git clone --depth 1 --filter=blob:none --sparse https://github.com/Agenta-AI/agenta
cd agenta
git sparse-checkout set hosting/docker-compose api/oss/databases/postgres api/ee/databases/postgres
  1. Copy configuration and, optionally, edit it:
cp hosting/docker-compose/oss/env.oss.gh.example hosting/docker-compose/oss/.env.oss.gh
  1. Start Agenta:
docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d
  1. Access Agenta at http://localhost.
Sign-ups are open by default

Anyone who can reach your instance can sign up and gets their own organization. If people you do not fully trust can reach it, see Restrict Sign-ups and Organization Creation.

Using a Custom Port​

To use a different port (e.g., 90):

Change the following variables in the environment file /hosting/docker-compose/oss/.env.oss.gh then restart the services:

TRAEFIK_PORT=90
AGENTA_SERVICES_URL=http://localhost:90/services
AGENTA_API_URL=http://localhost:90/api
AGENTA_WEB_URL=http://localhost:90

Upgrading to the Latest Version of Agenta​

Updating your local Agenta installation to the latest version, requires pulling the latest version with --pull always and running migrations if any.

  1. Pull the latest version:
docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh  --profile with-web --profile with-traefik up -d --pull always
  1. Run migrations if needed:
docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core agenta-oss-gh-api-1 alembic -c alembic.ini upgrade head

Consult the upgrading guide for more details.

Troubleshooting​

If Agenta doesn't start properly, check these common issues:

  1. Port conflicts: Verify if another application is using your chosen port.
  2. Container status: Run docker ps to check if all Agenta containers are running
  3. Logs: Examine container logs with: 
    docker logs agenta-oss-gh-web
    docker logs agenta-oss-gh-api
  4. SDK connectivity issues: If you're using the Agenta SDK from outside Docker to connect to your localhost Agenta instance and experiencing connection failures, ensure the DOCKER_NETWORK_MODE environment variable is unset (this is the default behavior).
  5. Docker network layout: The Docker networks are defined in the compose files. See hosting/docker-compose/oss/docker-compose.gh.yml (OSS) or hosting/docker-compose/ee/docker-compose.dev.yml (EE) for the network names and service attachments.
  6. Lack of memory provided to docker: If you are experiencing the web container restarting and dying unexpectedly, the most likely cause is that you are running out of memory. You may need to increase the memory allocated to docker (desktop).
  7. The runner container does not start and Docker reports error gathering device information while adding custom device "/dev/fuse": the host has no FUSE device. See Run agents locally.
info

To set up a development environment with features like hot-reloading, refer to our Development Guide.

Where do agents run?

Agents run in a separate runner service. To understand the runner topology and where agent code executes, see How agents run.

Need help? Either: