Quick Start

Get Envoy up and running in minutes to start automating your job applications. This guide will walk you through the essential steps to install, configure, and launch Envoy.

Prerequisites

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

Python 3.12+: The core Agent service runs on Python.
Node.js 20+: The Tools (browser automation) and Portal (user interface) services run on Node.js.
Google Chrome: Envoy uses Playwright for browser automation, which requires a local installation of Google Chrome.

Installation

Clone the repository:

Start by cloning the Envoy repository to your local machine:
```
git clone https://github.com/nitindatta/envoy.git
cd envoy
```
Install Python dependencies (Agent service):

Navigate into the agent/ directory and install the required Python packages:
```
cd agent
pip install -r requirements.txt
cd ..
```
Install Node.js dependencies (Tools & Portal services):

Next, install the Node.js packages for both the tools/ and portal/ directories:
```
cd tools
npm install
cd ../portal
npm install
cd ..
```

Configuration

Envoy uses environment variables for configuration. You'll typically create .env files in the agent/ and portal/ directories.

OpenAI API Key: Envoy's AI features, such as cover letter generation and profile interviews, require an OpenAI API key.

Create a file named agent/.env and add your API key:

OPENAI_API_KEY="sk-YOUR_OPENAI_KEY"
# Optional: If using a local LLM or custom endpoint, configure these:
# OPENAI_BASE_URL="http://localhost:1234/v1"
# OPENAI_MODEL="ollama/llama3"

Internal Authentication Secret: Envoy's services communicate securely using a shared internal secret. This helps prevent unauthorized access to the internal APIs.

Add the same secret to both agent/.env and portal/.env:

agent/.env:
```
INTERNAL_AUTH_SECRET="your-secure-random-secret"
```
portal/.env:
```
VITE_AGENT_BASE_URL="http://127.0.0.1:8000" # Default Agent API URL
VITE_INTERNAL_AUTH_SECRET="your-secure-random-secret" # Must match the secret in agent/.env
```
Profile Path (Optional for first run): Envoy needs a professional profile to draw information from. While you can create a profile.json manually, the interactive Profile Interview feature is designed to help you build and refine it.

In agent/.env, specify where your profile data will be stored. If the file doesn't exist, Envoy will guide you to create one.
```
PROFILE_PATH="./data/my_profile.json"
RAW_PROFILE_PATH="./data/raw_profile.json" # Used for initial parsing of raw text
```

Running Envoy

Envoy comprises three services that need to run concurrently. Open three separate terminal windows for the following steps.

Start the Agent (Backend API & Orchestration): In your first terminal, navigate to the envoy/agent directory and start the FastAPI application:
```
cd agent
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
```
(Leave this terminal running.)
Start the Tools (Browser Automation): In your second terminal, navigate to the envoy/tools directory and launch the Playwright-based browser automation service:
```
cd tools
npm run dev
```
(Leave this terminal running. This service will typically run on http://127.0.0.1:4320.)
Start the Portal (User Interface): In your third terminal, navigate to the envoy/portal directory and start the React development server:
```
cd portal
npm run dev
```
(Leave this terminal running. The Portal UI will typically be available at http://localhost:5173.)

Your First Steps with Envoy

Once all three services are running:

Access the Envoy Portal: Open your web browser and navigate to http://localhost:5173.
Set Up Your Profile: If this is your first time using Envoy, you'll likely be prompted to start a Profile Interview. This AI-guided process helps you build a detailed professional profile based on the STAR method (Situation, Task, Action, Result), which is crucial for generating accurate and compelling cover letters. Follow the on-screen prompts to complete this.
Search for Jobs: After establishing your profile, use the Portal's interface to enter your desired job keywords and location. Click "Run Search." Envoy will query job boards (like SEEK) and display relevant listings.
Review and Prepare Applications: For jobs you're interested in, click the "Review" button. The Agent will asynchronously fetch the full job description, evaluate your profile's fit, and generate a personalized cover letter draft. You can then review the AI's analysis, make edits to the cover letter, and compare it against the job description.
Start Applying: Once you're satisfied with the prepared application, click "Approve" and then "Start Applying." Envoy will open a new Chrome browser window and begin automating the application form filling. During this process, you may be prompted to log in to job platforms (e.g., SEEK) within the opened browser window if you are not already logged in.

Congratulations! You've successfully installed and started using Envoy to automate and enhance your job application process.