# Manual DVE Agent Installation

Use this guide when deploying the DVE agent outside MDM — pilots, contractors, home offices, or individual troubleshooting.

## Prerequisites

- Administrator rights on the target machine (macOS, Windows, or Linux x64)
- Outbound HTTPS to your DVE API and agent download host
- A DVE user account provisioned in your organization

## Step 1: Fetch the agent manifest

From a browser or terminal, request the public manifest (no authentication required):

```bash
curl -s "${DVE_API_BASE_URL}/api/deployment/agent-manifest"
```

Or use your org-scoped endpoint if you already have an agent session:

```bash
curl -s -H "X-Agent-Token: ${AGENT_TOKEN}" \
  "${DVE_API_BASE_URL}/api/orgs/${ORG_ID}/deployment/agent-manifest"
```

Note the `version`, the correct `download_urls` entry for your platform (`mac_arm`, `mac_x64`, `windows_x64`, `linux_x64`), and `checksum_url`.

## Step 2: Download the installer

Download the platform-appropriate artifact. Example for macOS Apple Silicon:

```bash
VERSION=$(curl -s "${DVE_API_BASE_URL}/api/deployment/agent-manifest" | jq -r '.manifest.version')
URL=$(curl -s "${DVE_API_BASE_URL}/api/deployment/agent-manifest" | jq -r '.manifest.download_urls.mac_arm')
curl -L -o "dve-agent-${VERSION}.dmg" "$URL"
```

## Step 3: Verify checksum

Download checksums and verify before installing:

```bash
CHECKSUM_URL=$(curl -s "${DVE_API_BASE_URL}/api/deployment/agent-manifest" | jq -r '.manifest.checksum_url')
curl -L -o checksums.sha256 "$CHECKSUM_URL"
shasum -a 256 -c checksums.sha256 --ignore-missing
```

On Windows, use `Get-FileHash` and compare against the checksum file.

## Step 4: Install

| Platform | Install action |
|----------|----------------|
| macOS (.dmg) | Open DMG, drag DVE Agent to Applications, eject DMG |
| Windows (.exe) | Run installer silently: `dve-agent-windows-x64.exe /S` (adjust per your package) |
| Linux (.AppImage) | `chmod +x dve-agent-*.AppImage` and move to `/opt` or user Applications |

## Step 5: First-run setup

1. Launch **PhantomKey DVE Agent** from Applications or Start menu.
2. Sign in with your organization URL and complete agent pairing if prompted.
3. Enter your DVE passphrase when unlocking — the passphrase stays on this device only.
4. Confirm the tray/menu bar icon shows the agent as connected.

## Step 6: Verify access

Open the DVE web console or browser extension and confirm credentials load after unlock. If credentials do not appear, confirm the agent is running and the user has an active DVE role.

## Automated install script

For repeatable manual fleet rollout, use `install-dve-agent.sh` (macOS/Linux) or `Install-DveAgent.ps1` (Windows) with `DVE_API_BASE_URL` set.

## Troubleshooting

- **"Agent required" message in DVE:** Install and launch the local agent; unlock with your passphrase.
- **Checksum mismatch:** Re-download from current manifest; do not install unverified binaries.
- **Gatekeeper blocks macOS install:** Right-click → Open once, or deploy via MDM with approved package signature.
- **Manifest shows null download URLs:** Your DVE server administrator must configure `AGENT_VERSION` and `AGENT_DOWNLOAD_BASE_URL`.

## API reference

- Public manifest: `GET /api/deployment/agent-manifest`
- Deployment config (IT Admin): `GET /api/orgs/{org_id}/deployment/config`

See [overview.md](overview.md) for the full deployment picture.