Skip to main content
Version: 0.4 · current

Manage entities

How-to guideReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Entities are the tree that holds your resources: companies, clients, environments, teams. What you set on an entity, everything below it inherits. This guide shows how to build and change the tree under Settings › Entities, where to set what each entity passes down, and how to tag resources so you can group them across the tree.

Before you begin​

  • You need the Entity admin role on the entity you change. To create an entity, you need it on the parent; to move one, on the entity and on its new parent.
  • Plan the levels you need. The kinds of entity (tenant, client, environment, group) are labels and change no behaviour. For how inheritance works, see Entities, tags and inheritance.

In the examples, Areito Corporation is the root, Ciguapa Inc. is a client below it, and Production and UAT are its environments.

Create an entity​

  1. Open Settings › Entities. The tree shows the entity chosen in the picker and everything below it, with the number of resources in each branch.
  2. On the parent, for example Ciguapa Inc., open its actions menu and select Add an entity below.
  3. Enter the Name, for example Production.
  4. Choose the Kind, for example environment.
  5. Optionally enter a Short name, used in paths: lower-case letters, digits and hyphens, unique across the installation. When you leave it empty, it is derived from the name. It cannot be changed later.
  6. Select Create.

There is only one root entity; every other entity has a parent.

Rename an entity​

  1. Open the entity's actions menu and select Rename.
  2. Change the Name, and the Kind if needed. The root's kind cannot change.
  3. Select Save.

The short name stays as it was, so links and paths keep working.

Move an entity​

Moving an entity moves everything below it, and from then on it all inherits from its new place: thresholds, Slack channels, maintenance windows, registration and roles.

  1. Open the entity's actions menu and select Move.
  2. Choose the New parent. Only entities you administer are offered, and never the entity itself or one below it.
  3. Select Move.

The root cannot move. The audit log records every move.

Delete an entity​

You can delete an entity once nothing is left below it.

  1. Remove or move what it holds: child entities, resources and sources. Deleting a resource also deletes its alerts.
  2. Open the entity's actions menu and select Delete. The option is available only when the entity is empty.
  3. Select Delete to confirm. The entity's own credentials, Slack channels and role assignments are deleted with it.

Excubius refuses the deletion when the entity still has child entities, resources, sources or alerts, or when resources elsewhere use one of its credentials. The root cannot be deleted.

Set what an entity passes down​

Each inherited setting has its own screen. Choose the entity in the picker, or open it from Settings › Entities.

SettingWhereGuide
Threshold defaults of every checkSettings › Entities, actions menu, Threshold defaultsChange thresholds and turn checks off
Roles and who gets an accountSettings › Users and rolesManage users and roles
Credentials for the collectorSettings › CredentialsStore a credential for the collector
Slack channelsSettings › NotificationsConfigure Slack notifications
Maintenance windowsSettings › Maintenance windowsPlan a maintenance window
Default theme and logoSettings › Branch appearanceSet up the public status page
Public status pageSettings › Status pageSet up the public status page

Tag resources​

Tags are key:value labels on resources, such as env:prod, role:sql or client:ciguapa. A resource lives in one place of the tree, but tags let you group it with others from anywhere in the tree.

To tag a resource:

  1. Open the resource and select Edit. When you add a resource, the wizard has a Tags step that works the same way.
  2. In Tags, enter key:value pairs separated by spaces, for example env:prod role:sql client:ciguapa. Keys use letters, digits, dot, dash and underscore, and each key appears once.
  3. Set the Criticality, from 1 (low) to 5 (critical). It is its own field, not a tag, and it is used for routing, risk and the security score.
  4. Select Save.

Use at least env, role and client on every resource, and set the criticality.

To use the tags:

  • In Resources, enter a Tag rule. role:sql env:prod shows resources that have both; a key alone, such as client, shows every resource that has that key.
  • On the Overview, choose the Hex view and Group by a tag key to see one group of hexagons per value.

Do it with the API​

TaskRequest
CreatePOST /api/v1/entities with parent_id, name, optional kind and slug
Rename or change the kindPATCH /api/v1/entities/{id} with name or kind
MovePATCH /api/v1/entities/{id} with parent_id
DeleteDELETE /api/v1/entities/{id}; answers 409 with the reason while the entity is not empty
Tag a resourcePATCH /api/v1/resources/{id} with tags, an object such as {"env": "prod", "role": "sql"}, and criticality