#### Getting Started For background information, see the [What is Beszel?](https://www.beszel.dev/guide/what-is-beszel) page. #### 1. Start the hub The hub can be run with a single binary file or with Docker / Podman.

- [Binary](https://www.beszel.dev/guide/hub-installation#binary) - [Docker or Podman](https://www.beszel.dev/guide/hub-installation#docker-or-podman)

IMPORTANT This configuration should work out of the box, but you must follow these steps when adding the system in the web UI:

1. Update the `KEY` and `TOKEN` environment variables with your public key and token, then restart the agent:

``` docker compose up -d ```

2. Use the unix socket path as the **Host / IP** in the web UI:

``` /beszel_socket/beszel.sock ```

docker-compose.yml

``` services: beszel: image: henrygd/beszel:latest container_name: beszel restart: unless-stopped environment: APP_URL: http://localhost:8090 ports: - 8090:8090 volumes: - ./beszel_data:/beszel_data - ./beszel_socket:/beszel_socket beszel-agent: image: henrygd/beszel-agent:latest container_name: beszel-agent restart: unless-stopped network_mode: host volumes: - ./beszel_agent_data:/var/lib/beszel-agent - ./beszel_socket:/beszel_socket - /var/run/docker.sock:/var/run/docker.sock:ro environment: LISTEN: /beszel_socket/beszel.sock HUB_URL: http://localhost:8090 TOKEN: KEY: "" ```

NOTE If you prefer to set up containers in a different way, please feel free to do so. 1. Install [Docker](https://docs.docker.com/engine/install/) and [Docker Compose](https://docs.docker.com/compose/install/) if you haven't already. 2. Copy the `docker-compose.yml` content. 3. Create a directory somewhere to store the `docker-compose.yml` file. ``` mkdir beszel cd beszel ``` 4. Create a `docker-compose.yml` file, paste in the content, and save it.

nanovimemacsvscode

``` nano docker-compose.yml ``` 5. Change the `APP_URL` environment variable to the URL you’ll use to access the Hub (for example, a domain name or public IP including port if needed) 6. Start the service. ``` docker compose up -d ```

#### 2. Create an admin user After starting the hub, navigate to [http://localhost:8090](http://localhost:8090/) or your chosen address. You will be prompted to create an account:

[![Screenshot of user creation form](https://www.beszel.dev/image/admin-creation.png)](https://www.beszel.dev/image/admin-creation.png)

#### 3. Configure your first system Click the **Add System** button in the top right corner to open the system creation dialog. We're using a local unix socket in this example, but you can use a remote agent instead. > Note: As of 0.12.0, you can also use a universal token (`/settings/tokens`) to connect the agent to the hub without needing to configure it ahead of time.

[![Screenshot of system creation form](https://www.beszel.dev/image/add-system-socket-2.png)](https://www.beszel.dev/image/add-system-socket-2.png)

#### 4. Start the agent

NOTE If you prefer to set up containers in a different way, please feel free to do so. 1. Copy the `docker-compose.yml` content from the **Add System** dialog. 2. Create a directory somewhere to store the agent's `docker-compose.yml` file. ``` mkdir beszel-agent cd beszel-agent ``` 3. Create a `docker-compose.yml` file and paste in the content provided in the **Add System** dialog.

nanovimemacsvscode

``` nano docker-compose.yml ``` 4. Start the agent. ``` docker compose up -d ```

The install script is for Linux only If you use a different OS, please manually download and run the correct binary for your system. See the [Agent Installation](https://www.beszel.dev/guide/agent-installation#binary) page or the [Compiling](https://www.beszel.dev/guide/compiling) page for more information. 1. Copy the binary install command from the **Add System** dialog. 2. Open a terminal and run the command. This will download the correct binary, create a user called `beszel`, and start the agent. It also creates a service to keep it running after reboot, and optionally enables automatic daily updates.

#### 5. Finish adding the system Now that the agent is running, click the **Add System** button in the dialog. You will see the new system in table. If it flips to green, you're good to go.

[![Screenshot of system creation form](https://www.beszel.dev/image/new-system.png)](https://www.beszel.dev/image/new-system.png)

If it changes to red, check the [Common Issues](https://www.beszel.dev/guide/common-issues) page.