> For the complete documentation index, see [llms.txt](https://docs.pharos.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pharos.ai/configuration-guide/the-basics/package-installation.md).

# Package Installation

Step-by-step guide to installing the Pharos managed package in your Salesforce org.

Pharos is delivered as a Salesforce managed package. Installation deploys all custom objects, Lightning components, Apex classes, and configuration interfaces into your org. The process takes about 10 minutes and follows the standard Salesforce package installation flow.

***

## Prerequisites

Before starting, confirm you have:

| Requirement            | Details                                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Salesforce Edition** | Enterprise, Unlimited, or Performance Edition (Developer Edition for testing)                                                                                                                                                                                                                                                                                      |
| **User Permissions**   | System Administrator profile or a user with **Customize Application** and **View All Data**                                                                                                                                                                                                                                                                        |
| **Installation URL**   | Obtain via [Pharos Free](https://pharos.ai/pricing/102), [AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMhhvUAD), or [paid edition trials](https://pharos.ai/pricing) — or use the direct install link for [production](https://resources.pharos.ai/pharos-prod) or [sandbox](https://resources.pharos.ai/pharos-sandbox) |

***

## Getting the Package

Choose one of the following to obtain — or go straight to — your installation URL:

| Option                          | Link                                                                                                     | Use Case                                                                                 |
| ------------------------------- | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Pharos Free**                 | [pharos.ai/pricing/102](https://pharos.ai/pricing/102)                                                   | Free (Core) edition — no cost                                                            |
| **AppExchange**                 | [AppExchange listing](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMhhvUAD) | By default, installs the free (Core) edition of Pharos — click **Get It Now** to proceed |
| **Paid Edition Trials**         | [pharos.ai/pricing](https://pharos.ai/pricing)                                                           | Growth, Professional, and Enterprise trial links                                         |
| **Direct Install — Production** | [resources.pharos.ai/pharos-prod](https://resources.pharos.ai/pharos-prod)                               | Install straight into a production or Developer Edition org                              |
| **Direct Install — Sandbox**    | [resources.pharos.ai/pharos-sandbox](https://resources.pharos.ai/pharos-sandbox)                         | Install straight into a sandbox                                                          |

<details>

<summary>Paid edition trial links</summary>

* [Growth trial](https://pharos.ai/pricing/104) — up to 500 users
* [Professional trial](https://pharos.ai/pricing/103) — up to 1,000 users
* [Enterprise proof of concept](https://pharos.ai/pricing/105) — custom pricing

</details>

When you sign up for the free edition or submit a paid trial form on the Pharos website, you will receive a direct install link by email. AppExchange provides the link immediately when you click **Get It Now**. If you already know which org you're installing into, you can skip straight to the direct install link for [production](https://resources.pharos.ai/pharos-prod) or [sandbox](https://resources.pharos.ai/pharos-sandbox). Follow the steps below once you have your URL.

{% hint style="info" %}
**AppExchange users:** On the [Pharos AppExchange listing](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMhhvUAD), click **Get It Now** (not "Try It") to proceed to the installation flow.
{% endhint %}

![Pharos AppExchange listing — click Get It Now to install](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-05fd80b0a8490e77a90e9e8d013f62fb51a1b2d3%2Fappexchange-get-it-now.png?alt=media)

***

## Installation Steps

{% embed url="<https://demo.arcade.software/EGjr3QQojmI36uZbnx47?embed>" %}

### Step 1: Open the Installation URL

Open the Pharos installation URL in your browser. If you're installing from AppExchange, click **Get It Now** on the listing page to reach the Salesforce package installation screen.

If you're not already logged in, Salesforce will prompt you to authenticate. Make sure you log in to the **correct org** — production or sandbox — where you want Pharos installed.

{% hint style="warning" %}
**Double-Check Your Target Org:** Make sure you're using the link that matches your environment — [pharos-prod](https://resources.pharos.ai/pharos-prod) for production and Developer Edition orgs, [pharos-sandbox](https://resources.pharos.ai/pharos-sandbox) for sandboxes. Even then, the link doesn't pick a *specific* org, so verify the org name displayed on the installation screen before proceeding.
{% endhint %}

### Step 2: Choose Installation Scope

Salesforce presents three options for which users get access to the installed components:

| Option                            | When to Use                                                                              |
| --------------------------------- | ---------------------------------------------------------------------------------------- |
| **Install for Admins Only**       | Recommended for initial setup — gives you time to configure before granting wider access |
| **Install for All Users**         | Use when you're ready for the full team to access Pharos                                 |
| **Install for Specific Profiles** | Use when you need granular access control from the start                                 |

{% hint style="info" %}
**Recommended:** Start with **Install for Admins Only**. This lets you complete configuration and run the Quick Start wizard before other users see the Pharos app. You can adjust permissions later through permission sets and profiles.
{% endhint %}

### Step 3: Install

Click **Install** to begin the deployment. For most orgs, installation completes within a few minutes.

If the installation takes longer than expected, Salesforce will email you when it's finished. This is normal for larger orgs and does not indicate a problem.

### Step 4: Verify Installation

After installation completes:

1. Navigate to **Setup → Installed Packages**
2. Confirm **Pharos** appears in the list with the expected version number
3. Open the **App Launcher** and search for **Pharos** — the Pharos Lightning app should appear

{% hint style="success" %}
**Installation Complete:** You should now see the Pharos app in your App Launcher. The next step is to designate the [Pharos Running User](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md) and run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard.
{% endhint %}

***

## Sandbox Installation

Installing Pharos in a sandbox follows the same steps as production — just use the sandbox install link, [resources.pharos.ai/pharos-sandbox](https://resources.pharos.ai/pharos-sandbox), instead of the production one.

{% hint style="warning" %}
**Sandbox Refreshes Require Reconfiguration:** When you refresh a sandbox from production, the Pharos package is copied but the configuration needs to be reinitialized. After every sandbox refresh, run the [Quick Start](https://docs.pharos.ai/configuration-guide/quick-start.md) wizard with the **Sandbox Refresh** option. This clears stale production configuration and sets up the sandbox correctly.
{% endhint %}

***

## Upgrading Pharos

You'll receive a notification when a new major version of Pharos is released. There's no new URL to obtain — the same install links and AppExchange routes always point to the current version, and running the installer on an org that already has Pharos performs the upgrade in place.

An upgrade is **not** finished when the installer is. It requires post-install steps the installer cannot do for you: redeploying and reassigning the separately distributed permission sets, resetting the running user, and updating the Triton platform-event subscriber user. Skipping them leaves Pharos partly non-functional.

Follow [Upgrade](https://docs.pharos.ai/configuration-guide/the-basics/upgrade.md) for the full procedure.

***

## Troubleshooting

If installation fails, Salesforce may email you or display an error on the installation page. A typical failure message looks like this:

![Example of a package install failure message from Salesforce](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-60b405d88ab06c0e4bfcd228b357175816113244%2Finstall-failure-screenshot.png?alt=media)

| Issue                                                                      | Cause                                                    | Resolution                                                                                                                                  |
| -------------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **"Dependent class is invalid and needs recompilation"** (SetupAuditTrail) | Org lacks API access to SetupAuditTrail object           | Contact Salesforce support to request Setup Audit Trail API enablement. See the expandable below for the exact wording to use in your case. |
| **"User doesn't have permission to create dashboard with colors"**         | Installing user lacks Change Dashboard Colors permission | Assign the **Change Dashboard Colors** permission to the user's profile or via a permission set.                                            |
| **Platform Cache Partitions (Missing Feature)**                            | Org has no cache partitions (common in scratch/dev orgs) | [Request a platform cache trial](https://help.salesforce.com/s/articleView?id=sf.data_platform_cache_trial.htm) from Salesforce.            |

<details>

<summary>Salesforce case wording for SetupAuditTrail error</summary>

Create a case from the [Salesforce Help and Training portal](https://help.salesforce.com). Use this in your case:

**Description:** We are unable to view SetupAuditTrail object via API. It is not visible in workbench, however it is visible via UI. Because of this we are not able to install a required managed package. Please enable Setup Audit Trail API setting on Salesforce side.

**Product:** Sales\
**Severity Level:** Severity 2 - Major functionality impacted and time-sensitive\
**Topic:** Developer Support\
**Attachment:** Attach the full error message from the installation attempt.

Salesforce may suggest recompiling Apex or running tests — these will not resolve the issue. Ask them to enable the setting. Typical turnaround is 1–2 days.

</details>

<details>

<summary>What the Platform Cache error looks like</summary>

![Platform Cache Partitions error — org lacks cache partitions](https://4264222071-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdl9tmJ56lvwg5XY63QYr%2Fuploads%2Fgit-blob-ac431922c59042a1b0d7d3e5317c70e843a2c70b%2Fplatform-cache-error-screenshot.png?alt=media)

</details>

| Issue                               | Cause                            | Resolution                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Package not visible in App Launcher | User profile doesn't have access | Assign the **Log\_Admin** permission set (for the [running user](https://docs.pharos.ai/configuration-guide/the-basics/pharos-running-user.md)) or an appropriate `Log_Read`/`Log_Read_Write` set — these ship separately via the [pharos-permissions](https://resources.pharos.ai/pharos-permissions) download, not the managed package |
| Installation email never arrives    | Salesforce email delay           | Check Setup → Installed Packages — the package may already be installed                                                                                                                                                                                                                                                                  |
| Other installation failures         | Various                          | Contact [Pharos support](https://support.pharos.ai/hc/en-us/articles/57878277056539) with your org ID and the error message                                                                                                                                                                                                              |

{% hint style="info" %}
**Need Help?** If you encounter issues during installation, contact [Pharos support](mailto:support@pharos.ai) with your org ID and the error message. The team can verify your installation URL and help resolve any blockers.
{% endhint %}
