How you receive VoisX Orchestrate
VoisX Orchestrate runs on your own Kubernetes cluster. You receive two things from us, separately: the signed software and your licence file. Both come from the VoisX portal, and both are checked on your side before they are trusted: voisctl checks the software's signature before it installs anything, and Orchestrate checks the licence's signature before it unlocks anything.
Nothing secret travels to you. The keys that sign the software and the licence never leave VoisX. The matching public keys are built into voisctl and into Orchestrate, so you don't install or manage any key yourself.
Your portal account
The VoisX portal is where you get both the software and the licence.
- When you sign up, we add the people you name to your organization on the portal, by email address.
- Each person opens the portal, registers (or signs in) with that email address, and sets up an authenticator app at the first sign-in.
- After sign-in they see your organization's licences, the downloads your licences cover, and your organization's recent downloads.
Only people we added to your organization see anything. To add or remove someone, contact us.
The portal is not open to customers yet. Until it is, we send your licence file and download links directly to your named contact, and the release key fingerprint by a second channel. Everything else on this page works the same.
Choose how you get the software
There are two ways, and you can change later.
| Online | Offline (air-gapped) | |
|---|---|---|
| For | A cluster that can reach the internet | A cluster with no internet access |
| What you get | A registry login: a read-only credential file for the VoisX release registry, valid for your licence term | A signed bundle file to download, plus optional model packs |
| Install with | voisctl install --from-registry ... --pull-secret <file> | voisctl install --bundle <file> |
| Images run from | Our registry directly, or your own registry after voisctl import copies them in | Your own registry, after voisctl pushes them in |
| Models | Built in your cluster from the internet, or from model packs | From model packs, or the speech models in the bundle |
Either way it is the same release, signed the same way, and voisctl runs the same checks.
The VoisX release registry is not open yet. Until it is, every site installs and upgrades from the bundle, as an offline site does.
Online: registry login
We issue a registry credential for your organization with your licence. It is a small file: keep it private, like a password. It is read-only, it works only for VoisX Orchestrate releases, and it expires with your licence. At renewal we send a new one.
voisctl reads the signed release information from the registry, checks its signature and version, then installs with every image pinned to the signed digest. You can let your cluster pull straight from our registry, or copy every image into your own registry first. See Install.
Offline: download the bundle
On the portal, open Downloads, choose the release, and download:
| File | What it is |
|---|---|
vois-orchestrate-<version>-base-linux-amd64.tar | The base bundle: everything the release needs, signed. See What is in the bundle. |
SHA256SUMS | The checksum of every file in the release. |
| Release notes | What changed, the requirements, and the release key fingerprint. |
Each download link opens for 15 minutes, so start the download soon after you click. Bundles are tens of gigabytes: use a download tool that can resume. The portal shows each file's size and SHA-256 checksum.
Move the files into your network by whatever route your security process allows. The route doesn't affect integrity: a file changed on the way fails the checks below.
For a site that can't download at all, we can ship the release on encrypted physical media. Contact us to arrange it.
What is in the bundle
A bundle is built for one release and one node architecture, normally linux/amd64. Run voisctl inspect --bundle <bundle> to see the version, the platform and every image inside.
| Part | What it contains |
|---|---|
| Signed manifest | The packing list: the version, the platform, and the SHA-256 digest of every image, the chart, every tool file and every stored model file. It is signed with our release key. Everything else in the bundle is checked against it. |
| Orchestrate images | The console, API, Model Gateway, License Service, audit service, workers, deployment controller and the other Orchestrate services. Each image we build carries its own signature, a software bill of materials (SBOM) and a build provenance record. |
| Third-party images | PostgreSQL, Temporal and its web UI, Keycloak, Open Policy Agent, LiveKit, Qdrant, MinIO and Redis. Also the images the in-cluster build jobs run: Kaniko, BusyBox and the MinIO client. |
| Speech models | Prebuilt images for the baseline speech models: Whisper tiny.en and base.en for speech to text, and the Piper en_US-lessac-medium voice for text to speech. Voice agents work offline with these from the first install. |
| Cluster add-ons | cert-manager, CloudNativePG and its Barman Cloud plugin, KServe, OpenBao, Harbor and ingress-nginx: each chart, its settings and every image it uses, by digest. voisctl install --with-prerequisites installs them. |
| Model runtime images | The images in-cluster model builds start from (Ollama, vLLM for CPU, llama.cpp, Whisper, Piper and the other CPU runtimes), with every dependency already inside, so a model build needs only its weights. |
| Code-agent images | The base images for code agents, and an offline Python package index that code-agent builds install from. They are used only if you turn code agents on. |
| Vulnerability database | The image scanner's (Trivy's) vulnerability database, dated, for your registry to scan with offline. voisctl imports it. See Requirements. |
| Helm chart | The vois-orchestrate chart at this release. |
voisctl | The command-line tool that verifies, imports, installs and upgrades, in the bundle's tools/ directory. |
The database migrations are inside the API image. The API applies them itself when it starts, so there is no separate database step.
What isn't in the bundle
- Your container registry. You bring one that your nodes can pull from;
voisctlpushes everything into it. See Requirements. - Kubernetes itself. You install onto the Kubernetes cluster you already run: OpenShift, AKS, EKS, GKE, RKE2 or upstream Kubernetes. See Requirements. For an evaluation on one server, k3s installs offline from its own release files: see Evaluation or pilot on a single server.
- GPU model runtimes. The current bundle is CPU-only: about 13 GiB, 71 images. vLLM for GPU, Triton and SGLang are not in it. See Requirements.
- Models beyond the baseline speech models. Bring their weights through the local model store.
Check the signatures
Always check what you received before you install it. voisctl has the VoisX release public key built in, so you don't need a key file.
-
Check the files arrived whole, in the directory where you downloaded them:
sha256sum -c SHA256SUMS --ignore-missing -
Compare the release key fingerprint in the release notes with the one we sent you separately (by email from your VoisX contact, or on a call). They must match.
-
Check the signature and every part of the bundle:
mkdir bundle
tar -xf vois-orchestrate-<version>-base-linux-amd64.tar -C bundle
./bundle/tools/voisctl verify --bundle ./bundleverifychecks the manifest's signature against the built-in VoisX key first, then re-hashes every image layer, the chart, every tool file and every stored model file against the signed digests, and checks each image's own signature. It ends withOK version <version> is intact and signed.If it reports anything else, don't use the bundle. Contact us for another copy.
The example runs the voisctl that came in the bundle. If you already have a voisctl you trust, for example from a release you verified before, check a new bundle with that copy instead.
Every later step checks again. voisctl import, install and upgrade verify before they push anything, and after pushing they read each image back from your registry and compare its digest with the signed manifest. The running Deployments are pinned to those digests.
Check image signatures in your own registry
Each image carries a signature, an SBOM and a provenance record made with our image signing key, which is vouched for by the signed manifest. To check images in your registry with your own tools, export that key and use cosign:
./bundle/tools/voisctl verify --bundle ./bundle --export-cosign-key cosign.pub
cosign verify --key cosign.pub --insecure-ignore-tlog=true registry.example.internal:5000/vois-orchestrate/api@<digest>
--insecure-ignore-tlog is correct here: the signatures are key-based and are not published to a public transparency log, which an air-gapped site couldn't reach anyway.
Your licence
Your licence is a signed file that the License Service checks inside your cluster against the VoisX licence key built into it. You download it from the portal's Licences list, activate it for your cluster, and apply it on the console's Licence page. See Licence.
The licence and the software are independent: a renewal is a new licence file, not a new bundle, and an upgrade keeps your licence.
Model packs
Model packs carry ready-to-use models for a site that can't download them: for example a CPU starter pack of small chat models, a speech pack, an embeddings pack and a GPU pack. We can also build a pack of the catalog models you choose. Each pack is a separate signed file with its own SHA256SUMS, dated rather than tied to one release, and names the oldest Orchestrate release it works with. The portal lists the packs your licence covers.
Inside a pack:
| File | What it is |
|---|---|
pack.json.signed | The packing list, signed with our release key: every model, and the size and SHA-256 of every file |
pack.json | The same list, readable |
LICENSES.txt | The licence of each model. Read it before you use the models |
SHA256SUMS | The SHA-256 of every model file, for sha256sum -c |
models/ | The model weights |
Import a pack after the install, with a platform admin's API token:
export VOIS_API_URL=https://orchestrate-api.example.com VOIS_ADMIN_TOKEN=<token>
./bundle/tools/voisctl models import-pack --pack vois-orchestrate-models-cpu-starter-<date>.tar --add
voisctl checks the pack's signature, every file and your installed version before it imports anything, and prints each model's licence. The models then appear in your local model store. With --add, each one is also added to your models: its image builds in your cluster, and you deploy it from the Models page. Without --add, add them yourself from Models, Add model, where they show as Local store. Add --only <name> to import just some of a pack. See Models offline.
voisctl refuses a pack that is not signed with our release key.
Model packs are not available to download yet. Until they are, ask us to include stored models for your local model store with your bundle, and import them with voisctl models push. See Models offline.
Upgrades
Each new release appears on the portal (offline) or in the registry (online) under its version number. You check it the same way and apply it with voisctl upgrade, which keeps your settings and your licence, refuses a downgrade and checks the result. See Upgrade.