Your First Agent

This page walks you through installing, starting, and registering your first Keeper EPM agent on a single endpoint. It's designed to get you from a fresh install to a fully registered agent that appears in your Admin Console, using a manual process that helps you understand what each step does. Once you've done it once, you can automate the same steps for wider deployment — see the Deployment section for platform-specific packaging, MDM/GPO integration, and unattended install patterns.

Before You Begin

Confirm you have the prerequisites from Licensing & Activation:

• Keeper Enterprise license active with EPM seats.

• Endpoint Privilege Manager activated in the Keeper Admin Console.

• An administrator account with the Manage Privileged Access permission.

• A registration token in the format hostname:deployment-uid:private-key.

You'll also need on the endpoint itself:

• Local Administrator or Root Rights on the machine for installation and service management.

• Available Ports — defaults are HTTP 6888, HTTPS 6889, and MQTT 8675. These are configurable if they conflict with something else on the endpoint.

• The Agent Installer for your platform (Windows, Linux, or macOS), obtained from your Keeper account team or your Admin Console.

Creating Your First Deployment Package

A deployment package is the container in the Keeper Admin Console that generates a registration token and pairs it with the settings, collections, and installer your agent will use. Every agent registers to exactly one deployment package, and the package determines which endpoints the agent is grouped with and which policies it receives.

Before you can register an agent, you need at least one deployment package to register it to.

1

Open the Deployments Tab

In the Keeper Admin Console, navigate to [TK: Admin > Endpoint Privilege Manager > Deployments] (or the equivalent menu path in your console version).

2

Create a New Deployment Package

Select [TK: Create Deployment / New Package / +] to start a new deployment package.

3

Name the Package

Give the package a descriptive name that identifies its purpose. For your first package, something like Pilot - Windows or First Agent Test works well. Names should reflect either the endpoint group (Finance Workstations, Engineering Laptops) or the rollout phase (Pilot, Wave 1), depending on how you plan to organize your deployment.

4

Select the Target Platform

Choose the platform this package targets:

• Windows

• macOS

• Linux

Each platform generates a platform-specific installer and set of default settings. If you plan to deploy to more than one platform, create a separate deployment package for each — do not try to reuse a single package across platforms.

5

Assign Collections

Assign the collections this package should apply to. Collections determine which users and machines the registered agents will be associated with, and — indirectly — which policies will apply once you've defined them.

For your first package, you can assign an existing collection or leave the package unassigned for now and add collections later. If you haven't created collections yet, see How Approvers, Collections & Policies Work Together.

6

[TK: Configure Package-Level Settings]

[TK: Verify what package-level settings are exposed in the current UI — e.g., default policy mode, agent update behavior, plugin selection, custom appsettings overrides. Document each with the recommended default for a first agent.]

For a first agent, accept the defaults unless you have a specific reason to override them.

7

Generate the Registration Token

Select [TK: Generate Token / Create Package] to finalize the package. The Admin Console will generate a registration token in the format:

hostname:deployment-uid:private-key

Copy this token immediately and store it securely. You'll need it to register your first agent in Step 4 of the agent registration flow below.

Registration tokens are sensitive credentials. Treat them as secrets — store and transmit them through secure channels only, and rotate them if you suspect a token has been exposed.

8

Download the Installer

From the deployment package detail view, download the platform-specific installer:

• Windows: [TK: KeeperPrivilegeManager.msi or similar]

• macOS: [TK: KeeperPrivilegeManager.pkg or similar]

• Linux: [TK: .deb / .rpm / .tar.gz — confirm which formats are provided]

Transfer the installer to the endpoint where you'll install the agent.

What You Have Now

At this point you have:

• A deployment package created in the Admin Console.

• A registration token copied and stored securely.

• The platform-specific installer downloaded and ready to transfer to the endpoint.

You're ready to proceed with installing and registering your first agent.

---

Installing Your First Agent

1

Install the Agent

Install the Keeper Privilege Manager agent on the endpoint using the installer for your platform. The installer places the product in a platform-specific location:

• Windows: C:\Program Files\KeeperPrivilegeManager

• Linux / macOS: /opt/keeper/

After install, confirm the installation directory contains the main executable, appsettings.json, and the Plugins/, Jobs/, and KeeperStorage/ subdirectories.

For automated or unattended install methods — including MSI parameters, package manager options, and MDM configuration profiles — see the platform-specific deployment guides under Deployment.

2

Start the Service

Start the KeeperPrivilegeManager service. Give it 15–30 seconds to initialize before running the verification steps in Step 3.

Windows:

Get-Service -Name "KeeperPrivilegeManager"
Start-Service -Name "KeeperPrivilegeManager"

Linux:

sudo systemctl status keeper-privilege-manager
sudo systemctl start keeper-privilege-manager
sudo systemctl enable keeper-privilege-manager   # Optional: auto-start on boot

macOS:

Use the provided launchd configuration to load and start the Keeper service. See Deploy with macOS for the specific launchctl commands and configuration profile.

3

Verify the Service Is Healthy

From the endpoint, run the local health check:

curl -k https://localhost:6889/health

You should receive a 200 OK response indicating the service is running. If the check fails:

• Wait an additional 30 seconds and retry — the service may still be initializing.

• Confirm nothing else on the endpoint is bound to ports 6888 or 6889.

• Check the service logs for errors. See Reading Logs for log locations by platform.

For a full list of health and status endpoints — including plugin health, monitoring status, and system status — see Health & Status Endpoints.

4

Register the Agent

Registration links this endpoint to your Keeper tenant so it can receive policies and report status back.

Check Current Registration Status:

curl -k https://localhost:6889/api/Keeper/registration

If the agent is not yet registered, the response will indicate that.

Register Using the HTTP API (replace YOUR_TOKEN_HERE with your actual registration token):

curl -X POST "https://localhost:6889/api/Keeper/register?token=YOUR_TOKEN_HERE" --insecure

Register Using the Registration Helper:

• Windows: KeeperRegistrationHelper.exe --token "YOUR_TOKEN_HERE"

• Linux: ./register-keeper-ubuntu.sh --token "YOUR_TOKEN_HERE" (or the equivalent script for your distribution)

Confirm Registration:

curl -k https://localhost:6889/api/Keeper/registration

The response should now show the agent as registered. From this point, the agent will sync policies from the Admin Console according to the deployment package and collections it was registered under.

5

Confirm the Core Plugins Are Running

To confirm the plugins responsible for backend sync and policy enforcement are operational:

curl -k https://localhost:6889/api/plugins

Look for two plugins in a Running state:

• KeeperAPI — required for registration and policy sync with the Keeper backend.

• KeeperPolicy — required for local policy evaluation and enforcement.

If either plugin is missing or not running, review the service logs before proceeding.

6

Verify the Agent in the Admin Console

Return to the Keeper Admin Console and navigate to the Endpoint Privilege Manager section. Your newly registered agent should appear in the list of endpoints, associated with the deployment package and collections you registered it under.

If the agent doesn't appear within a minute or two:

• Confirm the registration token was for the correct tenant and deployment package.

• Confirm the endpoint can reach the Keeper backend (registration succeeded locally, but ongoing sync requires outbound connectivity).

• Check the KeeperAPI plugin logs for sync errors.

Success Checklist

Before moving on, confirm all of the following:

• Agent installed in the expected directory.

• Service running (Get-Service, systemctl status, or launchctl list).

• Health check returns 200 OK.

• Registration API confirms the agent as registered.

• KeeperAPI and KeeperPolicy plugins both show Running.

• Agent visible in the Admin Console under Endpoint Privilege Manager.

What's Next

Your first agent is registered but not yet doing anything — it's waiting for policies to be assigned. From here:

• To understand the model behind approvers, collections, and policies, see How Approvers, Collections & Policies Work Together.

• To understand how deployment packages, the agent, and requests interact once policies are in place, see How Deployment Packages, the Agent, & Requests Work Together.

• To roll out agents at scale using MDM, GPO, or scripted install, see the Deployment section.