Arch Recon — agent stack

This repository contains a minimal Docker Compose setup to run the Arch Recon agent stack. By default it pulls the published container images, but you can point the stack at locally built images via environment variables.

Prerequisites

• Docker Engine with Docker Compose installed.

Setup

1. Clone the repository

git clone <repository-url>
cd arch-recon-stack

2. Create environment file

Create a .env file in the root directory next to docker-compose.yml. The setup script will automatically create this file and configure the LOCAL_AGENT_WORKSPACE variable, but you can also create it manually.

Required environment variables:

• LOCAL_AGENT_WORKSPACE - Path to the agent workspace directory (defaults to ./agent_workspace if using setup script)

Optional environment variables:

• AGENT_IMAGE - Override the agent container image (default: thwr322/arch-recon-agent:latest)
• CHAT_IMAGE - Override the chat container image (default: arch-recon-chat:local)

3. Run the setup script

The setup script will:

• Create the agent_workspace directory for the agent
• Create or update the .env file with the LOCAL_AGENT_WORKSPACE variable

On Linux/macOS:

./setup.sh

On Windows (PowerShell):

bash setup.sh

Manual setup (alternative): If you prefer to set up manually:

1. Create the agent workspace directory: mkdir agent_workspace
2. Create a .env file with: LOCAL_AGENT_WORKSPACE=./agent_workspace

4. Configure the agent (optional)

The archrecon.json file contains the agent configuration including:

• Model settings (git_clone_model, arch_recon_model)
• Tool call limits
• Error handling settings
• Summarization parameters
• Recursion limits

You can modify this file to customize the agent behavior before starting the stack.

Usage

Start the stack

docker compose up

Run in background

docker compose up -d

Run without PlantUML logs

docker compose up --no-attach plantuml

Rebuild images and start

docker compose up --build

Stop and remove containers

docker compose down

Services

The stack includes three services:

• agent - The Arch Recon agent service (port 2024)
• chat - The chat frontend interface (port 3000)
• plantuml - PlantUML server for diagram generation (port 8080)

Notes

• Compose automatically reads .env before parsing docker-compose.yml. Run docker compose config to confirm that your overrides are applied.
• The compose file exposes ports for the agent, chat frontend, and PlantUML service. Adjust the port mappings in docker-compose.yml if needed.