What Is VHT 1.x?¶

VHT 1.x is the original VeeaHub application toolkit.

It lets a developer take normal application code, wrap it as a secure Docker image, package it as a Veea application, and run it on a VeeaHub through Veea's application model.

If Docker is the engine, VHT 1.x is the set of rails around that engine: identity, signing, licenses, VeeaHub hardware permissions, persistent storage, app packaging, and Control Center integration.

The Simple Story¶

A VeeaHub can run containerized applications at the edge.

But VeeaHubs are not generic Linux boxes where every Docker command is wide open. They are managed edge devices. Apps may need to:

• run on ARM hardware such as VHC25
• access local devices like Bluetooth, Zigbee, serial, or radios
• publish HTTP ports
• store data across restarts
• expose a UI in Control Center
• prove who built the app
• prove which licenses/features it is allowed to use
• run safely beside other apps on the same hub or mesh

VHT 1.x exists to solve those packaging and trust problems.

The Mental Model¶

VHT 1.x has three big layers:

Most confusion comes from mixing these layers together. Keep them separate and VHT 1.x makes more sense.

Image: The Container With Veea Identity¶

A VHT 1.x image starts with a normal Dockerfile, but VHT adds secure metadata.

That metadata describes:

• app/container name
• version
• target architecture, such as arm32v7
• target platform, such as iesv2.5
• published ports
• persistent volumes
• device access
• requested feature licenses
• partner identity
• persistent image UUID

The source file that drives most of this is usually config.yaml.

For VHC25, the important target is:

Unsigned Images¶

Unsigned images are for local development on hubs that allow unsigned apps.

They use the reserved partner prefix:

FFFFFFFF

That prefix appears in image UUIDs, shell prompts, and volume names. It means "unauthenticated development identity", not a real partner.

Typical unsigned build:

vhc image build save --arch arm32v7 --unauth

Typical unsigned upload:

vhc hub access upload-image --hub-id <hub-name> \
  'build/unauth/arm32v7/<image-name>-arm32v7:<version>.unsigned.tar'

Then you create and start a container from VeeaHub Shell:

vhc hub access shell --hub-id <hub-name> --command "docker image ls"
vhc hub access shell --hub-id <hub-name> --command \
  "docker image create <image-id> --detach --publish <host-port>:<container-port>"
vhc hub access shell --hub-id <hub-name> --command "docker container start <container-id>"

Signed Images And Applications¶

Signed images are for authorized partner development, controlled testing, and release.

Instead of FFFFFFFF, signed images use a real partner prefix such as:

00000046

The signature and metadata tell the hub:

• who built the image
• whether the image is allowed to run
• which devices, capabilities, and features it may use
• whether the app matches the hub's active partner/license state

A signed application archive is built with:

vhc app build release
vhc app build verify build/<AppName>-<version>.tgz

That .tgz is the artifact uploaded to Control Center using the VHT1.x upload path.

Application: More Than One Container¶

In VHT 1.x, an application package is not just a Docker image.

It is a bundle that can contain:

• one or more signed image archives
• service metadata
• platform and architecture information
• application version metadata
• Docker service definitions for the hub runtime

This is why these names are different and should be chosen deliberately:

Changing one does not always change the others.

VeeaHub Shell: The Hub-Side Control Plane¶

VHT 1.x uses the VeeaHub Client command:

vhc

The local vhc CLI can talk to the hub's sideload API on port 9000.

For deeper runtime control, it uses VeeaHub Shell over SSH, commonly on port 9010:

vhc hub access shell --hub-id <hub-name>

Inside VeeaHub Shell, Docker commands are Veea-aware. They show Veea metadata such as P-UUID, partner prefixes, service states, and published ports.

Examples:

docker image ls
docker container ls --all
docker service list
docker volume ls

Use docker image ... and docker container ... for unsigned image sideload containers.

Use docker service ... for Veea application services created from signed app packages.

Licenses And Partner Identity¶

VHT 1.x is built around trust.

The hub checks whether an uploaded image or app is allowed to run. The important command is:

vhc hub access get-partner-id --hub-id <hub-name>

If it returns:

This matters because get-licenses can show developer licenses while the active partner ID is still FFFFFFFF.

If a signed app upload fails with:

Non-authorized partner id found

check get-partner-id before retrying. The hub may be telling you to use the unsigned path.

Ports, Volumes, And Devices¶

VHT 1.x asks you to declare what the app needs.

Common examples:

This is different from casual local Docker development. VeeaHub apps are expected to declare their needs so the runtime can enforce boundaries.

D-Bus: Talking To Veea Core¶

VHT 1.x apps can talk to VeeaHub platform services through D-Bus.

Useful services include:

• io.veea.VeeaHub.Info for serial, model, software, hardware, and mesh identity
• io.veea.VeeaHub.Networking for network information
• io.veea.VeeaHub.MqttControl for MQTT-related platform settings
• io.veea.VeeaHub.ReverseProxy for Control Center service cards
• io.veea.VeeaHub.ContainerControl for container/platform control surfaces

This is how an app becomes a real VeeaHub edge app rather than just a web server in a container.

Control Center UI Cards¶

Publishing a port lets the app answer on the LAN.

It does not automatically create a Control Center link.

To create a clickable UI:HTTP card, the running container must call the ReverseProxy D-Bus API:

1. RegisterReverseProxy(...)
2. ConfigureVeeaCloudAccess(...)

That registration is runtime state, so apps should do it on every start and retry until D-Bus is ready.

Why Web Apps Break In Control Center¶

Control Center does not open the app at:

/

It opens the app under a nested path:

/node/v2/proxy/<hub-serial>/<app-or-image-uuid>/http/<service-name>/

So root-absolute browser paths can escape the app:

/_next/...
/assets/...
/api/...
/devices

Good VHT 1.x web apps support both:

• LAN direct access: http://<hub-ip>:<port>/
• Control Center nested proxy access

That is why this documentation includes a dedicated Web UI Proxy Compatibility page.

How VHT 1.x And VHT 2.x Differ¶

VHT 1.x is Veea-specific. It uses vhc, secure image metadata, Veea application archives, and the legacy Control Center VHT1.x upload path.

VHT 2.x moves toward a more Docker-native workflow using vhc2, Docker contexts, Compose, Stack, and registries.

VHT 1.x apps and VHT 2.x apps can run side by side on the same VeeaHub Mesh. Keep commands and packaging workflows separate.

The "Oh, I Get It" Version¶

VHT 1.x is not just a build tool.

It is the old VeeaHub application system:

your code
  -> Docker image
  -> VHT secure image metadata
  -> unsigned dev image or signed partner image
  -> optional Veea application archive
  -> VeeaHub secure Docker runtime
  -> Control Center, D-Bus, ports, volumes, devices, and edge services

Once you see those layers, the rest of the VHT 1.x documentation is easier to read:

• template pages teach how image projects are shaped
• signed image pages teach trust and partner identity
• application pages teach packaging for Control Center
• upload/test pages teach hub-side runtime commands
• D-Bus pages teach how apps talk to Veea Core
• ReverseProxy pages teach how UI links appear in Control Center

Start with this mental model, then use VHC25 Quickstart For VHT 1.x or VHT 1.x Validated Workflows for the actual commands.