Developer Setup

This section provides instructions for setting up a local development environment for Envoy. Envoy is composed of three distinct services: Agent (Python), Tools (Node.js), and Portal (React). You will need to set up and run all three services for the application to function correctly.

Prerequisites

Before you begin, ensure you have the following installed on your machine:

Git: For cloning the repository.
Python 3.12 or newer: Required for the Agent service. We recommend using a virtual environment.
Node.js 20 or newer: Required for the Tools and Portal services.
npm (Node Package Manager): Typically bundled with Node.js.
Google Chrome: Required for Playwright to perform browser automation in the Tools service. Ensure it's installed and accessible from your system's PATH.

1. Clone the Repository

Start by cloning the Envoy repository to your local machine:

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

2. Environment Configuration

Envoy uses environment variables for configuration. It's recommended to create a .env file in the project root to manage these variables locally. Copy the example file and populate it:

cp .env.example .env

Now, open the .env file and set the following variables.

Core Application Settings

These are essential for the services to communicate and function.

INTERNAL_AUTH_SECRET: A secret key used for authentication between the Agent and Tools services. Choose any strong, random string. This must be the same for both services.
```
INTERNAL_AUTH_SECRET="your-super-secret-key-here"
```
SQLITE_PATH: The path to the SQLite database file where Agent persists its data. For local development, you can use a file within the project directory.
```
SQLITE_PATH="sqlite.db"
```
- Note: You can also set SQLITE_PATH=":memory:" for an entirely in-memory, non-persistent database for quick testing.
PROFILE_PATH: The path to the JSON file containing your canonical professional profile data. This is used by the Agent for AI-driven insights and cover letter generation. You can start with an empty JSON object {} or a basic profile, and the interview workflow will help you populate it.
```
PROFILE_PATH="./nitin_datta_profile.json"
```
RAW_PROFILE_PATH: The path to a JSON file where raw profile data (e.g., from LinkedIn export) can be stored, which Agent uses to build the canonical profile.
```
RAW_PROFILE_PATH="./raw_profile.json"
```

Service Endpoints

These variables ensure services know how to reach each other.

TOOLS_BASE_URL: The base URL where the Tools service will be running.
```
TOOLS_BASE_URL="http://127.0.0.1:4320"
```
AGENT_BASE_URL: The base URL where the Agent service will be running. The Portal service will connect to this.
```
AGENT_BASE_URL="http://127.0.0.1:8000"
```

AI Configuration (Optional)

If you plan to develop or test AI-driven features, you'll need to configure your OpenAI API access.

OPENAI_API_KEY: Your OpenAI API key.
OPENAI_BASE_URL: (Optional) If you are using a self-hosted or compatible OpenAI API endpoint, provide its URL. Otherwise, omit this for the default OpenAI API.
OPENAI_MODEL: (Optional) The name of the OpenAI model to use (e.g., gpt-4o, gpt-3.5-turbo).

# Example OpenAI settings
OPENAI_API_KEY="sk-your-openai-api-key"
# OPENAI_BASE_URL="https://api.openai.com/v1" # Uncomment and modify if using a custom endpoint
OPENAI_MODEL="gpt-4o"

3. Service Setup and Running

You need to set up and run each service in its dedicated directory. Open three separate terminal windows for this.

3.1. Tools Service (Node.js)

The Tools service handles browser automation using Playwright.

Navigate to the tools/ directory:
```
cd tools
```
Install Node.js dependencies:
```
npm install
```
Start the Tools service:
```
npm start
```
The Tools service will typically run on http://127.0.0.1:4320 (as configured in TOOLS_BASE_URL). You should see output indicating it's listening.

3.2. Agent Service (Python)

The Agent service is the core orchestrator, handling AI, persistence, and the main API.

Navigate to the agent/ directory (in a new terminal):
```
cd agent
```

Create and activate a Python virtual environment (recommended):

python3.12 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate

Install Python dependencies:
```
pip install -r requirements.txt
```
Run database migrations (initializes the SQLite database schema):
```
python -m app.persistence.migrations
```
Start the Agent service using Uvicorn:
```
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
The Agent service will run on http://127.0.0.1:8000 (as configured in AGENT_BASE_URL). The --reload flag is useful for development as it restarts the server on code changes.

3.3. Portal Service (React)

The Portal service is the user interface, a React application that interacts with the Agent.

Navigate to the portal/ directory (in a new terminal):
```
cd portal
```
Install Node.js dependencies:
```
npm install
```
Start the Portal development server:
```
npm run dev
```
The Portal will typically be accessible at http://localhost:5173 (or another port if 5173 is in use).

4. Verifying the Setup

Once all three services are running:

Open your web browser and navigate to the Portal URL (e.g., http://localhost:5173).
You should see the Envoy user interface.
Try to perform a search or start a profile interview. Observe the logs in your terminal windows for each service to ensure they are communicating and processing requests without errors.

Congratulations! You have successfully set up your Envoy development environment.