Installation Guide
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:
(On Windows, use
python3.12 -m venv .venv source .venv/bin/activate.\.venv\Scripts\activatefor PowerShell/Command Prompt) - Install the required Python packages:
The Agent service will automatically create and initialize the SQLite database file specified by
pip install -r requirements.txtSQLITE_PATHwhen 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 rootenvoy/directory):cd ../tools - Install Node.js dependencies. You can use
npm,yarn, orpnpm: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 rootenvoy/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
--reloadflag 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:
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!