> For the complete documentation index, see [llms.txt](https://docs.umh.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.umh.app/usage/instances.md).

# Instances

## What is an Instance?

An instance is a running UMH Core container - a single Docker container that hosts your entire Unified Namespace. Each instance has a location path like `enterprise.site.area.line`. The location path determines where data is organized in your industrial data infrastructure. An instance is also uniquely identified by its Instance UUID.

## How an instance connects

An instance authenticates with an `AUTH_TOKEN`, not with a user account. The Management Console generates the token while you create the instance and shows it once. Copy it then and pass it to the container as the `AUTH_TOKEN` environment variable on the first start.

The token does two things:

* It proves the instance's identity. The Management Console accepts the instance's status and hands it the configuration meant for it.
* It locks the instance's access to the Management Console. Only the instance can unlock it, because only the instance has the token. The Management Console cannot.

Keep the token somewhere you can find it again, such as your password manager. For storage and rotation on the instance, see [AUTH\_TOKEN in Environment Variable](https://docs.umh.app/production/security/deployment-security.md#auth_token-in-environment-variable).

## Instance Overview Page

![Instance Overview](https://3966587046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPQ7UY9eT1SiICDqYFZdA%2Fuploads%2Fgit-blob-ec30c3474ace0adbdab0080868120a61efc65f2f%2Finstance-overview.png?alt=media\&token=48ce6ca9-6c0f-4e88-866d-cc08c233fc2c)

The instance overview shows all your UMH instances at a glance:

* **Instance Name**: Your chosen identifier for the instance
* **Type**:
  * **Core**: Single container deployment (UMH Core)
  * **Classic**: Kubernetes-based deployment (legacy)
* **Version**: Container version identifier (e.g., `9e22396`)
* **Data Flows**: Number of configured bridges and stand-alone flows
* **Topics**: Total data points in your Unified Namespace
* **Latency**: Network response time in milliseconds
* **Throughput**: Messages per second flowing through the system

**Status indicators:**

* Green dot: Instance is online and reachable
* Gray dot: Instance is offline or unreachable

**Quick actions:** Click the context menu (⋮) on any instance for:

* Instance Details
* Config File
* Delete

## Instance Details Page

![Instance Details](https://3966587046-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FPQ7UY9eT1SiICDqYFZdA%2Fuploads%2Fgit-blob-b0af1a9961fd555792b453666d44bf99fd20faa6%2Finstance-detail.png?alt=media\&token=e0f7ed7f-6028-4e37-9c64-0ece9d07ec60)

The instance details page provides comprehensive monitoring and management:

### Agent Card

The Agent card shows the identity and the version of the instance: its name, location path, UMH Core version and release channel. See [Agent](https://docs.umh.app/usage/instances/agent.md).

### Container Card

The Container card shows the CPU, memory and disk of the container, its architecture and its Hardware ID. See [Container](https://docs.umh.app/usage/instances/container.md).

### Communicator Card

The Communicator card shows the connection to the Management Console: its health, how full the outbound queue is, and how many Management Console sessions watch the instance. See [Communicator](https://docs.umh.app/usage/instances/communicator.md).

### Data Flows Card

The Data Flows card groups bridges and stand-alone flows by their state. The states come from the [state machines](https://docs.umh.app/reference/state-machines.md) reference:

* **Active**: Currently processing data (messages flowing)
* **Neutral**: Includes:
  * `idle`: Healthy but no data for 30+ seconds
  * `stopped`: Intentionally disabled
  * `starting`: Initialization in progress
  * Various transition states

Example states:

* `starting_dfc (port is open)`: Connection verified, waiting for Benthos, the stream processor that runs the flow, to start
* `starting: stopping: stopping`: Complex state transition in progress

**Bridges count**: Total configured with active/neutral breakdown

### Redpanda Card

The Redpanda card shows the message broker that stores your [Unified Namespace](https://docs.umh.app/usage/unified-namespace.md):

* **Incoming Throughput**: Data rate into the broker, per second, in B, KiB, MiB or a larger binary unit, depending on the value
* **Outgoing Throughput**: Data rate from the broker, per second, in B, KiB, MiB or a larger binary unit, depending on the value
* **Logs/Metrics buttons**: Direct access to Redpanda diagnostics

### Topic Browser Card

The Topic Browser card summarizes the data in the instance's Unified Namespace:

* **Topics count**: Total number of data topics
* Quick access to the [Topic Browser](https://docs.umh.app/usage/unified-namespace/topic-browser.md) for data exploration

## Next Steps

* **Configure your instance**: [Edit the config file](https://docs.umh.app/usage/instances/config-file.md)
* **Connect devices**: [Create bridges](https://docs.umh.app/usage/data-flows/bridges.md)
* **View your data**: [Topic Browser](https://docs.umh.app/usage/unified-namespace/topic-browser.md)
* **Understand states**: [State Machines reference](https://docs.umh.app/reference/state-machines.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.umh.app/usage/instances.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
