App Garden | Kamiwaza Docs

Version: 1.0.1 (Latest)

What is App Garden?

App Garden is a catalog of ready-to-run apps (dashboards, demo UIs, tools) that you can deploy in your Kamiwaza environment. It handles all the technical setup for you, so you can focus on using the app.

For documentation on specific apps available in the App Garden, please check the Extensions section. If you want to build and ship your own app, service, or tool for Kamiwaza, see the Developer Guide.

Key Features

• One‑click deploy: Launch apps directly from the catalog
• Automatic routing: Each app gets a stable HTTPS URL through the platform gateway
• Browser-based access: Users can open deployed apps directly from the Kamiwaza UI
• AI‑ready: Apps can automatically connect to your deployed models (OpenAI‑compatible)
• Simple lifecycle: Start, stop, and remove from the UI
• Remote catalog sync: Pull templates from the remote catalog with version filtering
• Template variables: Environment values can reference routing-aware variables

Getting Started

1. Open the App Garden page in the Kamiwaza UI.
2. If the catalog is empty, click Import/Refresh (or ask your administrator to enable the remote catalog).
3. Browse the list and select an app to view details.
4. Click Deploy. App Garden will start the containers and assign a URL.
5. Click Open to launch the app in your browser.

Deploying and Managing Apps

• Deploy: Choose an app and click Deploy. Most apps work out of the box with defaults.
• Access: After deployment, use the Open button or copy the provided URL.
• Status: Check deployment status, ports, and health in the App Garden page.
• Stop/Remove: Stop or remove an app anytime from its details panel.

Using AI Models with Apps

Many apps can use models you’ve deployed in Kamiwaza. App Garden provides standard OpenAI‑compatible environment variables to the app automatically, so most apps need no manual configuration.

Tips:

• If your app has a model preference setting (e.g., fast, large, reasoning, vision), choose it in the app’s configuration panel before deploying.
• Ensure at least one model is deployed if your app requires AI.

Remote template catalog

App Garden templates can sync from a remote catalog. Administrators can choose the approved catalog source for their environment and refresh the catalog when new templates are published.

Template variable substitution

Template environment variables can reference routing-aware values. Examples include:

• {openai_base_url}: the OpenAI-compatible base URL selected by the platform for the model, typically path-based in current deployments (no trailing /v1)
• {openai_path_base_url}: the explicit path-based OpenAI base URL (no trailing /v1)
• {model_path_url}: full HTTPS URL to the selected model (path-based)
• {app_path_url}: full HTTPS URL to the app (path-based)

Reserved KAMIWAZA_* and FORWARDAUTH_SIGNATURE_SECRET environment keys are protected and cannot be overridden by user input.

When to Use App Garden

• You want a quick, reliable way to run common tools and demos
• You prefer a click‑to‑deploy experience over manual Docker commands
• You need apps that “just work” with your existing model deployments

Troubleshooting

• No apps in the catalog: Click Import/Refresh on the App Garden page, then retry. If still empty, ask your administrator to enable the default catalog.
• App won’t start: Retry Deploy. If it persists, Stop/Remove and deploy again.
• Can’t reach the app: Use the Open button from the UI. Avoid direct container ports; App Garden routes traffic for you.
• AI features not working: Verify at least one model is deployed and healthy. Some apps expose a preference for model type—set it before deployment.

Ephemeral Sessions

When deploying an app, you can enable Ephemeral session mode. This automatically cleans up the deployment when you log out or your session expires.

• Check the box during deployment to make the app ephemeral
• Ephemeral apps are automatically purged on logout or session timeout
• Persistent apps (unchecked) remain running until manually stopped

This is useful for demo environments or when you want automatic cleanup of test deployments.

Session tokens for apps

When an app is deployed in ephemeral mode, it receives a session token and endpoints it can call to keep the session alive or request cleanup:

• KAMIWAZA_APP_SESSION_TOKEN
• KAMIWAZA_APP_SESSION_HEARTBEAT_ENDPOINT (/api/apps/sessions/heartbeat)
• KAMIWAZA_APP_SESSION_ENDPOINT (/api/apps/sessions/end)

Apps should send periodic heartbeats when they remain active. Ending the session (or logging out) triggers cleanup of the associated deployment.

Advanced Options

App customization is coming soon!