Skip to main content

Quick Start — Local Development

Get ProjectAchilles running on your machine for development. This guide uses the development startup script that automatically installs dependencies, finds available ports, and starts both frontend and backend.

Prerequisites​

  • Node.js 22.x or higher
  • npm 10.x or higher
  • Git
  • Go 1.24+ (optional — only needed for agent development or building test binaries)

Steps​

1. Clone the Repository​

git clone https://github.com/projectachilles/ProjectAchilles.git
cd ProjectAchilles

2. Configure Clerk Authentication​

All modules require Clerk authentication. Create a free Clerk application:

  1. Sign up at clerk.com and create a new application
  2. Enable your desired sign-in methods (Google, GitHub, email/password)
  3. Copy your API keys from the Clerk Dashboard

Create the environment files:

# Frontend
cat > frontend/.env << 'EOF'
VITE_CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
EOF

# Backend
cat > backend/.env << 'EOF'
CLERK_PUBLISHABLE_KEY=pk_test_your_key_here
CLERK_SECRET_KEY=sk_test_your_key_here
EOF
Separate Keys

The frontend uses VITE_CLERK_PUBLISHABLE_KEY (with the VITE_ prefix) and the backend uses CLERK_PUBLISHABLE_KEY and CLERK_SECRET_KEY. Both the frontend and backend publishable keys should be the same value.

3. Start the Development Stack​

./scripts/start.sh -k --daemon

This script will:

  • Kill any existing ProjectAchilles processes (-k)
  • Install npm dependencies for both frontend and backend
  • Find available ports (defaults: frontend 5173, backend 3000)
  • Start both services in the background (--daemon)

4. Open the Dashboard​

Navigate to http://localhost:5173 in your browser. You'll be redirected to Clerk's sign-in page. After authenticating, you'll see the Test Browser.

Optional: Elasticsearch​

The Analytics module requires an Elasticsearch connection. You can either:

Option A — Use Elastic Cloud (recommended for production):

  1. Create a free trial at elastic.co
  2. Add credentials to backend/.env:
ELASTICSEARCH_CLOUD_ID=your_cloud_id
ELASTICSEARCH_API_KEY=your_api_key

Option B — Use local Elasticsearch via Docker:

docker compose --profile elasticsearch up -d

This starts Elasticsearch 8.17 (single-node, security disabled) and seeds 1,000 synthetic test results.

The local ES instance is available at http://localhost:9200 — no credentials needed.

Optional: Test Library​

To populate the Test Browser, configure a Git repository containing security tests:

# In backend/.env
TESTS_REPO_URL=https://github.com/your-org/your-test-library.git
GITHUB_TOKEN=ghp_your_pat_here  # Only needed for private repos

The backend will clone and sync the test library on startup.

Stopping Services​

./scripts/start.sh --stop

Troubleshooting​

Port Conflicts​

If ports 5173 or 3000 are in use, the start script will automatically find the next available port. Check the script output for the actual ports used.

Clerk Authentication Errors​

  • Ensure both frontend/.env and backend/.env have the correct keys
  • The publishable key should start with pk_test_ (development) or pk_live_ (production)
  • The secret key should start with sk_test_ or sk_live_

TypeScript Build Errors​

Verify the project compiles cleanly:

cd frontend && npm run build
cd ../backend && npm run build

Next Steps​