Skip to main content

Core

Overview​

Barbara Core brings the Barbara Platform runtime to general-purpose servers, industrial PCs, and virtual machines.
A Core instance is created locally on your own infrastructure using the Barbara Core Manager wizard.

This document explains:

  • How to install Barbara Core Manager on supported Linux distributions
  • How to run the interactive wizard to create a Core instance
  • What each step of the wizard does and why it matters
  • How to register the resulting Core in Barbara Panel
  • How to read the local status view once the instance is running

Every screen shown here reflects the actual text and layout that appears in the terminal.

Installing Barbara Core Manager

Barbara Core Manager is distributed as a compressed .tar.gz archive.
Each archive contains prebuilt packages for a specific Linux family.

Supported distributions:

  • Ubuntu — Jammy (22.04 LTS), Noble (24.04 LTS)
  • Debian — Bullseye (11), Bookworm (12), Trixie (13)
  • RHEL / AlmaLinux — 8, 9, 10

The internal package naming uses either Ubuntu/Debian codenames or RHEL-style el suffixes.

Examples:

  • Ubuntu:

    • barbara-core-manager_<version>~jammy1_amd64.deb
    • barbara-core-manager_<version>~noble1_amd64.deb

  • Debian:

    • barbara-core-manager_<version>~bullseye1_amd64.deb
    • barbara-core-manager_<version>~bookworm1_amd64.deb
    • barbara-core-manager_<version>~trixie1_amd64.deb

  • RHEL / AlmaLinux:

    • barbara-core-manager-<version>.el8.x86_64.rpm
    • barbara-core-manager-<version>.el9.x86_64.rpm
    • barbara-core-manager-<version>.el10.x86_64.rpm

Note
RHEL and AlmaLinux use the same el8, el9, el10 convention and are binary compatible for these packages.

Downloading from Barbara Panel​

To obtain the archive:

  1. Log into Barbara Panel.
  2. Navigate to OS Images.
  3. Ensure the Barbara OS filter is active.
  4. In the list, locate:
    • Core for Ubuntu (if your host is Ubuntu)
    • Core for Debian (if your host is Debian)
    • Core for RHEL (if your host is RHEL or AlmaLinux)
  5. Click the download icon on the right side to download the corresponding .tar.gz file.

You will get a file similar to:

core-for-ubuntu-<version>.tar.gz
core-for-debian-<version>.tar.gz
core-for-rhel-<version>.tar.gz

The OS Images view in Barbara Panel looks similar to:

OS Images view showing Core for Ubuntu, Core for Debian and Core for RHEL

Extracting the archive​

Copy the .tar.gz file to the target machine (or download it directly there), then extract it:

tar -xvf core-for-ubuntu-<version>.tar.gz
# or
tar -xvf core-for-debian-<version>.tar.gz
# or
tar -xvf core-for-rhel-<version>.tar.gz

You will find the .deb or .rpm packages corresponding to each supported release.

Installing Barbara Core Manager​

Ubuntu / Debian​

Choose the .deb file that matches your distribution codename and install it using apt:

sudo apt install ./barbara-core-manager_<version>~jammy1_amd64.deb
# or
sudo apt install ./barbara-core-manager_<version>~noble1_amd64.deb
# or
sudo apt install ./barbara-core-manager_<version>~bullseye1_amd64.deb
# etc.

RHEL / AlmaLinux​

Choose the .rpm file that matches your RHEL/AlmaLinux major version and install it using dnf:

sudo dnf install ./barbara-core-manager-<version>.el8.x86_64.rpm
# or
sudo dnf install ./barbara-core-manager-<version>.el9.x86_64.rpm
# or
sudo dnf install ./barbara-core-manager-<version>.el10.x86_64.rpm

Running Barbara Core Manager​

Installation creates a binary named:

barbara-core-manager

Because it needs to:

  • create and manage Core instances
  • configure virtual networking and NAT

it must be run with root privileges:

sudo barbara-core-manager

This command launches the interactive wizard documented in the next section.

Wizard walkthrough

Step 1 — Welcome screen​

When you run barbara-core-manager on a system where no Core instance has been created yet, the following screen appears:

Barbara Core Manager

No Barbara Core was found.

This setup wizard will guide you through configuring a new Barbara Core instance.

You will be asked to specify:
  • Number of CPU cores
  • Amount of RAM in MB
  • Disk size in GB
  • NAT network IP range
  • Host network interface for port forwarding
  • Port forwarding rules

Press → or Enter to begin, or 'q' to quit.

What this means​

  • The tool has checked the system and did not find an existing Core instance.
  • It clearly lists all the configuration points it will ask about.
  • No changes are made until you confirm the final summary later in the process.
  • Right arrow (→) or Enter → continue to the next step
  • q → exit immediately without creating anything

Step 2 — Selecting CPU cores​

The next screen asks how many CPU cores (vCPUs) should be assigned to the Core VM:

How many CPU cores do you want to assign to Barbara Core?

Host has 4 cores
Enter a value between 1 and 4.

> 2

Press → or Enter to continue, ← to go back, or 'q' to cancel.

Explanation​

Barbara Core runs as a virtual machine. The number of vCPUs you assign here is the number of host CPU cores that will be reserved for that VM.

The wizard:

  • Detects the total number of cores on the host
  • Enforces a minimum of 1 and a maximum equal to the detected core count

If the host has 8 cores, for example, you might see:

Host has 8 cores
Enter a value between 1 and 8.

Recommendations​

  • For testing or small demos, assigning 1–2 cores is usually enough.
  • For production or heavier workloads, assign more cores according to:
    • The size and number of workloads you will deploy on this Core
    • The total available capacity of the host

Avoid allocating all host cores to the VM unless the host is dedicated to Barbara Core.
The host OS and other services need CPU cycles as well.

  • → / Enter → confirm the chosen number and go to the next step
  • ← → return to the previous screen
  • q → abort the wizard without creating the instance

Step 3 — Assigning RAM​

The wizard then asks how much RAM (in MiB) should be assigned to the VM:

How much RAM (in MiB) do you want to assign to Barbara Core?

Host has 3883 MiB available

Enter a value between 2048 and 3883.

> 2048

Press → or Enter to continue, ← to go back, or 'q' to cancel.

Explanation​

  • The wizard measures how much memory is currently available on the host and shows it in the line:

    Host has <AVAILABLE> MiB available

  • It enforces a minimum of 2048 MiB for the Core VM:

    Enter a value between 2048 and <AVAILABLE>.

This prevents creating under-provisioned instances that might not be able to run the OS and workloads reliably.

Recommendations​

  • 2 GiB (2048 MiB) — acceptable for:

    • Small demo environments
    • Lightweight test workloads

  • 4 GiB or more — recommended for:

    • Production environments
    • Edge nodes that will host multiple containers or services

Make sure there is enough RAM left on the host so that:

  • The host OS remains stable
  • Other processes on the host do not run out of memory
  • → / Enter → confirm the selected amount of RAM and proceed
  • ← → go back to the CPU selection step
  • q → cancel the wizard

Step 4 — Configuring disk size​

The next screen determines how much disk space (in GB) will be permanently assigned to the Core VM:

How much disk (in GB) do you want to assign to Barbara Core?
Note: disk size cannot be modified after creation.

Host partition: 96 GiB total, 85 GiB free
Enter a value between 16 and 85 GB.

> 16

Press → or Enter to continue, ← to go back, or 'q' to cancel.

Explanation​

Barbara Core Manager creates a virtual disk image for the VM.
This image lives on a host partition, and its size is fixed at creation time.

  • The wizard reads the host partition size and free space:

    Host partition: <TOTAL> GiB total, <FREE> GiB free

  • It enforces:

    • A minimum of 16 GB for the VM disk
    • A maximum equal to the current free space on that partition

Important: disk size is immutable​

Disk size cannot be modified after creation.
If you later realize that you need more disk space, the procedure will be:

  1. Decommission the current instance
  2. Create a new Core instance with a larger disk

This makes it especially important to choose a sensible size from the start.

Recommendations​

  • 16 GB

    • Suitable for small tests

  • 32–64 GB

    • Reasonable starting point for standard environments
    • Enough for OS, and a moderate number of workloads

  • More than 64 GB

    • Consider if the node will store significant application data locally

Also ensure there is extra free space on the host partition for:

  • Other host services and system updates
  • → / Enter → confirm the selected disk size and move on to networking
  • ← → go back to the RAM configuration step
  • q → cancel without creating the instance

Step 5 — Selecting the NAT network IP range​

After defining compute and storage, the wizard configures networking for the Barbara Core instance.
The first networking step is selecting the IP range for the internal NAT network:

Select the IP range (CIDR) for the Barbara Core network:

> 192.168.234.0/24

Press Enter to confirm, or 'q' to quit.

What this step does​

Barbara Core Manager will create a private, isolated network dedicated to the Core instance:

  • It uses a NAT (Network Address Translation) gateway.
  • The Core VM receives its IP address from this network via DHCP.
  • Port forwarding rules (configured later) will map host ports into this network.

This ensures that the Core instance does not directly join the host LAN with a bridged interface.
Instead, it lives in a controlled, isolated IP range.

Requirements for the IP range​

The CIDR you select must not conflict with any existing networks reachable from the host:

  • Host LAN segments (e.g. 192.168.0.0/24, 192.168.1.0/24)
  • VPN networks used on the host
  • Corporate and datacenter subnets
  • Other virtual networks (Docker, LXD, other hypervisors)

If there is overlap, you may experience:

  • Routing problems (packets taking the wrong path)
  • Inability to reach services exposed through port forwarding
  • Confusing network behavior that is hard to debug

The wizard does not automatically detect all external conflicts.
It is the responsibility of the operator to choose a safe subnet.

Choosing a safe subnet​

Some example ranges that are usually safe in typical environments:

  • 192.168.234.0/24
  • 10.123.45.0/24
  • 172.31.200.0/24

Rough guidelines:

  • Prefer a range that is not in use anywhere else you know of.
  • Avoid extremely common home/office ranges such as:
    • 192.168.0.0/24
    • 192.168.1.0/24
    • 10.0.0.0/24
  • Enter → confirm the selected CIDR and proceed
  • q → quit the wizard immediately

Step 6 — Selecting the host network interface​

Next, the wizard asks which host network interface should be used for port forwarding:

Select host network interface for port forwarding:

 ▶ ens33 (192.168.206.128)

Use ↑/↓ to navigate, → or Enter to select, ← to go back, q to quit.

Purpose of this step​

The chosen host interface is the one that:

  • Receives incoming traffic from the rest of the network
  • Is used as the “external” side of the NAT configuration
  • Becomes the anchoring point for all port forward rules

In other words, if a client connects to http://<host-ip>:80, the <host-ip> is the IP address of the interface you select here.

Interface list​

The list may include:

  • Physical Ethernet interfaces (e.g. eth0, ens33, enp3s0, etc.)
  • Wi-Fi interfaces (e.g. wlan0)
  • Virtual interfaces (bridges, bonds, VLANs, docker bridges, etc.)

Each entry shows:

  • The interface name
  • Its primary IPv4 address in parentheses

Recommendations​

  • Choose the interface that is connected to the network where your users or systems are:

    • For a server on a LAN, that is usually the main wired interface (eth0, ens33, etc.).
    • For a compact edge device on Wi-Fi, it may be wlan0.

  • Avoid selecting:

    • Host-only local bridges (unless you really intend to isolate access that way).
    • docker0 or other container bridges, unless you have a very specific advanced use case.
  • ↑ / ↓ → move the selection cursor between interfaces
  • → / Enter → confirm the chosen interface and go on to port forwarding
  • ← → go back to the NAT network range selection
  • q → quit without saving

Step 7 — Configuring port forwarding rules​

The last step before the summary is defining which ports on the host should be forwarded to the Core instance.

Initial screen (no rules defined yet):

Port forwarding configuration
Use this step to define port forwards for Barbara Core.
Only ports listed here will be accessible from the network.

**Note:** ports must be unique and in the range 1–65535.

Use ↑/↓ to select, 'd' to delete, 'n' to add new, Enter to continue.

At this point:

  • The list of defined forwards is empty.
  • Nothing is exposed from the Core VM to the outside world yet.

Adding a new forwarding rule​

Press n to create a new forwarding rule:

Enter port number:
Protocol (↑/↓ to change): TCP

Press Enter to add, ← to go back, or q to quit.

You must:

  1. Enter a port number between 1 and 65535.
  2. Select the protocol using the arrow keys (TCP/UDP/Both).
  3. Press Enter to confirm and add the rule.

Example: adding HTTP on port 80​

After adding a rule for port 80/TCP, the screen might look like:

Port forwarding configuration
Use this step to define port forwards for Barbara Core.
Only ports listed here will be accessible from the network.

**Note:** ports must be unique and in the range 1–65535.

Defined forwards:
▶ 80 → TCP

Use ↑/↓ to select, 'd' to delete, 'n' to add new, Enter to continue.

Internally, this means:

  • Incoming connections to port 80 on the host’s selected interface
  • Will be forwarded to port 80 on the Core instance inside the NAT network

Managing the list​

From the port forwarding screen:

  • ↑ / ↓ → move the selection across already defined rules
  • n → add a new rule (as shown above)
  • d → delete the currently selected rule
  • Enter → confirm the current set of rules and move on to the final summary
  • ← → go back to the host interface selection
  • q → quit the wizard

Recommendations​

  • Only forward the ports that are strictly needed.
  • Typical examples:
    • 80/TCP — HTTP access to services running inside Barbara Core
    • 443/TCP — HTTPS access
  • Additional ports may be forwarded depending on your workloads and protocols.

Remember that security hardening (firewalls, TLS termination, authentication) should be handled according to your organization’s policies.

Step 8 — Final configuration summary​

Before creating the instance, the wizard shows a complete summary of the chosen configuration:

Barbara Core configuration summary:

  • CPU cores:               2
  • RAM:                     2048 MB
  • Disk size:               16 GB
  • Network:                 192.168.30.0/24
  • Port forward interface:  ens33
  • Port forwards:
      ↳ 80 → TCP

Press Enter to create and launch the Barbara Core instance.
Press ← to go back or 'q' to quit.

Purpose of this step​

This is the last chance to review and correct any values before Core Manager:

  • Allocates compute resources
  • Reserves disk space
  • Configures networking and NAT
  • Applies port forwarding rules
  • Downloads and boots the Core image

If something looks wrong (for example, disk too small or wrong subnet), press ← to go back and adjust it.

  • Enter → start the creation and launch process
  • ← → go back to the port forwarding configuration
  • q → exit without creating the instance

Step 9 — Creating and launching the instance​

Once the configuration summary is confirmed, Barbara Core Manager performs several actions automatically:

  1. Downloads the Barbara Core image (if it is not present yet).
  2. Validates its integrity.
  3. Creates the virtual disk image with the selected size.
  4. Sets up the NAT network for the Core instance.
  5. Configures port forwarding rules on the chosen host interface.
  6. Boots the Barbara Core virtual machine.

When the process completes successfully, you will see a screen similar to:

Barbara Core instance successfully created

Scan this QR code to register it:

<ASCII QR CODE>

Or alternatively, open this URL to register it:
https://app.barbara.tech/qr?id=<barbara-id>

Press any key to exit

Registering the new Core instance​

There are two ways to register the instance with Barbara:

  • Scan the QR code with a supported application.

  • Open the URL in a browser:

    https://app.barbara.tech/qr?id=<barbara-id>

The <barbara-id> uniquely identifies this Core instance inside the Barbara Platform.

Exiting the wizard​

When you press any key, Barbara Core Manager exits.
The Core instance continues running in the background.

To inspect its status or manage it locally again, rerun:

sudo barbara-core-manager

Managing an existing Barbara Core instance

When you start Barbara Core Manager on a system where a Core instance has already been created, the wizard does not ask for provisioning parameters again.
Instead, it shows a status and actions view.

Two examples are shown below: one while the instance is still booting, and another when it has fully started and telemetry is available.

Instance view while Core is booting​

Barbara Core Manager

  • Barbara Core ID: <barbara-id>
  • Status: running
  • CPU: 50.0% (2 vCPU)
  • RAM: 107 / 2048 MiB (5%)
  • Interfaces:
      • Device still booting...
  • Mounts:
      • Device still booting...
  • Port forwarding via ens33:
      • 80 (TCP)

Select an action:

 ▶ Start
   Stop
   Edit
   Delete

Use ↑/↓ to navigate, press Enter to select, 'q' to quit.

At this stage:

  • The VM is already running, but:
    • The guest agent has not yet provided detailed information about network interfaces and mounted filesystems.
    • CPU and RAM usage are starting to be collected, but other metrics may still show placeholders.

You can already see:

  • The Barbara Core ID (<barbara-id>)
  • Current status (e.g. running)
  • Allocated vCPUs and RAM
  • Port forwarding configuration via the selected host interface

Instance view when Core is fully running​

After the instance finishes booting and the guest agent is ready, Barbara Core Manager shows richer telemetry:

Barbara Core Manager

  • Barbara Core ID: <barbara-id>
  • Status: running
  • CPU: 4.3% (2 vCPU)
  • RAM: 1308 / 2048 MiB (63%)
  • Interfaces:
      • ens1 (52:54:00:aa:48:79)
          ↳ IP: 192.168.30.2
          ↳ RX 0.0 MB, TX 0.0 MB
      • docker0 (02:42:52:3a:54:44)
          ↳ IP: 172.17.0.1
          ↳ RX 0.0 MB, TX 0.0 MB
  • Mounts:
      • /data: 4.2/11.4 GiB
      • /cache: 0.0/0.1 GiB
      • /: 1.1/2.7 GiB
  • Port forwarding via ens33:
      • 80 (TCP)

Select an action:

 ▶ Start
   Stop
   Edit
   Delete

Use ↑/↓ to navigate, press Enter to select, 'q' to quit.

Reading the telemetry​

  • CPU

    • Instantaneous CPU usage as a percentage, plus the number of vCPUs.

  • RAM

    • Current usage vs total allocated to the Core VM, plus the percentage.

  • Interfaces

    • Logical name (e.g. ens1, docker0)
    • MAC address
    • IP address inside the Core internal network or Docker bridge
    • Basic traffic counters (RX/TX)

  • Mounts

    • Mountpoints inside the Core instance (e.g. /data, /cache, /)
    • Used vs total capacity in GiB

  • Port forwarding

    • Host interface used (e.g. ens33)
    • Ports and protocols exposed (e.g. 80 (TCP))

Available actions​

At the bottom of the screen, the available actions are:

  • Start
  • Stop
  • Edit
  • Delete

These actions are always present, though some may be effectively no-ops depending on the current state (e.g. Start when already running).

Navigation:

  • ↑ / ↓ → move the selection cursor between actions
  • Enter → execute the selected action
  • q → exit Barbara Core Manager

Edit action: what can be changed​

The Edit action opens a configuration wizard similar in style to the initial creation flow, but with an important constraint:

  • The disk size step is omitted, because the disk size cannot be changed once the instance has been created.