Installation Guide

This guide will walk you through setting up Envoy, a local, review-first autonomous job application agent, on your machine. Envoy consists of three independent services that work together: the Agent (Python), Tools (Node.js with Playwright), and Portal (React UI).

System Requirements

Before you begin, ensure your system meets the following requirements:

Operating System: macOS, Linux, or Windows (WSL recommended for Linux environments on Windows).
Git: For cloning the repository.
Python 3.12: The Agent service requires this specific version.
Node.js 20: The Tools and Portal services require this specific version, including its package manager (npm, yarn, or pnpm).
Google Chrome Browser: The Tools service uses Playwright to control a Chrome instance for browser automation. Ensure Chrome is installed and up to date.

Step 1: Clone the Repository

First, clone the Envoy repository to your local machine:

git clone https://github.com/nitindatta/envoy.git
cd envoy

Step 2: Configure Environment Variables

Envoy uses environment variables for configuration, including API keys and inter-service communication. We recommend creating a .env file in the root directory of the cloned repository.

Create a file named .env in the envoy/ directory with the following content:

# Required for AI-powered features (e.g., cover letter generation, profile interviews)
OPENAI_API_KEY="YOUR_OPENAI_API_KEY"

# A secret key used for internal authentication between Agent and Tools services.
# Generate a random string (e.g., using `head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32`)
INTERNAL_AUTH_SECRET="YOUR_GENERATED_SECRET_KEY"

# Path to the SQLite database file.
# This file will be created if it doesn't exist.
# For persistent data, choose a specific path like './envoy.sqlite3'.
# For development/testing, you can use ':memory:' but data will not persist.
SQLITE_PATH="./envoy.sqlite3"

# The base URL for the Tools service.
# The Agent service needs to know where to find the Tools service.
# This should match the address where the Tools service is running (default is 4320).
TOOLS_BASE_URL="http://127.0.0.1:4320"

# The base URL for the Portal service.
# The Agent service may need this for generating UI links or callbacks.
# This should match the address where the Portal service is running (default is 3000).
PORTAL_BASE_URL="http://127.0.0.1:3000"

# Optional: Set to 'DEBUG' for verbose logging
LOG_LEVEL="INFO"

Important:

Replace "YOUR_OPENAI_API_KEY" with your actual OpenAI API key. Without this, AI features will not function.
Replace "YOUR_GENERATED_SECRET_KEY" with a strong, random string. This secret ensures secure communication between services.

Step 3: Install Agent Service (Python)

The Agent service is written in Python.

Navigate into the agent/ directory:
```
cd agent
```
Create and activate a Python virtual environment:
```
python3.12 -m venv .venv
source .venv/bin/activate
```
(On Windows, use .\.venv\Scripts\activate for PowerShell/Command Prompt)
Install the required Python packages:
```
pip install -r requirements.txt
```
The Agent service will automatically create and initialize the SQLite database file specified by SQLITE_PATH when it first starts up.

Step 4: Install Tools Service (Node.js)

The Tools service is a Node.js application that uses Playwright for browser automation.

Navigate into the tools/ directory (from the root envoy/ directory):
```
cd ../tools
```
Install Node.js dependencies. You can use npm, yarn, or pnpm:
```
npm install # Or yarn install / pnpm install
```
Install the Playwright Chromium browser binary:
```
npx playwright install chromium
```

Step 5: Install Portal Service (React)

The Portal is a React web application that provides the user interface.

Navigate into the portal/ directory (from the root envoy/ directory):
```
cd ../portal
```

Install Node.js dependencies:

npm install # Or yarn install / pnpm install

Step 6: Run Envoy Services

Envoy's three services are designed to run concurrently. You will need to open three separate terminal windows to run them simultaneously.

Make sure you are in the correct directory for each service before running its command.

Run Agent Service: Open a new terminal, activate the Python virtual environment, and start the FastAPI server:
```
cd envoy/agent
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
(The --reload flag is optional and enables hot-reloading for development.)
Run Tools Service: Open a new terminal and start the Node.js Tools server:
```
cd envoy/tools
npm run start
```
Run Portal Service: Open a new terminal and start the React development server:
```
cd envoy/portal
npm run dev
```

Step 7: Verify Installation

Once all three services are running, open your web browser and navigate to the Portal's address:

http://localhost:3000

You should see the Envoy user interface. Check the terminal outputs for each service to ensure there are no errors and that they are running as expected. If all services start without issues and the Portal loads, your Envoy installation is successful!