VENI-AIDOCS
01 / Get started

Get started ​

To develop, choose how you'll run the platform — everything on your machine, or against a shared cloud environment where you only run your own app. New to the model? Read Platform architecture.

Just want to see it run? One command.

dev-up.sh brings up the whole local platform — Redis, the Shell's database, and a fully-configured Shell plus Veni builder — in about two minutes (needs Docker + Bun). Download it then bash dev-up.sh, or follow Local setup step by step.

Setup Alocalhost
Everything local

Run the whole platform on your machine — the Shell, its services and each app. Full control, works offline; just more to run.

  1. Start the Shell and its services
  2. Run or build an app against it
Local setup →
Setup Bveni.dev.venizia.ai
Against a cloud environment

The Shell and platform already run in the cloud (Dev). You run only your app locally and register it there — no local Shell to stand up or maintain.

  1. Run your app locally, pointed at Dev
  2. Register & open it on Dev
Cloud setup →

Prerequisites ​

Install these once:

  • Docker (Compose v2) — the backing services.
  • Bun — every API/UI dev server, migration and seed.
  • Node 20.12+ — the Shell UI's build imports util.styleText. 22 LTS is the safe pick; on the 21.x line it needs 21.7+, so 21.0–21.6 fails despite the higher number.
  • git · make · openssl · curl — cloning, the Makefile, the signing secret, and the veni CLI.

Verify them in one shot before you clone anything — any MISSING or TOO OLD line is what to fix first:

bash
for c in docker bun git make openssl curl; do
  command -v "$c" >/dev/null 2>&1 && echo "  ok       $c" || echo "  MISSING  $c"
done
docker compose version >/dev/null 2>&1 && echo "  ok       docker compose v2" || echo "  MISSING  docker compose v2"
if command -v node >/dev/null 2>&1; then
  # Probe the export the build actually needs, not the major version — 21.4
  # is newer than 20.12 and still lacks it.
  node -e 'process.exit(require("node:util").styleText ? 0 : 1)' 2>/dev/null \
    && echo "  ok       node $(node -v)" \
    || echo "  TOO OLD  node $(node -v), need 20.12+ / 21.7+ / 22+"
else echo "  MISSING  node"; fi
  ok       docker
  ok       bun
  ok       git
  ok       make
  ok       openssl
  ok       curl
  ok       docker compose v2
  ok       node v22.11.0

That last line is the one people get wrong. A major-version check passes 20.11 and 21.4, and both then die inside vite's config load — so the failure surfaces as a Shell UI that never goes healthy, not as a version error. dev-up.sh runs this exact probe and stops early.

The moving parts ​

What it isRuns at
ShellHost app — auth, routing, app registry, the launchpad:5173 / :3000
AppsRemote satellites (HRM, Drive, …) federated into the Shelleach its own ports
Veni builderDev tooling — scaffolds new apps, serves the veni CLI:3011 / :3010
Shell servicesRedis (cache + event bus), MinIO (object storage); Keycloak (SSO) in productionsee Services

Every host port a local stack uses is in one place — Ports at a glance — check it first when something won't bind.

Where to go next ​

  • Services — every service and its docker-compose, ports, and databases.
  • Shell → Configure — auth providers (Local / Google / Keycloak / OIDC).