Configuration Reference

The VENI-AI platform uses environment variables for all configuration. The Shell API validates these variables at startup using Zod to ensure system integrity.

---

🐚 Shell API Variables (shell/api/.env)

These variables are defined in shell/api/env.example and are required for the Shell API to function correctly.

1. Application Core

Variable	Default	Description
APP_ENV_PORT	3000	The HTTP port the API listens on.
APP_ENV_SERVER_BASE_PATH	/api	The base path for all API routes.
APP_ENV_APPLICATION_NAME	shell	The internal name of the application.
APP_ENV_APPLICATION_TIMEZONE	Asia/Ho_Chi_Minh	The timezone for the application.
DEBUG	true	Enables verbose logging and error messages.
NODE_ENV	development	development, production, or test.

2. Database & Cache

Variable	Default Value	Description
APP_ENV_DATABASE_URL	postgresql://shell:shell@localhost:15433/shell_db	PostgreSQL connection string.
APP_ENV_REDIS_URL	redis://localhost:16379	Redis connection for caching and state.

3. Identity & Security

Variable	Default	Description
APP_ENV_JWT_SECRET	8fc28702811e...	Secret for HS256 signing (Fallback/Local Dev).
APP_ENV_JWT_PRIVATE_KEY	-	RSA Private Key (PEM) for RS256 signing.

---

🔑 Generating Secrets & Keys

For the platform to be secure, you must generate unique secrets and keys for your environment.

1. Generate APP_ENV_JWT_SECRET (HS256)

Used for local development or when an RSA key is not provided.

# Using openssl
openssl rand -hex 32

# OR using Bun/Node
bun -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. Generate APP_ENV_JWT_PRIVATE_KEY (RS256)

The Shell uses this key to sign tokens with RS256. This enables remote apps to verify tokens via the public JWKS endpoint.

# 1. Generate a 2048-bit RSA private key
openssl genrsa -out private.pem 2048

# 2. Convert to PKCS#8 format (required by the Shell)
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out pkcs8.pem

# 3. Copy the content of pkcs8.pem to your .env file
# Ensure the multi-line string is properly handled in your env loader.

The Shell automatically derives the public component and serves it at /api/.well-known/jwks.json.

---

4. Keycloak Integration (OIDC)

Variable	Default	Description
APP_ENV_KEYCLOAK_URL	http://localhost:18080	Public Keycloak URL (reachable by browser).
APP_ENV_KEYCLOAK_REALM	veni-ai	The Keycloak realm name.
APP_ENV_KEYCLOAK_CLIENT_ID	veni-ai-platform	Client ID configured in Keycloak.
APP_ENV_KEYCLOAK_CLIENT_SECRET	y8fEBCBHdEPR...	Client secret for OIDC communication.
APP_ENV_KEYCLOAK_REDIRECT_URI	http://localhost:3000/api/auth/callback	Callback URL for OIDC flow.

5. Third-Party Auth (Optional)

Variable	Description
APP_ENV_GOOGLE_CLIENT_ID	Google OAuth client ID.
APP_ENV_GOOGLE_CLIENT_SECRET	Google OAuth client secret.

---

🎨 Shell UI Variables (shell/ui/.env.development)

Variable	Default	Description
VITE_API_URL	http://localhost:3000	Full URL to the Shell API.

---

🛰️ Satellite (SCS) Variables

Satellites require specific configurations to interact with the Shell.

API (api/.env)

Variable	Default	Description
APP_ENV_SHELL_JWKS_URL	http://localhost:3000/api/.well-known/jwks.json	URL for Shell's public keys.
APP_ENV_DATABASE_URL	-	Satellite-specific database connection string.

UI (ui/.env)

Variable	Default	Description
VITE_API_URL	-	Satellite's own API URL.
VITE_SHELL_URL	http://localhost:5173	URL of the Shell UI (for SSO redirects).

---

💡 Environment Best Practices

1. Local Dev: Use .env or .env.local files (automatically gitignored).
2. Production (K8s): Use Kubernetes Secrets or ConfigMaps.
3. Security: Never commit real keys or passwords. Use the provided .env.example as a template.