System administrators and developers can self-host AgentGPT on private infrastructure using Docker and Docker Compose in just a few minutes. By deploying the application locally or within an internal virtual private cloud (VPC), organizations retain complete ownership over agent objectives, intermediate reasoning traces, prompt history, and database records, eliminating the risk of leaking internal operational context to multi-tenant public web applications.
This guide outlines the system architecture, prerequisites, automated and manual containerized setup procedures, security hardening recommendations, and operational trade-offs for running private autonomous agent workflows.
Architecture Overview
AgentGPT coordinates recursive autonomous agent execution through a modular, containerized multi-tier stack:
- Frontend (
frontend): A Next.js 13 web application built with TypeScript, Tailwind CSS, and HeadlessUI. It serves the browser-based dashboard on port3000, enabling users to define agent identities, specify top-level goals, observe sub-task creation in real time, and export task artifacts. - Backend Engine (
platform): A Python FastAPI service operating on port8000. It coordinates LLM toolchains via LangChain, orchestrating task generation, priority queue scheduling, execution, and evaluation cycles. - Database Layer: Managed through Prisma ORM on the web layer and SQLModel on the backend, persisting agent configurations, sessions, and operational logs to MySQL.
- External API Integrations: While core application state and orchestrations stay on the private host, the agent communicates externally with LLM providers (OpenAI API) and optional search APIs (Serper) or image generation models (Replicate).
Prerequisites
Before starting the deployment, verify the target host meets the following requirements:
- Docker & Docker Compose: Docker Engine 20.10+ or Docker Desktop with Compose v2 installed and running.
- Git: To clone the source repository.
- Node.js 18+: Required if using the bundled interactive CLI setup script.
- API Credentials:
- An active OpenAI API key with sufficient token quotas (GPT-4 or GPT-3.5-turbo).
- (Optional) Serper API key to enable internet search capabilities for autonomous web browsing.
- (Optional) Replicate API token if generating synthetic image assets.
Method 1: Quick Deployment via the Automated Setup Script
The AgentGPT repository provides an interactive onboarding script that automatically configures environment variables, builds local Docker images, and boots the service containers.
1. Clone the Repository
Clone the repository to your server and enter the project root:
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
2. Execute the Setup Script
Run the platform-specific launcher:
- Linux / macOS:
./setup.sh - Windows (PowerShell or Command Prompt):
setup.bat
3. Complete the Interactive Configuration
The setup wizard will prompt you for:
- Your OpenAI API Key.
- Optional Serper and Replicate credentials.
- Application port bindings and database preferences.
Once the script completes container provisioning, open your browser and navigate to http://localhost:3000 to verify that the AgentGPT interface is online.
Method 2: Manual Docker Compose Deployment
For production servers, continuous integration pipelines, or environments where interactive scripts are unsuitable, use standard Docker Compose workflows.
1. Clone and Inspect the Directory
git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT
The repository root contains docker-compose.yml, which defines two core services: frontend (pointing to ./next/Dockerfile) and platform (pointing to ./platform targeting the prod stage).
2. Configure Environment Variables
Copy the root environment example to the Next.js runtime environment path:
cp .env.example ./next/.env
Open ./next/.env in an editor and configure core variables:
# Platform runtime loop limit to prevent uncontrolled token consumption
NEXT_PUBLIC_MAX_LOOPS="50"
REWORKD_PLATFORM_MAX_LOOPS="50"
# Networking endpoints
NODE_ENV="production"
NEXT_PUBLIC_BACKEND_URL="http://localhost:8000"
# Session security
NEXTAUTH_SECRET="generate-a-secure-random-32-byte-hex-string"
NEXTAUTH_URL="http://localhost:3000"
# External LLM & Tooling APIs
OPENAI_API_KEY="sk-your-openai-api-key"
SERPER_API_KEY="your-optional-serper-api-key"
3. Build and Launch Containers
Trigger an explicit image build and start the containers in detached mode:
docker compose up --build -d
4. Verify Service Health and Logs
Check the status of running containers:
docker compose ps
To tail real-time output from the frontend and backend services:
docker compose logs -f
Navigate to http://localhost:3000 to create your first autonomous agent run.
Hardening Private Workflows for Production Environments
While the default Docker Compose configuration works out of the box for local development, system administrators deploying AgentGPT in private corporate networks should implement the following hardening practices:
1. Restrict Container Port Binding
By default, Docker publishes ports 3000 and 8000 on all network interfaces (0.0.0.0). If the host is accessible on a local network or public IP, bind these services exclusively to localhost (127.0.0.1):
# In docker-compose.yml
services:
frontend:
ports:
- "127.0.0.1:3000:3000"
platform:
ports:
- "127.0.0.1:8000:8000"
2. Implement a Reverse Proxy with TLS Termination
Route inbound traffic through Nginx, Traefik, or Caddy to provide SSL/TLS encryption, corporate SSO integration, and request rate limiting. A standard Nginx upstream configuration ensures frontend and API traffic are securely unified under a single domain:
server {
listen 443 ssl http2;
server_name agent.internal.example.com;
ssl_certificate /etc/ssl/certs/internal.crt;
ssl_certificate_key /etc/ssl/private/internal.key;
location / {
proxy_pass http://127.0.0.1:3000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto https;
}
}
3. Enforce Strict Loop Governance
Autonomous agents can enter repetitive recursive execution cycles when tasks are ambiguous. Always define NEXT_PUBLIC_MAX_LOOPS and REWORKD_PLATFORM_MAX_LOOPS (e.g., between 20 and 50) to protect corporate API budgets from unbounded expenditure.
4. Establish Clear Data Boundaries
Self-hosting AgentGPT keeps the application stack, task orchestration logs, and database records inside your security boundary. However, task prompts, contextual reasoning, and intermediate outputs are still transmitted over HTTPS to OpenAI's API endpoints. Teams handling strictly classified data should route requests through an enterprise Azure OpenAI Service instance or an internal egress proxy configured with data loss prevention (DLP) filters.
Operational Lifecycle and Maintenance Considerations
Before standardizing internal automation on AgentGPT, administrators should note the project's upstream maintenance lifecycle:
- Archival Status: The upstream
reworkd/AgentGPTrepository was formally archived in early 2026 after active feature development wound down. The codebase is stable for self-contained prototyping, academic exploration, and specialized task runs, but will not receive upstream security patches or dependency updates. - Dependency Pinning: When building Docker images from source, lock base images and package dependencies to prevent build breakage caused by outdated external npm or Python packages.
- Architectural Progression: For teams building mission-critical, long-running agentic pipelines requiring continuous tool integration, multi-agent debates, and human-in-the-loop approvals, consider comparing this containerized UI pattern with active orchestration frameworks such as CrewAI, AutoGen, or LangGraph.