# Get started with Catalog

This page takes you from an empty Catalog to services with owners and resources matched to them. You need permission to create environments and enroll agents; by default that is an Owner or Admin. See [Catalog permissions](https://docs.evohub.io/catalog-permissions.md).

## 1. Create an environment

An environment is one place you run software, such as a production cluster. Create one for each cluster, or each group of VMs, that you want to see.

:::steps
### Open Environments and agents
In the console, open **Catalog**, then **Settings → Environments and agents**, and select **New environment**.

### Name it
Enter a **Name** such as `eu-prod`, pick its **Kind** (`prod`, `staging`, `dev` or `other`) and, if you like, a **Description**.

### Create it
Select **Create**. The environment shows **No agent reports here yet.** until something reports into it.
:::

## 2. Connect it

Catalog sees nothing on its own. Give it an agent, a cloud account, or both, for each environment.

### Install an agent

The [EvoHub agent](https://docs.evohub.io/agent-overview.md) runs in your Kubernetes cluster or on a Linux VM, reads what runs there with read-only access, and reports it. Secret values and environment variable values never leave your network.

:::steps
### Start from the environment
On the environment's card, select **Install an agent**, then **Go to Agents**. This opens **Organization → Agents** with that environment chosen; select **New agent**. Agents are managed there, not in Catalog, because one agent can serve several products.

### Describe the agent
Enter a **Name**, choose **Where it runs** (**Kubernetes cluster** or **Linux VM**) and check the **Environment**.

### Create the token
Select **Create token**. EvoHub creates a single-use enrollment token, valid for 15 minutes, and shows the install commands with it filled in.

### Run the commands
Choose **One command**, or **Keep it out of shell history** to paste the token separately, then copy and run the commands. See [Install on Kubernetes](https://docs.evohub.io/agent-kubernetes.md) or [Install on a VM](https://docs.evohub.io/agent-vm.md) for what they do.
:::

The agent enrolls, sends a heartbeat every minute and a full sweep every five minutes. What it found appears in Catalog within a few minutes, and the agent shows as **Reporting** under **Environments and agents** and **Organization → Agents**. An agent that stops reporting shows **Not reporting**, and after ten minutes without a heartbeat what it reported is marked stale.

### Connect a cloud account

For AWS, Azure, GCP or portvMind, EvoHub can read the account itself with read-only access you grant, every 15 minutes, with no agent to install. See [Cloud accounts](https://docs.evohub.io/catalog-cloud-accounts.md).

## 3. Declare your services

:::steps
### Open Services
Open **Catalog → Services** and select **New service** (or **Declare your first service**).

### Fill in what you know
Enter the **Name** and the **Slug**. The slug is lowercase letters, digits and hyphens, for example `payments-api`, and cannot change later. Pick the **Kind**, **Lifecycle**, **Owner team** and **Tier**, and add the **Repository**, **Docs** and **Runbook** links. Only the name and slug are required.

### Create it
Select **Create service**. Resources that already name this service in their annotation are matched to it at once.
:::

## 4. Match what runs to your services

There are two ways a resource joins a service.

**Annotate it.** Add the `evohub.io/component` annotation (or label) with the service's slug to your manifests, for example on a Deployment:

```yaml
metadata:
  annotations:
    evohub.io/component: payments-api
```

The next sweep binds it to that service without asking. Removing the annotation removes the binding at the next sweep.

**Review the match queue.** For everything without an annotation, Catalog proposes a service, for example when an application's name or `app.kubernetes.io/name` label is a service's slug. The Overview's **Ownership** panel shows how many suggestions are waiting and opens the **Match queue**, where you accept or reject each proposal. The **Services** entry in the navigation shows the same count. Accepting puts the application, and everything in it, in that service.

You can also open any application or resource and choose its service by hand. See [Matching and drift](https://docs.evohub.io/catalog-matching-and-drift.md).

## 5. Tie monitors and integrations to services

A service's [SLA report](https://docs.evohub.io/catalog-tiers-and-sla.md#the-sla-report) is measured from what watches it. Set the **Catalog service** field:

- on an Uptime monitor, when you create or edit it, so its checks count towards the service's availability
- on an On-Call integration, so the alerts it raises count towards the service's response and resolution times

## 6. Look at the gaps

With services declared and agents reporting, open the **Overview**. It shows what needs attention, the applications without an owner, and recent changes. **All drift** opens the full [drift report](https://docs.evohub.io/catalog-matching-and-drift.md#drift).

## Related

- [Catalog overview](https://docs.evohub.io/catalog-overview.md)
- [EvoHub Agent](https://docs.evohub.io/agent-overview.md)
- [Cloud accounts](https://docs.evohub.io/catalog-cloud-accounts.md)