diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
new file mode 100644
index 0000000..e4ad542
--- /dev/null
+++ b/.devcontainer/devcontainer.json
@@ -0,0 +1,76 @@
+{
+  "name": "GitHub App Auth Container Devcontainer",
+  "image": "mcr.microsoft.com/devcontainers/base:noble",
+  "features": {
+    "ghcr.io/devcontainers/features/go:1": {},
+    "ghcr.io/devcontainers/features/docker-outside-of-docker:1": {}
+  },
+  "mounts": [
+    {
+        "source": "/var/run/docker.sock",
+        "target": "/var/run/docker.sock",
+        "type": "bind"
+    },
+    {
+        "source": "claude",
+        "target": "/home/vscode/.claude",
+        "type": "volume"
+    }
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        // Docker and containers
+        "ms-azuretools.vscode-docker",
+
+        // Data and formats
+        "redhat.vscode-yaml",
+
+        // Markdown and documentation
+        "yzhang.markdown-all-in-one",
+        "bierner.markdown-mermaid",
+
+        // Protocol Buffers (gRPC)
+        "zxh404.vscode-proto3",
+
+        // Go development
+        "golang.go",
+
+        // General productivity
+        "Gruntfuggly.todo-tree",
+        "eamodio.gitlens",
+        "github.vscode-github-actions",
+        "GitHub.vscode-pull-request-github",
+
+        // AI assistants
+        "anthropic.claude-code",
+        "google.geminicodeassist",
+        "google.gemini-cli-vscode-ide-companion"
+      ],
+      "settings": {
+        "go.useLanguageServer": true,
+        "go.lintTool": "golangci-lint",
+        "go.lintOnSave": "package",
+        "[go]": {
+          "editor.formatOnSave": true,
+          "editor.codeActionsOnSave": {
+            "source.organizeImports": "explicit"
+          }
+        }
+      }
+    }
+  },
+
+  "remoteEnv": {
+    "PATH": "${containerEnv:PATH}:/usr/local/go/bin:/go/bin:/home/vscode/.bun/bin"
+  },
+
+  "forwardPorts": [],
+  "portsAttributes": {
+  },
+
+  "postCreateCommand": {
+    "golangci-lint": "go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest",
+    "claude-code": "curl -fsSL https://claude.ai/install.sh | bash"
+  }
+}
diff --git a/.env.example b/.env.example
index d6c013a..db6cfaf 100644
--- a/.env.example
+++ b/.env.example
@@ -22,7 +22,7 @@ TEST_GITHUB_PRIVATE_KEY_B64=LS0tLS1CRUdJTi...base64...
 # =============================================================================
 # Test Agent Identity
 # =============================================================================
-# Agent name used for authentication (must match the Bitwarden item name)
+# Agent name used for authentication (must match the item name in your secrets backend)
 TEST_AGENT_NAME=test-agent
 
 # Agent email for commit attribution
@@ -41,6 +41,20 @@ VAULTWARDEN_ADMIN_TOKEN=your-random-admin-token-here
 TEST_VAULT_EMAIL=test@localhost
 TEST_VAULT_PASSWORD=test-password-for-local-vault
 
+# =============================================================================
+# Secrets Backend Selection (for production/runtime)
+# =============================================================================
+# Choose secrets backend: "bitwarden" (default) or "vault"
+# SECRETS_BACKEND=bitwarden
+
+# =============================================================================
+# HashiCorp Vault Settings (when SECRETS_BACKEND=vault)
+# =============================================================================
+# VAULT_ADDR=http://localhost:8200
+# VAULT_TOKEN=your-vault-token
+# VAULT_MOUNT_PATH=secret
+# VAULT_BASE_PATH=agents
+
 # =============================================================================
 # Optional: Enable real GitHub API testing
 # =============================================================================
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 20fb65a..6d7542a 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -10,7 +10,7 @@ on:
       enable_github_api_tests:
         description: 'Run tests against real GitHub API'
         required: false
-        default: 'false'
+        default: false
         type: boolean
 
 env:
@@ -132,6 +132,94 @@ jobs:
         run: |
           docker-compose -f docker-compose.test.yml down -v --remove-orphans
 
+  # E2E tests with HashiCorp Vault backend
+  e2e-test-vault:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Create .env file
+        run: |
+          cat > .env << EOF
+          TEST_AGENT_NAME=${{ env.TEST_AGENT_NAME }}
+          TEST_AGENT_EMAIL=${{ env.TEST_AGENT_EMAIL }}
+          TEST_GITHUB_APP_ID=${{ secrets.TEST_GITHUB_APP_ID }}
+          TEST_GITHUB_INSTALLATION_ID=${{ secrets.TEST_GITHUB_INSTALLATION_ID }}
+          TEST_GITHUB_PRIVATE_KEY_B64=${{ secrets.TEST_GITHUB_PRIVATE_KEY_B64 }}
+          TEST_GITHUB_API_ENABLED=false
+          EOF
+
+      - name: Build containers
+        run: |
+          docker-compose -f docker-compose.test-vault.yml build
+
+      - name: Start Vault server
+        run: |
+          docker-compose -f docker-compose.test-vault.yml up -d vault-server
+
+          echo "Waiting for Vault..."
+          timeout 30 bash -c 'until curl -sf http://localhost:8200/v1/sys/health 2>/dev/null; do sleep 1; done' || {
+            docker-compose -f docker-compose.test-vault.yml logs vault-server
+            exit 1
+          }
+          echo "Vault is ready"
+
+      - name: Seed Vault with test credentials
+        run: |
+          docker-compose -f docker-compose.test-vault.yml up vault-seeder
+
+          EXIT_CODE=$(docker inspect test-vault-seeder-hcv --format='{{.State.ExitCode}}')
+          if [ "$EXIT_CODE" != "0" ]; then
+            echo "Vault seeder failed"
+            docker-compose -f docker-compose.test-vault.yml logs vault-seeder
+            exit 1
+          fi
+
+      - name: Start auth service
+        run: |
+          docker-compose -f docker-compose.test-vault.yml up -d github-auth-service
+
+          echo "Waiting for auth service..."
+          timeout 60 bash -c 'until curl -sf http://localhost:8080/health 2>/dev/null; do sleep 2; done' || {
+            docker-compose -f docker-compose.test-vault.yml logs github-auth-service
+            exit 1
+          }
+          echo "Auth service is ready"
+
+      - name: Run e2e tests
+        run: |
+          docker-compose -f docker-compose.test-vault.yml up test-runner
+
+          EXIT_CODE=$(docker inspect test-runner-vault --format='{{.State.ExitCode}}')
+          docker-compose -f docker-compose.test-vault.yml logs test-runner
+          exit $EXIT_CODE
+
+      - name: Collect logs on failure
+        if: failure()
+        run: |
+          echo "=== Vault server logs ==="
+          docker-compose -f docker-compose.test-vault.yml logs vault-server
+          echo ""
+          echo "=== Vault seeder logs ==="
+          docker-compose -f docker-compose.test-vault.yml logs vault-seeder
+          echo ""
+          echo "=== Auth service logs ==="
+          docker-compose -f docker-compose.test-vault.yml logs github-auth-service
+          echo ""
+          echo "=== Test runner logs ==="
+          docker-compose -f docker-compose.test-vault.yml logs test-runner
+
+      - name: Cleanup
+        if: always()
+        run: |
+          docker-compose -f docker-compose.test-vault.yml down -v --remove-orphans
+
   # Build-only job for PRs without secrets
   build:
     runs-on: ubuntu-latest
@@ -142,7 +230,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.22'
+          go-version: '1.23'
 
       - name: Build
         run: |
diff --git a/AGENTS.md b/AGENTS.md
index d4a2f98..7e4afd1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,22 +9,23 @@ This is a Go REST API service that provides GitHub App authentication and SSH co
 ## Architecture
 
 ```
-Agent Container                    Auth Service                 Bitwarden
-     │                                  │                           │
-     │  X-Agent-Name + X-Agent-Token    │                           │
-     ├─────────────────────────────────►│                           │
-     │                                  │   (startup only)          │
-     │                                  │◄──────────────────────────┤
-     │         Installation Token       │                           │
-     │◄─────────────────────────────────┤                           │
-     │                                  │                           │
+Agent Container                    Auth Service           Secrets Backend
+     │                                  │               (Bitwarden or Vault)
+     │  X-Agent-Name + X-Agent-Token    │                       │
+     ├─────────────────────────────────►│                       │
+     │                                  │   (startup only)      │
+     │                                  │◄──────────────────────┤
+     │         Installation Token       │                       │
+     │◄─────────────────────────────────┤                       │
+     │                                  │                       │
 ```
 
 **Key design decisions:**
 - **Token-based auth**: Agents authenticate with pre-signed tokens, not IP-based identification
-- **Fetch-at-startup**: All secrets loaded from Bitwarden at startup, session closed immediately
+- **Pluggable backends**: SecretsBackend interface supports Bitwarden and HashiCorp Vault
+- **Fetch-at-startup**: All secrets loaded from backend at startup, session closed immediately
 - **SSH signing**: Uses the GitHub App's RSA private key for commit signing (not GPG)
-- **Collection-based config**: Agents defined by Bitwarden collection contents, not a config file
+- **Scope-based config**: Agents defined by collection (Bitwarden) or path (Vault) contents
 
 ## Directory Structure
 
@@ -38,10 +39,11 @@ Agent Container                    Auth Service                 Bitwarden
 │   ├── api/                    # HTTP handlers, middleware, router
 │   ├── config/                 # Environment variable loading
 │   ├── github/                 # GitHub API client, JWT generation, token caching
-│   ├── secrets/                # Bitwarden backend, in-memory store
+│   ├── secrets/                # Secrets backends (Bitwarden, Vault), in-memory store
 │   └── ssh/                    # SSH signature generation
 ├── scripts/
-│   └── seed-vault.sh           # Test setup: seeds Vaultwarden with test data
+│   ├── seed-vault.sh           # Test setup: seeds Vaultwarden with test data
+│   └── seed-vault-hcv.sh       # Test setup: seeds HashiCorp Vault with test data
 ├── tests/
 │   └── e2e_test.go             # End-to-end tests
 └── examples/
@@ -52,8 +54,10 @@ Agent Container                    Auth Service                 Bitwarden
 
 | File | Purpose |
 |------|---------|
+| `internal/secrets/backend.go` | SecretsBackend interface, shared types |
 | `internal/secrets/store.go` | In-memory secrets store, token verification |
-| `internal/secrets/bitwarden.go` | Bitwarden CLI wrapper |
+| `internal/secrets/bitwarden.go` | Bitwarden CLI backend |
+| `internal/secrets/vault.go` | HashiCorp Vault KV v2 backend |
 | `internal/api/middleware.go` | Token authentication middleware |
 | `internal/api/handlers.go` | REST API endpoint handlers |
 | `internal/github/service.go` | GitHub JWT generation and token fetching |
@@ -82,18 +86,28 @@ All `/api/v1/*` endpoints require `X-Agent-Name` and `X-Agent-Token` headers.
 
 ## Testing
 
-E2E tests use Vaultwarden (self-hosted Bitwarden) in Docker Compose:
+E2E tests run against both backends:
 
 ```bash
-docker-compose -f docker-compose.test.yml up --build --abort-on-container-exit
+# Bitwarden backend (Vaultwarden)
+make test-e2e
+
+# HashiCorp Vault backend
+make test-e2e-vault
 ```
 
-The test stack:
+The Bitwarden test stack (`docker-compose.test.yml`):
 1. `vaultwarden` - Test Bitwarden server
 2. `vault-seeder` - Populates test credentials
 3. `github-auth-service` - Service under test
 4. `test-runner` - Executes Go tests
 
+The Vault test stack (`docker-compose.test-vault.yml`):
+1. `vault-server` - HashiCorp Vault dev server
+2. `vault-seeder` - Populates test credentials
+3. `github-auth-service` - Service under test (SECRETS_BACKEND=vault)
+4. `test-runner` - Executes Go tests (same tests, backend-agnostic)
+
 ## Common Tasks
 
 ### Adding a new API endpoint
@@ -103,12 +117,20 @@ The test stack:
 3. Register route in `internal/api/router.go`
 4. Add test in `tests/e2e_test.go`
 
-### Modifying Bitwarden item structure
+### Modifying agent item structure
 
 1. Update `parseAgentItem()` in `internal/secrets/store.go`
-2. Update `scripts/seed-vault.sh` for test seeding
+2. Update `scripts/seed-vault.sh` (Bitwarden) and `scripts/seed-vault-hcv.sh` (Vault) for test seeding
 3. Update README.md documentation
 
+### Adding a new secrets backend
+
+1. Implement `SecretsBackend` interface in `internal/secrets/<backend>.go`
+2. Add config fields in `internal/config/config.go`
+3. Add case to the backend selection switch in `cmd/server/main.go`
+4. Add e2e test infrastructure (docker-compose, seeder script)
+5. Update documentation
+
 ### Adding a new helper binary
 
 1. Create `cmd/<binary-name>/main.go`
@@ -119,15 +141,21 @@ The test stack:
 
 - `github.com/go-chi/chi/v5` - HTTP router
 - `github.com/golang-jwt/jwt/v5` - JWT generation for GitHub App auth
+- `github.com/hashicorp/vault/api` - HashiCorp Vault client
 - `golang.org/x/crypto/ssh` - SSH key handling and signatures
 
 ## Environment Variables
 
 The service reads all config from environment variables (no config files):
 
-- `BW_SESSION` / `BW_SESSION_FILE` - Bitwarden session token
-- `BW_COLLECTION_ID` / `BW_COLLECTION_ID_FILE` - Collection containing agent items
-- `BW_SERVER_URL` - Optional Vaultwarden URL
+- `SECRETS_BACKEND` - `bitwarden` (default) or `vault`
+- `BW_SESSION` / `BW_SESSION_FILE` - Bitwarden session token (bitwarden backend)
+- `BW_COLLECTION_ID` / `BW_COLLECTION_ID_FILE` - Collection containing agent items (bitwarden backend)
+- `BW_SERVER_URL` - Optional Vaultwarden URL (bitwarden backend)
+- `VAULT_ADDR` - Vault server address (vault backend)
+- `VAULT_TOKEN` / `VAULT_TOKEN_FILE` - Vault auth token (vault backend)
+- `VAULT_MOUNT_PATH` - KV v2 mount path, default `secret` (vault backend)
+- `VAULT_BASE_PATH` - Base path for agents, default `agents` (vault backend)
 - `GITHUB_API_URL` - Optional GitHub Enterprise URL
 - `LOG_LEVEL` - INFO or DEBUG
 - `PORT` - Server port (default 8080)
@@ -138,4 +166,6 @@ The service reads all config from environment variables (no config files):
 - There is no Docker socket access - authentication is token-based
 - GPG is NOT used - SSH signing with the GitHub App's RSA key
 - The Bitwarden CLI is called via `exec.Command`, not a Go library
+- The Vault backend uses the `hashicorp/vault/api` Go client (no CLI needed)
 - Secrets are loaded once at startup and held in memory
+- Backend selection is via `SECRETS_BACKEND` env var, defaulting to `bitwarden`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..705168f
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,45 @@
+# Contributing
+
+## Prerequisites
+
+- Go 1.23+
+- Docker & Docker Compose
+- A Bitwarden/Vaultwarden account or HashiCorp Vault server
+
+## Building
+
+```bash
+# Build auth service
+docker build -t github-app-auth-container .
+
+# Build helpers
+docker build -f Dockerfile.helpers -t github-app-auth-container-helpers .
+```
+
+## Running Tests
+
+```bash
+# Copy and configure test environment
+cp .env.example .env
+# Edit .env with your test credentials
+
+# Run unit tests
+go test -v ./internal/...
+
+# Run e2e tests with Bitwarden backend
+make test-e2e
+
+# Run e2e tests with HashiCorp Vault backend
+make test-e2e-vault
+```
+
+Tests requiring real GitHub App credentials (`TestTokenEndpoint`, `TestGitCredentialsEndpoint`, `TestFullGitWorkflow`) are skipped unless `TEST_GITHUB_API_ENABLED=true` is set and valid credentials are configured in `.env`.
+
+## Publishing
+
+Tag with a semantic version to trigger the publish workflow:
+
+```bash
+git tag 1.0.0
+git push origin 1.0.0
+```
diff --git a/Dockerfile b/Dockerfile
index 38022a8..801179d 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,5 +1,5 @@
 # Build stage
-FROM golang:1.22-alpine AS builder
+FROM golang:1.23-alpine AS builder
 
 WORKDIR /app
 
diff --git a/Dockerfile.helpers b/Dockerfile.helpers
index 7e49c20..e761ffb 100644
--- a/Dockerfile.helpers
+++ b/Dockerfile.helpers
@@ -10,7 +10,7 @@
 #   COPY --from=helpers /usr/local/bin/git-* /usr/local/bin/
 
 # Build stage
-FROM golang:1.22-alpine AS builder
+FROM golang:1.23-alpine AS builder
 
 WORKDIR /app
 
diff --git a/Dockerfile.test-runner b/Dockerfile.test-runner
index f3aebf5..2b06530 100644
--- a/Dockerfile.test-runner
+++ b/Dockerfile.test-runner
@@ -1,7 +1,7 @@
 # Dockerfile.test-runner
 # Container that runs e2e tests against the auth service
 
-FROM golang:1.22-alpine
+FROM golang:1.23-alpine
 
 # Install dependencies
 RUN apk add --no-cache \
diff --git a/Dockerfile.test-seeder-vault b/Dockerfile.test-seeder-vault
new file mode 100644
index 0000000..b7208c7
--- /dev/null
+++ b/Dockerfile.test-seeder-vault
@@ -0,0 +1,25 @@
+# Dockerfile.test-seeder-vault
+# Container that seeds HashiCorp Vault with test credentials
+
+FROM hashicorp/vault:1.15
+
+RUN apk add --no-cache \
+    bash \
+    curl \
+    jq \
+    openssl \
+    coreutils \
+    && rm -rf /var/cache/apk/*
+
+# Create output directory
+RUN mkdir -p /output
+
+# Copy seed script
+COPY scripts/seed-vault-hcv.sh /usr/local/bin/seed-vault-hcv.sh
+RUN chmod +x /usr/local/bin/seed-vault-hcv.sh
+
+# Set environment
+ENV OUTPUT_DIR=/output
+
+# Run the seeder
+CMD ["/usr/local/bin/seed-vault-hcv.sh"]
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..1ad9111
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,5 @@
+Copyright 2026 Scratching Monkey Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
\ No newline at end of file
diff --git a/Makefile b/Makefile
index f1b928d..a46af3b 100644
--- a/Makefile
+++ b/Makefile
@@ -1,20 +1,21 @@
-.PHONY: build test test-e2e clean help deps
+.PHONY: build test test-e2e test-e2e-vault clean help deps
 
 # Default target
 help:
 	@echo "GitHub App Auth Container"
 	@echo ""
 	@echo "Usage:"
-	@echo "  make deps        - Download Go dependencies and generate go.sum"
-	@echo "  make build       - Build the Docker image"
-	@echo "  make test        - Run unit tests"
-	@echo "  make test-e2e    - Run e2e tests with Vaultwarden"
-	@echo "  make clean       - Clean up containers and volumes"
+	@echo "  make deps             - Download Go dependencies and generate go.sum"
+	@echo "  make build            - Build the Docker image"
+	@echo "  make test             - Run unit tests"
+	@echo "  make test-e2e         - Run e2e tests with Vaultwarden (Bitwarden backend)"
+	@echo "  make test-e2e-vault   - Run e2e tests with HashiCorp Vault backend"
+	@echo "  make clean            - Clean up containers and volumes"
 	@echo ""
 	@echo "E2E Test Setup:"
 	@echo "  1. Copy .env.example to .env"
 	@echo "  2. Fill in your test GitHub App credentials"
-	@echo "  3. Run: make test-e2e"
+	@echo "  3. Run: make test-e2e  (or make test-e2e-vault)"
 
 # Download dependencies
 deps:
@@ -57,6 +58,34 @@ test-e2e: check-env
 	@echo "Tests completed. Cleaning up..."
 	docker-compose -f docker-compose.test.yml down -v
 
+# Run e2e tests with HashiCorp Vault
+test-e2e-vault: check-env
+	@echo "Building test containers (Vault backend)..."
+	docker-compose -f docker-compose.test-vault.yml build
+
+	@echo "Starting Vault server..."
+	docker-compose -f docker-compose.test-vault.yml up -d vault-server
+
+	@echo "Waiting for Vault to be ready..."
+	@timeout 30 bash -c 'until curl -sf http://localhost:8200/v1/sys/health 2>/dev/null; do sleep 1; done' || \
+		(docker-compose -f docker-compose.test-vault.yml logs vault-server && exit 1)
+
+	@echo "Seeding Vault with test credentials..."
+	docker-compose -f docker-compose.test-vault.yml up vault-seeder
+
+	@echo "Starting auth service..."
+	docker-compose -f docker-compose.test-vault.yml up -d github-auth-service
+
+	@echo "Waiting for auth service to be ready..."
+	@timeout 60 bash -c 'until curl -sf http://localhost:8080/health 2>/dev/null; do sleep 2; done' || \
+		(docker-compose -f docker-compose.test-vault.yml logs github-auth-service && exit 1)
+
+	@echo "Running e2e tests..."
+	docker-compose -f docker-compose.test-vault.yml up test-runner
+
+	@echo "Tests completed. Cleaning up..."
+	docker-compose -f docker-compose.test-vault.yml down -v
+
 # Check that .env exists
 check-env:
 	@if [ ! -f .env ]; then \
@@ -66,7 +95,8 @@ check-env:
 
 # Clean up all test containers and volumes
 clean:
-	docker-compose -f docker-compose.test.yml down -v --remove-orphans
+	docker-compose -f docker-compose.test.yml down -v --remove-orphans 2>/dev/null || true
+	docker-compose -f docker-compose.test-vault.yml down -v --remove-orphans 2>/dev/null || true
 	docker-compose down -v --remove-orphans 2>/dev/null || true
 
 # Run the service locally (requires .env with BW_SESSION)
diff --git a/README.md b/README.md
index aba777b..2938882 100644
--- a/README.md
+++ b/README.md
@@ -16,8 +16,9 @@ A REST API service that provides GitHub App authentication tokens and SSH commit
 │           │                                                 │
 │           ▼                                                 │
 │  ┌──────────────────┐                                      │
-│  │   Bitwarden CLI  │  (secrets fetched at startup,        │
-│  │                  │   session closed immediately)        │
+│  │ Secrets Backend  │  (secrets fetched at startup,        │
+│  │ Bitwarden or     │   session closed immediately)        │
+│  │ HashiCorp Vault  │                                      │
 │  └──────────────────┘                                      │
 └─────────────────────────────────────────────────────────────┘
 ```
@@ -27,8 +28,8 @@ A REST API service that provides GitHub App authentication tokens and SSH commit
 - **GitHub App Installation Tokens**: Agents request tokens for GitHub API/git operations
 - **SSH Commit Signing**: Sign commits using the same private key as the GitHub App
 - **Token-Based Auth**: Agents authenticate with pre-signed tokens (no Docker socket needed)
-- **Secrets from Bitwarden**: All credentials stored in a Bitwarden collection
-- **Fetch-at-Startup**: Secrets loaded once, Bitwarden session closed immediately
+- **Pluggable Secrets Backend**: Store credentials in Bitwarden/Vaultwarden or HashiCorp Vault
+- **Fetch-at-Startup**: Secrets loaded once, backend session closed immediately
 - **Helper Binaries**: Static Go binaries for git credential/signing helpers
 
 ## Quick Start
@@ -41,11 +42,12 @@ A REST API service that provides GitHub App authentication tokens and SSH commit
 4. Install the app on your repository/organization
 5. Note the App ID and Installation ID
 
-### 2. Store Credentials in Bitwarden
+### 2. Store Credentials
 
-Create a Bitwarden item in a collection with:
+Choose a secrets backend — Bitwarden/Vaultwarden or HashiCorp Vault.
+
+Each agent needs these fields:
 
-**Custom Fields:**
 | Field | Value |
 |-------|-------|
 | `app_id` | Your GitHub App ID |
@@ -53,14 +55,7 @@ Create a Bitwarden item in a collection with:
 | `agent_token` | Pre-signed token (see below) |
 | `identity_name` | Git commit author name |
 | `identity_email` | Git commit author email |
-| `private_key` | PEM-encoded private key (option 1) |
-
-**Attachments (alternative to field):**
-| File | Contents |
-|------|----------|
-| `private-key.pem` | GitHub App private key (option 2) |
-
-> **Note:** You can store the private key either as a custom field (`private_key`) or as an attachment. The field option is simpler; the attachment option keeps the key separate from other metadata.
+| `private_key` | PEM-encoded private key |
 
 **Generate agent token:**
 ```bash
@@ -68,10 +63,28 @@ Create a Bitwarden item in a collection with:
 echo -n "agent-name" | openssl dgst -sha256 -sign private-key.pem | base64 | tr -d '\n'
 ```
 
+#### Option A: Bitwarden / Vaultwarden
+
+Create a Bitwarden item in a collection with the fields above as custom fields. The private key can also be stored as an attachment named `private-key.pem`.
+
+#### Option B: HashiCorp Vault
+
+Store each agent as a KV v2 secret at `secret/agents/<agent-name>`:
+
+```bash
+vault kv put secret/agents/my-agent \
+    app_id=123456 \
+    installation_id=78901234 \
+    agent_token=$(echo -n "my-agent" | openssl dgst -sha256 -sign key.pem | base64 | tr -d '\n') \
+    private_key=@private-key.pem \
+    identity_name="My Agent" \
+    identity_email="my-agent@example.com"
+```
+
 ### 3. Run the Auth Service
 
+**With Bitwarden:**
 ```yaml
-# docker-compose.yml
 services:
   github-auth-service:
     image: ghcr.io/youruser/github-app-auth-container:latest
@@ -81,10 +94,21 @@ services:
       - BW_SERVER_URL=${BW_SERVER_URL:-}  # Optional: for Vaultwarden
     networks:
       - agent-network
+```
 
-networks:
-  agent-network:
-    driver: bridge
+**With HashiCorp Vault:**
+```yaml
+services:
+  github-auth-service:
+    image: ghcr.io/youruser/github-app-auth-container:latest
+    environment:
+      - SECRETS_BACKEND=vault
+      - VAULT_ADDR=https://vault.example.com
+      - VAULT_TOKEN=${VAULT_TOKEN}
+      # - VAULT_MOUNT_PATH=secret    # default
+      # - VAULT_BASE_PATH=agents     # default
+    networks:
+      - agent-network
 ```
 
 ### 4. Configure Agent Containers
@@ -116,245 +140,22 @@ services:
       - agent-network
 ```
 
-## API Reference
-
-### Health Check
-
-```
-GET /health
-```
-
-No authentication required.
-
-**Response:**
-```json
-{
-  "status": "healthy",
-  "agent_count": 3,
-  "version": "1.0.0"
-}
-```
-
-### Get Installation Token
+## Documentation
 
-```
-GET /api/v1/token
-POST /api/v1/token
-```
+- [Setting Up HashiCorp Vault](docs/vault.md) — configuring Vault as the secrets backend
+- [API Reference](docs/api.md) — all REST endpoints with request/response examples
+- [Configuration](docs/configuration.md) — environment variables for the auth service and agent containers
+- [Helper Binaries](docs/helpers.md) — git credential helper, SSH signing, and GitHub CLI wrapper
 
-**Headers:**
-- `X-Agent-Name`: Agent identifier
-- `X-Agent-Token`: Pre-signed authentication token
+## Contributing
 
-**Optional POST body** (for scoped tokens):
-```json
-{
-  "repositories": ["repo-name"],
-  "permissions": {"contents": "read"}
-}
-```
-
-**Response:**
-```json
-{
-  "token": "ghs_xxxxxxxxxxxx",
-  "expires_at": "2024-01-15T12:00:00Z",
-  "permissions": {"contents": "write"},
-  "repository_selection": "all"
-}
-```
-
-### Git Credentials
-
-```
-POST /api/v1/git-credentials
-```
-
-**Request:**
-```json
-{
-  "protocol": "https",
-  "host": "github.com",
-  "path": "owner/repo"
-}
-```
-
-**Response:**
-```json
-{
-  "protocol": "https",
-  "host": "github.com",
-  "username": "x-access-token",
-  "password": "ghs_xxxxxxxxxxxx"
-}
-```
-
-### Identity
-
-```
-GET /api/v1/identity
-```
-
-**Response:**
-```json
-{
-  "agent_name": "agent-claude-1",
-  "identity": {
-    "name": "Claude Agent 1",
-    "email": "claude-1@users.noreply.github.com"
-  },
-  "ssh_key_id": "SHA256:xxxxxxxx"
-}
-```
-
-### SSH Sign
-
-```
-POST /api/v1/ssh/sign
-```
-
-**Request:**
-```json
-{
-  "data": "data to sign",
-  "namespace": "git"
-}
-```
-
-**Response:**
-```json
-{
-  "signature": "-----BEGIN SSH SIGNATURE-----\n...",
-  "key_id": "SHA256:xxxxxxxx",
-  "signer_identity": {
-    "name": "Claude Agent 1",
-    "email": "claude-1@users.noreply.github.com"
-  }
-}
-```
-
-### SSH Public Key
-
-```
-GET /api/v1/ssh/public-key
-```
-
-**Response:**
-```json
-{
-  "public_key": "ssh-rsa AAAAB3...",
-  "key_id": "SHA256:xxxxxxxx",
-  "identity": {
-    "name": "Claude Agent 1",
-    "email": "claude-1@users.noreply.github.com"
-  }
-}
-```
-
-## Environment Variables
-
-### Auth Service
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `BW_SESSION` | Yes* | Bitwarden session token |
-| `BW_SESSION_FILE` | Yes* | Path to file containing session token |
-| `BW_COLLECTION_ID` | No** | Bitwarden collection ID |
-| `BW_COLLECTION_ID_FILE` | No** | Path to file containing collection ID |
-| `BW_SERVER_URL` | No | Bitwarden/Vaultwarden server URL |
-| `GITHUB_API_URL` | No | GitHub API URL (default: https://api.github.com) |
-| `LOG_LEVEL` | No | `INFO` or `DEBUG` (default: INFO) |
-| `PORT` | No | Server port (default: 8080) |
-
-*Either the variable or its `_FILE` variant is required.
-
-**If omitted or set to `PERSONAL_VAULT`, the service will load all items from the personal vault instead of a specific collection. This is useful for Vaultwarden setups where organization/collection creation is limited.
-
-### Agent Containers
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `GITHUB_AUTH_SERVICE` | Yes | URL of the auth service |
-| `AGENT_NAME` | Yes | Agent identifier (must match Bitwarden item name) |
-| `AGENT_TOKEN` | Yes | Pre-signed authentication token |
-
-## Helper Binaries
-
-The helpers image (`github-app-auth-container-helpers`) contains static Go binaries:
-
-| Binary | Purpose |
-|--------|---------|
-| `git-credential-github-app` | Git credential helper |
-| `git-ssh-sign` | SSH signing program for git |
-| `gh-github-app` | GitHub CLI wrapper with automatic auth |
-
-### Git Configuration
-
-```bash
-git config --global credential.helper github-app
-git config --global gpg.format ssh
-git config --global gpg.ssh.program git-ssh-sign
-```
-
-### GitHub CLI Wrapper
-
-The `gh-github-app` binary wraps the GitHub CLI, automatically fetching a token from the auth service:
-
-```bash
-# Use directly
-gh-github-app repo list
-gh-github-app pr create --title "Fix bug" --body "Description"
-
-# Or alias it
-alias gh='gh-github-app'
-gh issue list
-```
-
-Note: The `gh` CLI must be installed separately in your agent container.
-
-## Development
-
-### Prerequisites
-
-- Go 1.22+
-- Docker & Docker Compose
-- A Bitwarden/Vaultwarden account
-
-### Running Tests
-
-```bash
-# Copy and configure test environment
-cp .env.example .env
-# Edit .env with your test credentials
-
-# Run e2e tests with Vaultwarden
-./scripts/run-e2e-tests.sh
-```
-
-### Building
-
-```bash
-# Build auth service
-docker build -t github-app-auth-container .
-
-# Build helpers
-docker build -f Dockerfile.helpers -t github-app-auth-container-helpers .
-```
-
-### Publishing
-
-Tag with a semantic version to trigger the publish workflow:
-
-```bash
-git tag 1.0.0
-git push origin 1.0.0
-```
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, building, and testing instructions.
 
 ## Security Considerations
 
 - **Network Isolation**: The auth service should only be accessible from trusted agent containers via a private Docker network
 - **Token Verification**: Agent tokens are cryptographically signed with the GitHub App private key
-- **No Persistent Sessions**: Bitwarden session is closed immediately after loading secrets
+- **No Persistent Sessions**: Backend sessions are closed immediately after loading secrets
 - **Secrets in Memory**: Private keys are held in memory only, never written to disk in the container
 
 ## License
diff --git a/cmd/server/main.go b/cmd/server/main.go
index bd0c53f..2a35c6b 100644
--- a/cmd/server/main.go
+++ b/cmd/server/main.go
@@ -36,20 +36,39 @@ func main() {
 		os.Exit(1)
 	}
 
-	// Initialize Bitwarden backend
-	slog.Info("connecting to Bitwarden...")
-	bwBackend, err := secrets.NewBitwardenBackend(cfg.BitwardenServerURL)
+	// Initialize secrets backend
+	var backend secrets.SecretsBackend
+	var scope string
+	var err error
+
+	switch cfg.SecretsBackend {
+	case "bitwarden":
+		slog.Info("connecting to Bitwarden...")
+		backend, err = secrets.NewBitwardenBackend(cfg.BitwardenServerURL)
+		scope = cfg.CollectionID
+	case "vault":
+		slog.Info("connecting to HashiCorp Vault...")
+		backend, err = secrets.NewVaultBackend(cfg.VaultAddr, cfg.VaultMountPath)
+		scope = cfg.VaultBasePath
+	}
+
 	if err != nil {
-		slog.Error("failed to initialize Bitwarden backend", "error", err)
+		slog.Error("failed to initialize secrets backend",
+			"backend", cfg.SecretsBackend,
+			"error", err,
+		)
 		os.Exit(1)
 	}
 
 	// Create secrets store and load all agents
 	store := secrets.NewStore()
 	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
-	if err := store.LoadFromBitwarden(ctx, bwBackend, cfg.CollectionID); err != nil {
+	if err := store.LoadFromBackend(ctx, backend, scope); err != nil {
 		cancel()
-		slog.Error("failed to load secrets from Bitwarden", "error", err)
+		slog.Error("failed to load secrets",
+			"backend", cfg.SecretsBackend,
+			"error", err,
+		)
 		os.Exit(1)
 	}
 	cancel()
diff --git a/docker-compose.test-vault.yml b/docker-compose.test-vault.yml
new file mode 100644
index 0000000..863a9fa
--- /dev/null
+++ b/docker-compose.test-vault.yml
@@ -0,0 +1,116 @@
+version: '3.8'
+
+# E2E Test Stack (HashiCorp Vault backend)
+# Usage:
+#   1. Copy .env.example to .env and fill in test credentials
+#   2. Run: docker-compose -f docker-compose.test-vault.yml up --build --exit-code-from test-runner
+#   3. Check exit code of test-runner
+
+services:
+  # ==========================================================================
+  # HashiCorp Vault - Dev Server
+  # ==========================================================================
+  vault-server:
+    image: hashicorp/vault:1.15
+    container_name: test-vault-server
+    environment:
+      - VAULT_DEV_ROOT_TOKEN_ID=test-root-token
+      - VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200
+      - VAULT_ADDR=http://127.0.0.1:8200
+    ports:
+      - "8200:8200"
+    cap_add:
+      - IPC_LOCK
+    networks:
+      - test-network
+    healthcheck:
+      test: ["CMD", "vault", "status"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 3s
+
+  # ==========================================================================
+  # Vault Seeder - Populates Vault with test credentials
+  # ==========================================================================
+  vault-seeder:
+    build:
+      context: .
+      dockerfile: Dockerfile.test-seeder-vault
+    container_name: test-vault-seeder-hcv
+    environment:
+      - VAULT_ADDR=http://vault-server:8200
+      - VAULT_TOKEN=test-root-token
+      - TEST_GITHUB_APP_ID=${TEST_GITHUB_APP_ID}
+      - TEST_GITHUB_INSTALLATION_ID=${TEST_GITHUB_INSTALLATION_ID}
+      - TEST_GITHUB_PRIVATE_KEY_B64=${TEST_GITHUB_PRIVATE_KEY_B64}
+      - TEST_AGENT_NAME=${TEST_AGENT_NAME:-test-agent}
+      - TEST_AGENT_EMAIL=${TEST_AGENT_EMAIL:-test@example.com}
+    volumes:
+      - seeder-output:/output
+    networks:
+      - test-network
+    depends_on:
+      vault-server:
+        condition: service_healthy
+
+  # ==========================================================================
+  # GitHub Auth Service - The service under test (Vault backend)
+  # ==========================================================================
+  github-auth-service:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: test-github-auth-service-vault
+    environment:
+      - SECRETS_BACKEND=vault
+      - VAULT_ADDR=http://vault-server:8200
+      - VAULT_TOKEN=test-root-token
+      - VAULT_BASE_PATH=agents
+      - BW_COLLECTION_ID=unused
+      - LOG_LEVEL=DEBUG
+    ports:
+      - "8080:8080"
+    networks:
+      - test-network
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 5s
+      timeout: 3s
+      retries: 10
+      start_period: 10s
+    depends_on:
+      vault-seeder:
+        condition: service_completed_successfully
+      vault-server:
+        condition: service_healthy
+
+  # ==========================================================================
+  # Test Runner - Executes e2e tests (same as Bitwarden stack)
+  # ==========================================================================
+  test-runner:
+    build:
+      context: .
+      dockerfile: Dockerfile.test-runner
+    container_name: test-runner-vault
+    environment:
+      - GITHUB_AUTH_SERVICE=http://github-auth-service:8080
+      - TEST_AGENT_NAME=${TEST_AGENT_NAME:-test-agent}
+      - TEST_AGENT_TOKEN_FILE=/output/agent_token.txt
+      - TEST_GITHUB_API_ENABLED=${TEST_GITHUB_API_ENABLED:-false}
+    volumes:
+      - seeder-output:/output:ro
+      - test-results:/app/test-results
+    networks:
+      - test-network
+    depends_on:
+      github-auth-service:
+        condition: service_healthy
+
+networks:
+  test-network:
+    driver: bridge
+
+volumes:
+  seeder-output:
+  test-results:
diff --git a/docker-compose.yml b/docker-compose.yml
index 8edfd73..b2cd6c7 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -2,12 +2,20 @@ version: '3.8'
 
 # Production deployment configuration
 #
-# Required environment variables:
+# Secrets Backend: Set SECRETS_BACKEND to "bitwarden" (default) or "vault"
+#
+# Bitwarden backend required environment variables:
 #   BW_SESSION - Bitwarden session token
 #   BW_COLLECTION_ID - Bitwarden collection containing agent items
 #
+# HashiCorp Vault backend required environment variables:
+#   VAULT_ADDR - Vault server address
+#   VAULT_TOKEN - Vault authentication token
+#
 # Optional environment variables:
 #   BW_SERVER_URL - Bitwarden/Vaultwarden server URL (default: bitwarden.com)
+#   VAULT_MOUNT_PATH - Vault KV v2 mount path (default: secret)
+#   VAULT_BASE_PATH - Vault path for agent secrets (default: agents)
 #   GITHUB_API_URL - GitHub API URL (default: https://api.github.com)
 #   LOG_LEVEL - Logging level: INFO or DEBUG (default: INFO)
 
@@ -18,11 +26,19 @@ services:
       dockerfile: Dockerfile
     container_name: github-auth-service
     environment:
-      # Required
-      - BW_SESSION=${BW_SESSION}
-      - BW_COLLECTION_ID=${BW_COLLECTION_ID}
-      # Optional
+      # Secrets backend selection (uncomment one option)
+      # Option 1: Bitwarden (default)
+      - SECRETS_BACKEND=${SECRETS_BACKEND:-bitwarden}
+      - BW_SESSION=${BW_SESSION:-}
+      - BW_COLLECTION_ID=${BW_COLLECTION_ID:-}
       - BW_SERVER_URL=${BW_SERVER_URL:-}
+      # Option 2: HashiCorp Vault (uncomment and set these instead)
+      # - SECRETS_BACKEND=vault
+      - VAULT_ADDR=${VAULT_ADDR:-}
+      - VAULT_TOKEN=${VAULT_TOKEN:-}
+      # - VAULT_MOUNT_PATH=secret
+      # - VAULT_BASE_PATH=agents
+      # Common
       - GITHUB_API_URL=${GITHUB_API_URL:-https://api.github.com}
       - LOG_LEVEL=${LOG_LEVEL:-INFO}
     networks:
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..be975fe
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,136 @@
+# API Reference
+
+All `/api/v1/*` endpoints require `X-Agent-Name` and `X-Agent-Token` headers.
+
+## Health Check
+
+```
+GET /health
+```
+
+No authentication required.
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "agent_count": 3,
+  "version": "1.0.0"
+}
+```
+
+## Get Installation Token
+
+```
+GET /api/v1/token
+POST /api/v1/token
+```
+
+**Headers:**
+- `X-Agent-Name`: Agent identifier
+- `X-Agent-Token`: Pre-signed authentication token
+
+**Optional POST body** (for scoped tokens):
+```json
+{
+  "repositories": ["repo-name"],
+  "permissions": {"contents": "read"}
+}
+```
+
+**Response:**
+```json
+{
+  "token": "ghs_xxxxxxxxxxxx",
+  "expires_at": "2024-01-15T12:00:00Z",
+  "permissions": {"contents": "write"},
+  "repository_selection": "all"
+}
+```
+
+## Git Credentials
+
+```
+POST /api/v1/git-credentials
+```
+
+**Request:**
+```json
+{
+  "protocol": "https",
+  "host": "github.com",
+  "path": "owner/repo"
+}
+```
+
+**Response:**
+```json
+{
+  "protocol": "https",
+  "host": "github.com",
+  "username": "x-access-token",
+  "password": "ghs_xxxxxxxxxxxx"
+}
+```
+
+## Identity
+
+```
+GET /api/v1/identity
+```
+
+**Response:**
+```json
+{
+  "agent_name": "agent-claude-1",
+  "identity": {
+    "name": "Claude Agent 1",
+    "email": "claude-1@users.noreply.github.com"
+  },
+  "ssh_key_id": "SHA256:xxxxxxxx"
+}
+```
+
+## SSH Sign
+
+```
+POST /api/v1/ssh/sign
+```
+
+**Request:**
+```json
+{
+  "data": "data to sign",
+  "namespace": "git"
+}
+```
+
+**Response:**
+```json
+{
+  "signature": "-----BEGIN SSH SIGNATURE-----\n...",
+  "key_id": "SHA256:xxxxxxxx",
+  "signer_identity": {
+    "name": "Claude Agent 1",
+    "email": "claude-1@users.noreply.github.com"
+  }
+}
+```
+
+## SSH Public Key
+
+```
+GET /api/v1/ssh/public-key
+```
+
+**Response:**
+```json
+{
+  "public_key": "ssh-rsa AAAAB3...",
+  "key_id": "SHA256:xxxxxxxx",
+  "identity": {
+    "name": "Claude Agent 1",
+    "email": "claude-1@users.noreply.github.com"
+  }
+}
+```
diff --git a/docs/configuration.md b/docs/configuration.md
new file mode 100644
index 0000000..11c3b33
--- /dev/null
+++ b/docs/configuration.md
@@ -0,0 +1,46 @@
+# Configuration
+
+All configuration is via environment variables. There are no config files.
+
+## Auth Service — Common
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `SECRETS_BACKEND` | No | `bitwarden` | Secrets backend: `bitwarden` or `vault` |
+| `GITHUB_API_URL` | No | `https://api.github.com` | GitHub API URL |
+| `LOG_LEVEL` | No | `INFO` | `INFO` or `DEBUG` |
+| `PORT` | No | `8080` | Server port |
+
+## Auth Service — Bitwarden Backend
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `BW_SESSION` | Yes* | Bitwarden session token |
+| `BW_SESSION_FILE` | Yes* | Path to file containing session token |
+| `BW_COLLECTION_ID` | No** | Bitwarden collection ID |
+| `BW_COLLECTION_ID_FILE` | No** | Path to file containing collection ID |
+| `BW_SERVER_URL` | No | Bitwarden/Vaultwarden server URL |
+
+\*Either the variable or its `_FILE` variant is required.
+
+\*\*If omitted or set to `PERSONAL_VAULT`, loads all items from the personal vault.
+
+## Auth Service — HashiCorp Vault Backend
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `VAULT_ADDR` | Yes | — | Vault server address |
+| `VAULT_TOKEN` | Yes* | — | Vault authentication token |
+| `VAULT_TOKEN_FILE` | Yes* | — | Path to file containing Vault token |
+| `VAULT_MOUNT_PATH` | No | `secret` | KV v2 mount path |
+| `VAULT_BASE_PATH` | No | `agents` | Base path for agent secrets |
+
+\*Either `VAULT_TOKEN` or `VAULT_TOKEN_FILE` is required.
+
+## Agent Containers
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GITHUB_AUTH_SERVICE` | Yes | URL of the auth service |
+| `AGENT_NAME` | Yes | Agent identifier (must match item name in secrets backend) |
+| `AGENT_TOKEN` | Yes | Pre-signed authentication token |
diff --git a/docs/helpers.md b/docs/helpers.md
new file mode 100644
index 0000000..37e59b9
--- /dev/null
+++ b/docs/helpers.md
@@ -0,0 +1,48 @@
+# Helper Binaries
+
+The helpers image (`github-app-auth-container-helpers`) contains static Go binaries that agent containers use to authenticate with GitHub via the auth service.
+
+| Binary | Purpose |
+|--------|---------|
+| `git-credential-github-app` | Git credential helper |
+| `git-ssh-sign` | SSH signing program for git |
+| `gh-github-app` | GitHub CLI wrapper with automatic auth |
+
+## Installation
+
+Copy the binaries into your agent container from the helpers image:
+
+```dockerfile
+FROM ghcr.io/youruser/github-app-auth-container-helpers:latest AS helpers
+
+FROM python:3.12-slim
+COPY --from=helpers /usr/local/bin/git-* /usr/local/bin/
+COPY --from=helpers /usr/local/bin/gh-* /usr/local/bin/
+```
+
+## Git Configuration
+
+```bash
+git config --global credential.helper github-app
+git config --global gpg.format ssh
+git config --global gpg.ssh.program git-ssh-sign
+git config --global commit.gpgsign true
+```
+
+With these settings, `git push`, `git pull`, and `git commit -S` automatically use the auth service for credentials and signing.
+
+## GitHub CLI Wrapper
+
+The `gh-github-app` binary wraps the GitHub CLI, automatically fetching a token from the auth service:
+
+```bash
+# Use directly
+gh-github-app repo list
+gh-github-app pr create --title "Fix bug" --body "Description"
+
+# Or alias it
+alias gh='gh-github-app'
+gh issue list
+```
+
+Note: The `gh` CLI must be installed separately in your agent container.
diff --git a/docs/vault.md b/docs/vault.md
new file mode 100644
index 0000000..1450d43
--- /dev/null
+++ b/docs/vault.md
@@ -0,0 +1,113 @@
+# Setting Up HashiCorp Vault
+
+This guide walks through configuring HashiCorp Vault as the secrets backend.
+
+## Prerequisites
+
+- A running Vault server with the KV v2 secrets engine enabled
+- A Vault token with read/list access to the agent secrets path
+- The `vault` CLI (for seeding secrets)
+
+For local development, you can run a dev server:
+
+```bash
+vault server -dev -dev-root-token-id=my-root-token
+export VAULT_ADDR=http://127.0.0.1:8200
+export VAULT_TOKEN=my-root-token
+```
+
+The dev server automatically enables a KV v2 engine at `secret/`.
+
+## Secret Structure
+
+Each agent is stored as a KV v2 secret at `<mount>/<base_path>/<agent-name>`. With the defaults (`secret` mount, `agents` base path), the path is:
+
+```
+secret/agents/<agent-name>
+```
+
+Required fields:
+
+| Field | Description |
+|-------|-------------|
+| `app_id` | GitHub App ID |
+| `installation_id` | GitHub App Installation ID |
+| `agent_token` | RSA-SHA256 signature of the agent name, base64-encoded |
+| `private_key` | PEM-encoded RSA private key |
+| `identity_name` | Git commit author name |
+| `identity_email` | Git commit author email |
+
+## Creating Agent Secrets
+
+```bash
+# 1. Generate the agent token (sign agent name with the App's private key)
+AGENT_TOKEN=$(echo -n "my-agent" | openssl dgst -sha256 -sign private-key.pem | base64 | tr -d '\n')
+
+# 2. Write the secret to Vault (@ reads the file contents directly)
+vault kv put secret/agents/my-agent \
+    app_id="123456" \
+    installation_id="78901234" \
+    agent_token="${AGENT_TOKEN}" \
+    private_key=@private-key.pem \
+    identity_name="My Agent" \
+    identity_email="my-agent@users.noreply.github.com"
+
+# 3. Verify it was written
+vault kv get secret/agents/my-agent
+```
+
+To add more agents, repeat for each agent name. They can share the same GitHub App (same `app_id`, `installation_id`, and `private_key`) but should have unique names and tokens.
+
+## Vault Token Policy
+
+If you're not using the root token, create a policy with read and list access:
+
+```hcl
+# vault-policy.hcl
+path "secret/data/agents/*" {
+  capabilities = ["read"]
+}
+
+path "secret/metadata/agents/*" {
+  capabilities = ["read", "list"]
+}
+```
+
+```bash
+vault policy write github-auth vault-policy.hcl
+vault token create -policy=github-auth
+```
+
+## Running the Auth Service with Vault
+
+```yaml
+services:
+  github-auth-service:
+    image: ghcr.io/youruser/github-app-auth-container:latest
+    environment:
+      - SECRETS_BACKEND=vault
+      - VAULT_ADDR=https://vault.example.com
+      - VAULT_TOKEN=${VAULT_TOKEN}
+      # - VAULT_TOKEN_FILE=/run/secrets/vault-token  # alternative: read from file
+      # - VAULT_MOUNT_PATH=secret                    # default
+      # - VAULT_BASE_PATH=agents                     # default
+    networks:
+      - agent-network
+```
+
+The service connects to Vault at startup, loads all agent secrets from the configured path, then operates entirely from memory. The Vault token is only used during startup.
+
+## Custom Mount Path
+
+If your KV v2 engine is mounted at a non-default path:
+
+```bash
+# Enable KV v2 at a custom path
+vault secrets enable -path=github-apps kv-v2
+
+# Write secrets there
+vault kv put github-apps/agents/my-agent app_id=... ...
+
+# Configure the auth service
+# VAULT_MOUNT_PATH=github-apps
+```
diff --git a/go.mod b/go.mod
index b6412c3..7e2f88f 100644
--- a/go.mod
+++ b/go.mod
@@ -1,53 +1,33 @@
 module github.com/boblangley/github-app-auth-container
 
-go 1.22
+go 1.23.0
 
 require (
-	github.com/docker/docker v27.0.3+incompatible
 	github.com/go-chi/chi/v5 v5.1.0
 	github.com/golang-jwt/jwt/v5 v5.2.1
-	github.com/spf13/viper v1.19.0
-	golang.org/x/crypto v0.25.0
+	github.com/hashicorp/vault/api v1.22.0
+	golang.org/x/crypto v0.40.0
 )
 
 require (
-	github.com/Microsoft/go-winio v0.6.2 // indirect
-	github.com/distribution/reference v0.6.0 // indirect
-	github.com/docker/go-connections v0.5.0 // indirect
-	github.com/docker/go-units v0.5.0 // indirect
-	github.com/felixge/httpsnoop v1.0.4 // indirect
-	github.com/fsnotify/fsnotify v1.7.0 // indirect
-	github.com/go-logr/logr v1.4.2 // indirect
-	github.com/go-logr/stdr v1.2.2 // indirect
-	github.com/gogo/protobuf v1.3.2 // indirect
-	github.com/hashicorp/hcl v1.0.0 // indirect
-	github.com/magiconair/properties v1.8.7 // indirect
+	github.com/cenkalti/backoff/v4 v4.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/go-jose/go-jose/v4 v4.1.1 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-cleanhttp v0.5.2 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
+	github.com/hashicorp/go-retryablehttp v0.7.8 // indirect
+	github.com/hashicorp/go-rootcerts v1.0.2 // indirect
+	github.com/hashicorp/go-secure-stdlib/parseutil v0.2.0 // indirect
+	github.com/hashicorp/go-secure-stdlib/strutil v0.1.2 // indirect
+	github.com/hashicorp/go-sockaddr v1.0.7 // indirect
+	github.com/hashicorp/hcl v1.0.1-vault-7 // indirect
+	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
-	github.com/moby/docker-image-spec v1.3.1 // indirect
-	github.com/moby/term v0.5.0 // indirect
-	github.com/morikuni/aec v1.0.0 // indirect
-	github.com/opencontainers/go-digest v1.0.0 // indirect
-	github.com/opencontainers/image-spec v1.1.0 // indirect
-	github.com/pelletier/go-toml/v2 v2.2.2 // indirect
-	github.com/pkg/errors v0.9.1 // indirect
-	github.com/sagikazarmark/locafero v0.6.0 // indirect
-	github.com/sagikazarmark/slog-shim v0.1.0 // indirect
-	github.com/sourcegraph/conc v0.3.0 // indirect
-	github.com/spf13/afero v1.11.0 // indirect
-	github.com/spf13/cast v1.6.0 // indirect
-	github.com/spf13/pflag v1.0.5 // indirect
-	github.com/subosito/gotenv v1.6.0 // indirect
-	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.53.0 // indirect
-	go.opentelemetry.io/otel v1.28.0 // indirect
-	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.28.0 // indirect
-	go.opentelemetry.io/otel/metric v1.28.0 // indirect
-	go.opentelemetry.io/otel/sdk v1.28.0 // indirect
-	go.opentelemetry.io/otel/trace v1.28.0 // indirect
-	go.uber.org/multierr v1.11.0 // indirect
-	golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect
-	golang.org/x/sys v0.22.0 // indirect
-	golang.org/x/text v0.16.0 // indirect
-	gopkg.in/ini.v1 v1.67.0 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
-	gotest.tools/v3 v3.5.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/ryanuber/go-glob v1.0.0 // indirect
+	golang.org/x/net v0.42.0 // indirect
+	golang.org/x/sys v0.34.0 // indirect
+	golang.org/x/text v0.27.0 // indirect
+	golang.org/x/time v0.12.0 // indirect
 )
diff --git a/go.sum b/go.sum
index e69de29..67094b5 100644
--- a/go.sum
+++ b/go.sum
@@ -0,0 +1,66 @@
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fatih/color v1.18.0 h1:S8gINlzdQ840/4pfAwic/ZE0djQEH3wM94VfqLTZcOM=
+github.com/fatih/color v1.18.0/go.mod h1:4FelSpRwEGDpQ12mAdzqdOukCy4u8WUtOY6lkT/6HfU=
+github.com/go-chi/chi/v5 v5.1.0 h1:acVI1TYaD+hhedDJ3r54HyA6sExp3HfXq7QWEEY/xMw=
+github.com/go-chi/chi/v5 v5.1.0/go.mod h1:DslCQbL2OYiznFReuXYUmQ2hGd1aDpCnlMNITLSKoi8=
+github.com/go-jose/go-jose/v4 v4.1.1 h1:JYhSgy4mXXzAdF3nUx3ygx347LRXJRrpgyU3adRmkAI=
+github.com/go-jose/go-jose/v4 v4.1.1/go.mod h1:BdsZGqgdO3b6tTc6LSE56wcDbMMLuPsw5d4ZD5f94kA=
+github.com/go-test/deep v1.1.1 h1:0r/53hagsehfO4bzD2Pgr/+RgHqhmf+k1Bpse2cTu1U=
+github.com/go-test/deep v1.1.1/go.mod h1:5C2ZWiW0ErCdrYzpqxLbTX7MG14M9iiw8DgHncVwcsE=
+github.com/golang-jwt/jwt/v5 v5.2.1 h1:OuVbFODueb089Lh128TAcimifWaLhJwVflnrgM17wHk=
+github.com/golang-jwt/jwt/v5 v5.2.1/go.mod h1:pqrtFR0X4osieyHYxtmOUWsAWrfe1Q5UVIyoH402zdk=
+github.com/hashicorp/errwrap v1.0.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/errwrap v1.1.0 h1:OxrOeh75EUXMY8TBjag2fzXGZ40LB6IKw45YeGUDY2I=
+github.com/hashicorp/errwrap v1.1.0/go.mod h1:YH+1FKiLXxHSkmPseP+kNlulaMuP3n2brvKWEqk/Jc4=
+github.com/hashicorp/go-cleanhttp v0.5.2 h1:035FKYIWjmULyFRBKPs8TBQoi0x6d9G4xc9neXJWAZQ=
+github.com/hashicorp/go-cleanhttp v0.5.2/go.mod h1:kO/YDlP8L1346E6Sodw+PrpBSV4/SoxCXGY6BqNFT48=
+github.com/hashicorp/go-hclog v1.6.3 h1:Qr2kF+eVWjTiYmU7Y31tYlP1h0q/X3Nl3tPGdaB11/k=
+github.com/hashicorp/go-hclog v1.6.3/go.mod h1:W4Qnvbt70Wk/zYJryRzDRU/4r0kIg0PVHBcfoyhpF5M=
+github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo=
+github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM=
+github.com/hashicorp/go-retryablehttp v0.7.8 h1:ylXZWnqa7Lhqpk0L1P1LzDtGcCR0rPVUrx/c8Unxc48=
+github.com/hashicorp/go-retryablehttp v0.7.8/go.mod h1:rjiScheydd+CxvumBsIrFKlx3iS0jrZ7LvzFGFmuKbw=
+github.com/hashicorp/go-rootcerts v1.0.2 h1:jzhAVGtqPKbwpyCPELlgNWhE1znq+qwJtW5Oi2viEzc=
+github.com/hashicorp/go-rootcerts v1.0.2/go.mod h1:pqUvnprVnM5bf7AOirdbb01K4ccR319Vf4pU3K5EGc8=
+github.com/hashicorp/go-secure-stdlib/parseutil v0.2.0 h1:U+kC2dOhMFQctRfhK0gRctKAPTloZdMU5ZJxaesJ/VM=
+github.com/hashicorp/go-secure-stdlib/parseutil v0.2.0/go.mod h1:Ll013mhdmsVDuoIXVfBtvgGJsXDYkTw1kooNcoCXuE0=
+github.com/hashicorp/go-secure-stdlib/strutil v0.1.2 h1:kes8mmyCpxJsI7FTwtzRqEy9CdjCtrXrXGuOpxEA7Ts=
+github.com/hashicorp/go-secure-stdlib/strutil v0.1.2/go.mod h1:Gou2R9+il93BqX25LAKCLuM+y9U2T4hlwvT1yprcna4=
+github.com/hashicorp/go-sockaddr v1.0.7 h1:G+pTkSO01HpR5qCxg7lxfsFEZaG+C0VssTy/9dbT+Fw=
+github.com/hashicorp/go-sockaddr v1.0.7/go.mod h1:FZQbEYa1pxkQ7WLpyXJ6cbjpT8q0YgQaK/JakXqGyWw=
+github.com/hashicorp/hcl v1.0.1-vault-7 h1:ag5OxFVy3QYTFTJODRzTKVZ6xvdfLLCA1cy/Y6xGI0I=
+github.com/hashicorp/hcl v1.0.1-vault-7/go.mod h1:XYhtn6ijBSAj6n4YqAaf7RBPS4I06AItNorpy+MoQNM=
+github.com/hashicorp/vault/api v1.22.0 h1:+HYFquE35/B74fHoIeXlZIP2YADVboaPjaSicHEZiH0=
+github.com/hashicorp/vault/api v1.22.0/go.mod h1:IUZA2cDvr4Ok3+NtK2Oq/r+lJeXkeCrHRmqdyWfpmGM=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mitchellh/go-homedir v1.1.0 h1:lukF9ziXFxDFPkA1vsr5zpc1XuPDn/wFntq5mG+4E0Y=
+github.com/mitchellh/go-homedir v1.1.0/go.mod h1:SfyaCUpYCn1Vlf4IUYiD9fPX4A5wJrkLzIz1N1q0pr0=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/ryanuber/go-glob v1.0.0 h1:iQh3xXAumdQ+4Ufa5b25cRpC5TYKlno6hsv6Cb3pkBk=
+github.com/ryanuber/go-glob v1.0.0/go.mod h1:807d1WSdnB0XRJzKNil9Om6lcp/3a0v4qIHxIXzX/Yc=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+golang.org/x/crypto v0.40.0 h1:r4x+VvoG5Fm+eJcxMaY8CQM7Lb0l1lsmjGBQ6s8BfKM=
+golang.org/x/crypto v0.40.0/go.mod h1:Qr1vMER5WyS2dfPHAlsOj01wgLbsyWtFn/aY+5+ZdxY=
+golang.org/x/net v0.42.0 h1:jzkYrhi3YQWD6MLBJcsklgQsoAcw89EcZbJw8Z614hs=
+golang.org/x/net v0.42.0/go.mod h1:FF1RA5d3u7nAYA4z2TkclSCKh68eSXtiFwcWQpPXdt8=
+golang.org/x/sys v0.34.0 h1:H5Y5sJ2L2JRdyv7ROF1he/lPdvFsd0mJHFw2ThKHxLA=
+golang.org/x/sys v0.34.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/term v0.33.0 h1:NuFncQrRcaRvVmgRkvM3j/F00gWIAlcmlB8ACEKmGIg=
+golang.org/x/term v0.33.0/go.mod h1:s18+ql9tYWp1IfpV9DmCtQDDSRBUjKaw9M1eAv5UeF0=
+golang.org/x/text v0.27.0 h1:4fGWRpyh641NLlecmyl4LOe6yDdfaYNrGb2zdfo4JV4=
+golang.org/x/text v0.27.0/go.mod h1:1D28KMCvyooCX9hBiosv5Tz/+YLxj0j7XhWjpSUF7CU=
+golang.org/x/time v0.12.0 h1:ScB/8o8olJvc+CQPWrK3fPZNfh7qgwCrY0zJmoEQLSE=
+golang.org/x/time v0.12.0/go.mod h1:CDIdPxbZBQxdj6cxyCIdrNogrJKMJ7pr37NYpMcMDSg=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
diff --git a/internal/config/config.go b/internal/config/config.go
index d5fcd08..419d1e3 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -2,6 +2,7 @@ package config
 
 import (
 	"bytes"
+	"fmt"
 	"os"
 	"strconv"
 	"time"
@@ -14,10 +15,18 @@ type Config struct {
 	ReadTimeout  time.Duration
 	WriteTimeout time.Duration
 
-	// Bitwarden settings
+	// Secrets backend selection: "bitwarden" (default) or "vault"
+	SecretsBackend string
+
+	// Bitwarden settings (used when SecretsBackend == "bitwarden")
 	BitwardenServerURL string
 	CollectionID       string
 
+	// HashiCorp Vault settings (used when SecretsBackend == "vault")
+	VaultAddr      string
+	VaultMountPath string
+	VaultBasePath  string
+
 	// GitHub API settings
 	GitHubAPIURL string
 
@@ -31,8 +40,12 @@ func Load() *Config {
 		Port:               getEnvInt("PORT", 8080),
 		ReadTimeout:        getEnvDuration("READ_TIMEOUT", 30*time.Second),
 		WriteTimeout:       getEnvDuration("WRITE_TIMEOUT", 30*time.Second),
+		SecretsBackend:     getEnvString("SECRETS_BACKEND", "bitwarden"),
 		BitwardenServerURL: os.Getenv("BW_SERVER_URL"),
 		CollectionID:       getEnvOrFile("BW_COLLECTION_ID", "BW_COLLECTION_ID_FILE"),
+		VaultAddr:          os.Getenv("VAULT_ADDR"),
+		VaultMountPath:     getEnvString("VAULT_MOUNT_PATH", "secret"),
+		VaultBasePath:      getEnvString("VAULT_BASE_PATH", "agents"),
 		GitHubAPIURL:       getEnvString("GITHUB_API_URL", "https://api.github.com"),
 		LogLevel:           getEnvString("LOG_LEVEL", "INFO"),
 	}
@@ -56,8 +69,18 @@ func getEnvOrFile(envKey, fileEnvKey string) string {
 
 // Validate checks that required configuration is present.
 func (c *Config) Validate() error {
-	if c.CollectionID == "" {
-		return &ConfigError{Field: "BW_COLLECTION_ID", Message: "required"}
+	switch c.SecretsBackend {
+	case "bitwarden":
+		// CollectionID is optional — empty means load all items from personal vault
+	case "vault":
+		if c.VaultBasePath == "" {
+			return &ConfigError{Field: "VAULT_BASE_PATH", Message: "required when SECRETS_BACKEND=vault"}
+		}
+	default:
+		return &ConfigError{
+			Field:   "SECRETS_BACKEND",
+			Message: fmt.Sprintf("unsupported backend: %s (must be 'bitwarden' or 'vault')", c.SecretsBackend),
+		}
 	}
 	return nil
 }
diff --git a/internal/secrets/backend.go b/internal/secrets/backend.go
new file mode 100644
index 0000000..5697d95
--- /dev/null
+++ b/internal/secrets/backend.go
@@ -0,0 +1,46 @@
+package secrets
+
+import (
+	"context"
+	"errors"
+)
+
+// SecretsBackend abstracts a secrets storage provider.
+// Implementations include Bitwarden/Vaultwarden and HashiCorp Vault.
+type SecretsBackend interface {
+	// GetItems retrieves all agent items from the backend.
+	// The scope parameter is backend-specific:
+	//   - Bitwarden: collectionID (or "PERSONAL_VAULT" / empty for all items)
+	//   - Vault: base path in KV engine (e.g., "agents")
+	GetItems(ctx context.Context, scope string) ([]*Item, error)
+
+	// GetAttachment retrieves attachment data by item ID and filename.
+	// Backends that don't support attachments return ErrAttachmentsNotSupported.
+	GetAttachment(ctx context.Context, itemID, attachmentName string) ([]byte, error)
+
+	// Close performs cleanup (lock session, revoke token, etc.).
+	// Called after all secrets have been loaded.
+	Close(ctx context.Context) error
+
+	// Name returns a human-readable backend name for logging.
+	Name() string
+}
+
+// ErrAttachmentsNotSupported is returned by backends that don't support attachments.
+var ErrAttachmentsNotSupported = errors.New("attachments not supported by this backend")
+
+// Item represents a secrets item with fields and attachments.
+type Item struct {
+	ID          string
+	Name        string
+	Fields      map[string]string
+	Attachments []AttachmentInfo
+	Notes       string
+}
+
+// AttachmentInfo holds metadata about an attachment.
+type AttachmentInfo struct {
+	ID       string
+	FileName string
+	Size     int64
+}
diff --git a/internal/secrets/bitwarden.go b/internal/secrets/bitwarden.go
index f86f316..a270266 100644
--- a/internal/secrets/bitwarden.go
+++ b/internal/secrets/bitwarden.go
@@ -39,21 +39,8 @@ type bwAttachment struct {
 	Size     int64  `json:"size"`
 }
 
-// Item represents a secrets item with fields and attachments.
-type Item struct {
-	ID          string
-	Name        string
-	Fields      map[string]string
-	Attachments []AttachmentInfo
-	Notes       string
-}
-
-// AttachmentInfo holds metadata about an attachment.
-type AttachmentInfo struct {
-	ID       string
-	FileName string
-	Size     int64
-}
+// Compile-time interface check.
+var _ SecretsBackend = (*BitwardenBackend)(nil)
 
 // NewBitwardenBackend creates a new Bitwarden secrets backend.
 func NewBitwardenBackend(serverURL string) (*BitwardenBackend, error) {
@@ -296,3 +283,22 @@ func (b *BitwardenBackend) GetAttachment(ctx context.Context, itemID, attachment
 
 	return data, nil
 }
+
+// GetItems retrieves all agent items, delegating to ListAllItems or GetCollectionItems
+// based on the scope parameter (Bitwarden collection ID).
+func (b *BitwardenBackend) GetItems(ctx context.Context, scope string) ([]*Item, error) {
+	if scope == "PERSONAL_VAULT" || scope == "" {
+		return b.ListAllItems(ctx)
+	}
+	return b.GetCollectionItems(ctx, scope)
+}
+
+// Close locks the Bitwarden vault and clears the session.
+func (b *BitwardenBackend) Close(ctx context.Context) error {
+	return b.Logout(ctx)
+}
+
+// Name returns the backend name for logging.
+func (b *BitwardenBackend) Name() string {
+	return "bitwarden"
+}
diff --git a/internal/secrets/store.go b/internal/secrets/store.go
index cd258c6..6df218a 100644
--- a/internal/secrets/store.go
+++ b/internal/secrets/store.go
@@ -16,7 +16,7 @@ import (
 
 // AgentSecrets holds all secrets for a single agent, loaded at startup.
 type AgentSecrets struct {
-	Name           string          // Agent name (from Bitwarden item name)
+	Name           string          // Agent name (from secrets backend item name)
 	AppID          string          // GitHub App ID
 	InstallationID string          // GitHub App Installation ID
 	PrivateKey     *rsa.PrivateKey // Parsed RSA private key
@@ -45,26 +45,17 @@ func NewStore() *Store {
 	}
 }
 
-// LoadFromBitwarden fetches all agent secrets from a Bitwarden collection,
-// stores them in memory, and logs out the session.
-func (s *Store) LoadFromBitwarden(ctx context.Context, backend *BitwardenBackend, collectionID string) error {
-	slog.Info("loading secrets from Bitwarden collection", "collection_id", collectionID)
+// LoadFromBackend fetches all agent secrets from the given backend,
+// stores them in memory, and closes the backend session.
+func (s *Store) LoadFromBackend(ctx context.Context, backend SecretsBackend, scope string) error {
+	slog.Info("loading secrets from backend", "backend", backend.Name(), "scope", scope)
 
-	var items []*Item
-	var err error
-
-	// Handle personal vault (no collection) vs organization collection
-	if collectionID == "PERSONAL_VAULT" || collectionID == "" {
-		slog.Info("using personal vault - listing all items")
-		items, err = backend.ListAllItems(ctx)
-	} else {
-		items, err = backend.GetCollectionItems(ctx, collectionID)
-	}
+	items, err := backend.GetItems(ctx, scope)
 	if err != nil {
-		return fmt.Errorf("failed to get items: %w", err)
+		return fmt.Errorf("failed to get items from %s: %w", backend.Name(), err)
 	}
 
-	slog.Info("found items in collection", "count", len(items))
+	slog.Info("found items", "count", len(items), "backend", backend.Name())
 
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -87,23 +78,22 @@ func (s *Store) LoadFromBitwarden(ctx context.Context, backend *BitwardenBackend
 		)
 	}
 
-	// Logout the Bitwarden session
-	if err := backend.Logout(ctx); err != nil {
-		slog.Warn("failed to logout Bitwarden session", "error", err)
-		// Don't fail - secrets are already loaded
+	// Close the backend session
+	if err := backend.Close(ctx); err != nil {
+		slog.Warn("failed to close backend session", "backend", backend.Name(), "error", err)
 	} else {
-		slog.Info("Bitwarden session closed")
+		slog.Info("backend session closed", "backend", backend.Name())
 	}
 
 	if len(s.agents) == 0 {
-		return fmt.Errorf("no agents loaded from collection")
+		return fmt.Errorf("no agents loaded from %s", backend.Name())
 	}
 
 	return nil
 }
 
-// parseAgentItem converts a Bitwarden item into AgentSecrets.
-func (s *Store) parseAgentItem(ctx context.Context, backend *BitwardenBackend, item *Item) (*AgentSecrets, error) {
+// parseAgentItem converts a secrets backend item into AgentSecrets.
+func (s *Store) parseAgentItem(ctx context.Context, backend SecretsBackend, item *Item) (*AgentSecrets, error) {
 	agent := &AgentSecrets{
 		Name: item.Name,
 	}
diff --git a/internal/secrets/vault.go b/internal/secrets/vault.go
new file mode 100644
index 0000000..3c94c13
--- /dev/null
+++ b/internal/secrets/vault.go
@@ -0,0 +1,149 @@
+package secrets
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"strings"
+
+	vault "github.com/hashicorp/vault/api"
+)
+
+// VaultBackend implements SecretsBackend using HashiCorp Vault KV v2.
+type VaultBackend struct {
+	client    *vault.Client
+	mountPath string // KV v2 engine mount path (e.g., "secret")
+}
+
+// Compile-time interface check.
+var _ SecretsBackend = (*VaultBackend)(nil)
+
+// NewVaultBackend creates a new HashiCorp Vault secrets backend.
+// addr is the Vault server address (also read from VAULT_ADDR env).
+// mountPath is the KV v2 mount point (default: "secret").
+func NewVaultBackend(addr, mountPath string) (*VaultBackend, error) {
+	config := vault.DefaultConfig()
+	if addr != "" {
+		config.Address = addr
+	}
+
+	client, err := vault.NewClient(config)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create Vault client: %w", err)
+	}
+
+	// Read token from VAULT_TOKEN (automatic) or VAULT_TOKEN_FILE
+	if client.Token() == "" {
+		tokenFile := os.Getenv("VAULT_TOKEN_FILE")
+		if tokenFile != "" {
+			data, err := os.ReadFile(tokenFile)
+			if err != nil {
+				return nil, fmt.Errorf("failed to read VAULT_TOKEN_FILE: %w", err)
+			}
+			client.SetToken(string(bytes.TrimSpace(data)))
+		}
+	}
+
+	if client.Token() == "" {
+		return nil, fmt.Errorf("VAULT_TOKEN or VAULT_TOKEN_FILE is required")
+	}
+
+	if mountPath == "" {
+		mountPath = "secret"
+	}
+
+	// Verify connectivity
+	_, err = client.Auth().Token().LookupSelf()
+	if err != nil {
+		return nil, fmt.Errorf("failed to verify Vault token: %w", err)
+	}
+
+	slog.Info("connected to HashiCorp Vault", "addr", config.Address, "mount", mountPath)
+	return &VaultBackend{client: client, mountPath: mountPath}, nil
+}
+
+// GetItems retrieves all agent items from the Vault KV v2 engine.
+// The scope parameter is the base path under the mount (e.g., "agents").
+func (v *VaultBackend) GetItems(ctx context.Context, scope string) ([]*Item, error) {
+	// KV v2 list endpoint: <mount>/metadata/<path>
+	listPath := fmt.Sprintf("%s/metadata/%s", v.mountPath, scope)
+
+	secret, err := v.client.Logical().ListWithContext(ctx, listPath)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list secrets at %s: %w", listPath, err)
+	}
+
+	if secret == nil || secret.Data == nil {
+		return []*Item{}, nil
+	}
+
+	keys, ok := secret.Data["keys"].([]interface{})
+	if !ok {
+		return nil, fmt.Errorf("unexpected response format from Vault list")
+	}
+
+	var items []*Item
+	for _, k := range keys {
+		key, ok := k.(string)
+		if !ok {
+			continue
+		}
+		// Skip directory entries (ending with /)
+		if strings.HasSuffix(key, "/") {
+			continue
+		}
+
+		// KV v2 read endpoint: <mount>/data/<path>/<key>
+		readPath := fmt.Sprintf("%s/data/%s/%s", v.mountPath, scope, key)
+		secret, err := v.client.Logical().ReadWithContext(ctx, readPath)
+		if err != nil {
+			slog.Warn("failed to read secret", "path", readPath, "error", err)
+			continue
+		}
+		if secret == nil || secret.Data == nil {
+			continue
+		}
+
+		// KV v2 wraps data in a "data" key
+		data, ok := secret.Data["data"].(map[string]interface{})
+		if !ok {
+			slog.Warn("unexpected secret format", "path", readPath)
+			continue
+		}
+
+		item := &Item{
+			ID:     key,
+			Name:   key,
+			Fields: make(map[string]string),
+		}
+
+		for fieldKey, fieldVal := range data {
+			if str, ok := fieldVal.(string); ok {
+				item.Fields[fieldKey] = str
+			}
+		}
+
+		items = append(items, item)
+	}
+
+	return items, nil
+}
+
+// GetAttachment is not supported by HashiCorp Vault.
+// Private keys should be stored as field values instead.
+func (v *VaultBackend) GetAttachment(ctx context.Context, itemID, attachmentName string) ([]byte, error) {
+	return nil, ErrAttachmentsNotSupported
+}
+
+// Close is a no-op for Vault (tokens are typically long-lived or managed externally).
+func (v *VaultBackend) Close(ctx context.Context) error {
+	slog.Info("Vault backend closed")
+	return nil
+}
+
+// Name returns the backend name for logging.
+func (v *VaultBackend) Name() string {
+	return "vault"
+}
diff --git a/internal/secrets/vault_test.go b/internal/secrets/vault_test.go
new file mode 100644
index 0000000..3b33880
--- /dev/null
+++ b/internal/secrets/vault_test.go
@@ -0,0 +1,249 @@
+package secrets
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestVaultBackend_GetItems(t *testing.T) {
+	// Mock Vault KV v2 API responses
+	mux := http.NewServeMux()
+
+	// LIST secret/metadata/agents (Vault client sends GET with ?list=true)
+	mux.HandleFunc("/v1/secret/metadata/agents", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"keys": []string{"test-agent", "another-agent"},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	// GET secret/data/agents/test-agent
+	mux.HandleFunc("/v1/secret/data/agents/test-agent", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"data": map[string]interface{}{
+					"app_id":          "123456",
+					"installation_id": "78901234",
+					"agent_token":     "dGVzdC10b2tlbg==",
+					"private_key":     "-----BEGIN RSA PRIVATE KEY-----\\ntest\\n-----END RSA PRIVATE KEY-----",
+					"identity_name":   "Test Agent",
+					"identity_email":  "test@example.com",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	// GET secret/data/agents/another-agent
+	mux.HandleFunc("/v1/secret/data/agents/another-agent", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"data": map[string]interface{}{
+					"app_id":          "654321",
+					"installation_id": "43210987",
+					"agent_token":     "b3RoZXItdG9rZW4=",
+					"private_key":     "-----BEGIN RSA PRIVATE KEY-----\\nother\\n-----END RSA PRIVATE KEY-----",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	// Token lookup (for NewVaultBackend verification)
+	mux.HandleFunc("/v1/auth/token/lookup-self", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"id": "test-token",
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	// Set VAULT_TOKEN for the backend constructor
+	t.Setenv("VAULT_TOKEN", "test-token")
+
+	backend, err := NewVaultBackend(server.URL, "secret")
+	if err != nil {
+		t.Fatalf("NewVaultBackend failed: %v", err)
+	}
+
+	items, err := backend.GetItems(context.Background(), "agents")
+	if err != nil {
+		t.Fatalf("GetItems failed: %v", err)
+	}
+
+	if len(items) != 2 {
+		t.Fatalf("expected 2 items, got %d", len(items))
+	}
+
+	// Find test-agent
+	var testAgent *Item
+	for _, item := range items {
+		if item.Name == "test-agent" {
+			testAgent = item
+			break
+		}
+	}
+	if testAgent == nil {
+		t.Fatal("test-agent not found in items")
+	}
+
+	if testAgent.Fields["app_id"] != "123456" {
+		t.Errorf("expected app_id=123456, got %s", testAgent.Fields["app_id"])
+	}
+	if testAgent.Fields["installation_id"] != "78901234" {
+		t.Errorf("expected installation_id=78901234, got %s", testAgent.Fields["installation_id"])
+	}
+	if testAgent.Fields["identity_name"] != "Test Agent" {
+		t.Errorf("expected identity_name=Test Agent, got %s", testAgent.Fields["identity_name"])
+	}
+	if testAgent.Fields["identity_email"] != "test@example.com" {
+		t.Errorf("expected identity_email=test@example.com, got %s", testAgent.Fields["identity_email"])
+	}
+}
+
+func TestVaultBackend_GetItems_SkipsDirectories(t *testing.T) {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("/v1/secret/metadata/agents", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"keys": []string{"test-agent", "subdirectory/"},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	mux.HandleFunc("/v1/secret/data/agents/test-agent", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{
+			"data": map[string]interface{}{
+				"data": map[string]interface{}{
+					"app_id": "123",
+				},
+			},
+		}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	mux.HandleFunc("/v1/auth/token/lookup-self", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{"data": map[string]interface{}{"id": "test-token"}}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	t.Setenv("VAULT_TOKEN", "test-token")
+
+	backend, err := NewVaultBackend(server.URL, "secret")
+	if err != nil {
+		t.Fatalf("NewVaultBackend failed: %v", err)
+	}
+
+	items, err := backend.GetItems(context.Background(), "agents")
+	if err != nil {
+		t.Fatalf("GetItems failed: %v", err)
+	}
+
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item (directory skipped), got %d", len(items))
+	}
+	if items[0].Name != "test-agent" {
+		t.Errorf("expected item name=test-agent, got %s", items[0].Name)
+	}
+}
+
+func TestVaultBackend_GetAttachment_ReturnsError(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/auth/token/lookup-self", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{"data": map[string]interface{}{"id": "test-token"}}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	t.Setenv("VAULT_TOKEN", "test-token")
+
+	backend, err := NewVaultBackend(server.URL, "secret")
+	if err != nil {
+		t.Fatalf("NewVaultBackend failed: %v", err)
+	}
+
+	_, err = backend.GetAttachment(context.Background(), "item-id", "file.pem")
+	if err != ErrAttachmentsNotSupported {
+		t.Errorf("expected ErrAttachmentsNotSupported, got %v", err)
+	}
+}
+
+func TestVaultBackend_Close(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/auth/token/lookup-self", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{"data": map[string]interface{}{"id": "test-token"}}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	t.Setenv("VAULT_TOKEN", "test-token")
+
+	backend, err := NewVaultBackend(server.URL, "secret")
+	if err != nil {
+		t.Fatalf("NewVaultBackend failed: %v", err)
+	}
+
+	if err := backend.Close(context.Background()); err != nil {
+		t.Errorf("Close returned error: %v", err)
+	}
+}
+
+func TestVaultBackend_Name(t *testing.T) {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/v1/auth/token/lookup-self", func(w http.ResponseWriter, r *http.Request) {
+		resp := map[string]interface{}{"data": map[string]interface{}{"id": "test-token"}}
+		w.Header().Set("Content-Type", "application/json")
+		json.NewEncoder(w).Encode(resp)
+	})
+
+	server := httptest.NewServer(mux)
+	defer server.Close()
+
+	t.Setenv("VAULT_TOKEN", "test-token")
+
+	backend, err := NewVaultBackend(server.URL, "secret")
+	if err != nil {
+		t.Fatalf("NewVaultBackend failed: %v", err)
+	}
+
+	if backend.Name() != "vault" {
+		t.Errorf("expected name=vault, got %s", backend.Name())
+	}
+}
+
+func TestNewVaultBackend_MissingToken(t *testing.T) {
+	t.Setenv("VAULT_TOKEN", "")
+	t.Setenv("VAULT_TOKEN_FILE", "")
+
+	_, err := NewVaultBackend("http://localhost:8200", "secret")
+	if err == nil {
+		t.Fatal("expected error for missing token, got nil")
+	}
+}
diff --git a/scripts/seed-vault-hcv.sh b/scripts/seed-vault-hcv.sh
new file mode 100755
index 0000000..59cfae7
--- /dev/null
+++ b/scripts/seed-vault-hcv.sh
@@ -0,0 +1,146 @@
+#!/bin/bash
+# seed-vault-hcv.sh - Seeds HashiCorp Vault with test GitHub App credentials
+#
+# This script:
+# 1. Waits for Vault to be ready
+# 2. Decodes or generates a GitHub App private key
+# 3. Generates an agent token (signed with the private key)
+# 4. Writes agent secrets to Vault KV v2
+# 5. Exports agent token for the test runner
+#
+# Required environment variables:
+#   VAULT_ADDR
+#   VAULT_TOKEN
+#   TEST_GITHUB_APP_ID
+#   TEST_GITHUB_INSTALLATION_ID
+#   TEST_GITHUB_PRIVATE_KEY_B64
+#   TEST_AGENT_NAME
+#   TEST_AGENT_EMAIL
+
+set -e
+
+echo "=== HashiCorp Vault Seeder Starting ==="
+
+# Configuration
+OUTPUT_DIR="${OUTPUT_DIR:-/output}"
+MAX_RETRIES=30
+RETRY_INTERVAL=2
+
+# Validate required environment variables
+required_vars=(
+    "VAULT_ADDR"
+    "VAULT_TOKEN"
+    "TEST_AGENT_NAME"
+)
+
+for var in "${required_vars[@]}"; do
+    if [ -z "${!var}" ]; then
+        echo "ERROR: Required environment variable $var is not set"
+        exit 1
+    fi
+done
+
+# Apply defaults for optional GitHub App settings (allows CI without real secrets)
+TEST_GITHUB_APP_ID="${TEST_GITHUB_APP_ID:-123456}"
+TEST_GITHUB_INSTALLATION_ID="${TEST_GITHUB_INSTALLATION_ID:-78901234}"
+
+# Wait for Vault to be ready
+echo "Waiting for Vault at ${VAULT_ADDR}..."
+for i in $(seq 1 $MAX_RETRIES); do
+    if vault status > /dev/null 2>&1; then
+        echo "Vault is ready!"
+        break
+    fi
+    if [ $i -eq $MAX_RETRIES ]; then
+        echo "ERROR: Vault failed to become ready"
+        exit 1
+    fi
+    echo "  Attempt $i/$MAX_RETRIES - waiting..."
+    sleep $RETRY_INTERVAL
+done
+
+# Check if agent secret already exists (idempotent re-runs)
+EXISTING_TOKEN=$(vault kv get -field=agent_token "secret/agents/${TEST_AGENT_NAME}" 2>/dev/null || echo "")
+if [ -n "${EXISTING_TOKEN}" ]; then
+    echo "Agent secret already exists in Vault, skipping seed."
+    mkdir -p "${OUTPUT_DIR}"
+    echo "${EXISTING_TOKEN}" > "${OUTPUT_DIR}/agent_token.txt"
+    chmod 600 "${OUTPUT_DIR}/agent_token.txt"
+    echo "${TEST_AGENT_NAME}" > "${OUTPUT_DIR}/agent_name.txt"
+    chmod 644 "${OUTPUT_DIR}/agent_name.txt"
+    echo ""
+    echo "=== HashiCorp Vault Seeder Complete (existing data) ==="
+    echo "  Agent: ${TEST_AGENT_NAME}"
+    echo "  Agent token: ${OUTPUT_DIR}/agent_token.txt"
+    echo ""
+    exit 0
+fi
+
+# Decode or generate private key
+echo "Processing private key..."
+PRIVATE_KEY_FILE="/tmp/github-app-private-key.pem"
+
+if [ -n "${TEST_GITHUB_PRIVATE_KEY_B64}" ] && [ "${TEST_GITHUB_PRIVATE_KEY_B64}" != "LS0tLS1CRUdJTi...base64..." ]; then
+    echo "  Decoding provided private key..."
+    echo "${TEST_GITHUB_PRIVATE_KEY_B64}" | base64 -d > "${PRIVATE_KEY_FILE}"
+else
+    echo "  No private key provided, generating test key..."
+    openssl genrsa -out "${PRIVATE_KEY_FILE}" 2048 2>/dev/null
+fi
+chmod 600 "${PRIVATE_KEY_FILE}"
+
+# Verify the key is valid
+if ! openssl rsa -in "${PRIVATE_KEY_FILE}" -check -noout 2>/dev/null; then
+    echo "ERROR: Invalid private key. Please check TEST_GITHUB_PRIVATE_KEY_B64."
+    exit 1
+fi
+echo "  Private key is valid"
+
+# Read the private key content
+PRIVATE_KEY_DECODED=$(cat "${PRIVATE_KEY_FILE}")
+
+# Generate agent token (sign agent name with private key)
+echo "Generating agent token..."
+AGENT_TOKEN=$(echo -n "${TEST_AGENT_NAME}" | openssl dgst -sha256 -sign "${PRIVATE_KEY_FILE}" | base64 | tr -d '\n')
+
+# Escape the private key for storage (replace newlines with \n)
+PRIVATE_KEY_ESCAPED=$(echo "${PRIVATE_KEY_DECODED}" | sed ':a;N;$!ba;s/\n/\\n/g')
+
+# Write agent secrets to Vault KV v2
+AGENT_PATH="secret/agents/${TEST_AGENT_NAME}"
+echo "Writing agent secrets to Vault at ${AGENT_PATH}..."
+
+vault kv put "secret/agents/${TEST_AGENT_NAME}" \
+    app_id="${TEST_GITHUB_APP_ID}" \
+    installation_id="${TEST_GITHUB_INSTALLATION_ID}" \
+    agent_token="${AGENT_TOKEN}" \
+    private_key="${PRIVATE_KEY_ESCAPED}" \
+    identity_name="${TEST_AGENT_NAME}" \
+    identity_email="${TEST_AGENT_EMAIL:-${TEST_AGENT_NAME}@example.com}"
+
+echo "Agent secrets written successfully"
+
+# Verify the secret was written
+echo "Verifying secret..."
+vault kv get "secret/agents/${TEST_AGENT_NAME}" > /dev/null
+echo "Secret verified"
+
+# Export outputs
+echo "Exporting outputs..."
+mkdir -p "${OUTPUT_DIR}"
+
+echo "${AGENT_TOKEN}" > "${OUTPUT_DIR}/agent_token.txt"
+chmod 600 "${OUTPUT_DIR}/agent_token.txt"
+
+echo "${TEST_AGENT_NAME}" > "${OUTPUT_DIR}/agent_name.txt"
+chmod 644 "${OUTPUT_DIR}/agent_name.txt"
+
+echo ""
+echo "=== HashiCorp Vault Seeder Complete ==="
+echo "  Agent: ${TEST_AGENT_NAME}"
+echo "  Path: ${AGENT_PATH}"
+echo "  Agent token: ${OUTPUT_DIR}/agent_token.txt"
+echo ""
+
+# Cleanup
+rm -f "${PRIVATE_KEY_FILE}"
diff --git a/tests/e2e_test.go b/tests/e2e_test.go
index 19ca984..3668ffe 100644
--- a/tests/e2e_test.go
+++ b/tests/e2e_test.go
@@ -155,6 +155,11 @@ func TestTokenEndpoint(t *testing.T) {
 		t.Fatalf("Token request unauthorized - check agent credentials: %s", string(body))
 	}
 
+	// 500 means GitHub API call failed (expected without real GitHub App credentials)
+	if resp.StatusCode == http.StatusInternalServerError && os.Getenv("TEST_GITHUB_API_ENABLED") != "true" {
+		t.Skip("Token request failed (GitHub API not configured) - set TEST_GITHUB_API_ENABLED=true with real credentials")
+	}
+
 	if resp.StatusCode != http.StatusOK {
 		t.Fatalf("Expected status 200, got %d: %s", resp.StatusCode, string(body))
 	}
@@ -260,6 +265,11 @@ func TestGitCredentialsEndpoint(t *testing.T) {
 
 	body, _ := io.ReadAll(resp.Body)
 
+	// 500 means GitHub API call failed (expected without real GitHub App credentials)
+	if resp.StatusCode == http.StatusInternalServerError && os.Getenv("TEST_GITHUB_API_ENABLED") != "true" {
+		t.Skip("Git credentials failed (GitHub API not configured) - set TEST_GITHUB_API_ENABLED=true with real credentials")
+	}
+
 	if resp.StatusCode != http.StatusOK {
 		t.Fatalf("Expected status 200, got %d: %s", resp.StatusCode, string(body))
 	}