App Builder

Overview

The Komodo App Builder lets you create, build, and deploy containerized applications on the Komodo platform. Your apps run at https://{app-name}.{account-slug}.apps.{env-domain}.

App Builder:

1. Scaffolds application code from templates (FastAPI, Streamlit, React, multi-container)
2. Builds container images via the remote Build API by default — no local Docker, BuildKit, or AWS credentials required. Optional local BuildKit mode produces an image tarball and uploads it through the same Build API (prebuilt path); OAuth only, no client-side ECR push.
3. Deploys to the shared Komodo Data Apps environment
4. Connects AWS resources in your subaccount via mesh networking

Prerequisites

Account access and RBAC

App Builder requires both of these Komodo platform RBAC roles (not Snowflake database roles):

• komodo_connector:standard_user — baseline connector access
• komodo_connector:app_builder — grants App Builder capabilities (creating and listing apps, builds, infra mesh, secrets, and sharing)

If you don’t have App Builder access yet, contact the Komodo team.

1. Install the Marmot Development Kit — see Installation

2. Authenticate:

   uv run komodo login

   uv run komodo account set

   Confirm you have the RBAC roles listed in the note above.

3. Set up MCP (optional) — the recommended workflow uses an AI assistant. See MCP Server Setup to connect Cursor, VS Code, or Claude Desktop

No Docker, BuildKit, or AWS credentials are needed for the default remote build. Local mode (build_mode: local in MCP, or komodo build --local) needs BuildKit and buildctl on your machine; the image is still finalized (scan, ECR, signing) on the platform after upload.

Environment

App Builder operates against production. No environment configuration is needed.

Getting Started with MCP (Recommended)

The fastest way to build and deploy an app is through an AI assistant (Cursor, VS Code Copilot, Claude Desktop) connected to the Komodo MCP server. The MCP server provides 26 tools (15 app development + 6 secrets + 5 sharing) with detailed workflow instructions that guide the assistant through the entire process.

Example Conversation

You: “Use Komodo MCP to build and deploy an application named komodo-query-tool with a React frontend that can run Komodo SQL queries via a backend API. The backend should use a Komodo Snowflake connection.”

The assistant will automatically:

1. Call get_available_templates to list templates
2. Call scaffold_app to generate the project — application code, Dockerfile, devfile.yaml, and README
3. Call validate_devfile to verify the configuration
4. Call build_app to build via the remote Build API, then register the app
5. Print the app_id and every entry in service_urls (one URL per service)
6. Ask whether you want to poll get_app_status until the app is RUNNING or FAILED

Then, for example:

You: “Now list my apps”

You: “My app needs to connect to my RDS database”

The assistant will guide you through mesh networking to connect your subaccount’s RDS instance to your deployed app.

Available MCP Tools

Category	Tools	Purpose
Scaffolding	scaffold_app, get_available_templates, validate_devfile, generate_devfile	Create and validate app projects
Build & Deploy	build_app, get_build_scan_report, cancel_build	Remote image build; Trivy report; cancel build job
App Management	list_apps, get_app, get_app_status, get_app_logs	Monitor and inspect running apps
Lifecycle	enable_app, disable_app, delete_app	Start, stop, and remove apps
Secrets	create_secret, get_secret, list_secrets, update_secret, delete_secret, share_secret	Store and manage secrets for apps
Sharing	list_grantable_roles, list_app_permissions, grant_app_role, revoke_app_role, list_account_users	View and manage app access

See the App Builder MCP Tools Reference for full details.

Templates

App Builder provides six templates:

Template	Language	Description
fastapi	Python	FastAPI web API with health check and sample endpoints
streamlit	Python	Streamlit data app with charts and sample data
react	JavaScript	React SPA served via nginx
multi-container	Python	Two-service setup (API + worker) with docker-compose for local dev
react-advanced	JS + Python	React frontend with FastAPI backend
restate-agent	Python	Standalone durable app on the platform-managed Restate runtime

Each template generates a complete project: source code, Dockerfile, devfile.yaml, and README.md.

Durable workflows (Restate)

You can add Restate durable execution to a new FastAPI app by passing restate=true to scaffold_app (MCP) or the equivalent CLI flag: the tool injects metadata.komodo.restate, restate-sdk, an example workflow module, and an ASGI router so the Restate runtime can call back into your service on the paths it expects.

For what to configure in the devfile, which HTTP paths must reach the Restate handler, how in-cluster registration works, and multi-container notes, see Durable workflows (Restate).

Multi-Container Apps

The multi-container and react-advanced templates create projects with multiple services managed as a single app. One root devfile.yaml declares all services, one .app file tracks a single app_id, and the platform orchestrates parallel builds and ordered deployments automatically.

Template	Services	Primary	Layout
multi-container	api + worker	api	api/ and worker/ subdirectories
react-advanced	frontend + backend	frontend	Root for frontend, backend/ subdirectory

Project structure

my-app/
├── devfile.yaml          # Single devfile for ALL services
├── .app                  # Single app ID (created on first deploy)
├── api/
│   ├── Dockerfile
│   ├── main.py
│   └── requirements.txt
└── worker/
    ├── Dockerfile
    ├── main.py
    └── requirements.txt

How builds work

Remote (default) — when you run build_app (MCP) or komodo build (CLI) from the project root:

1. The project is packaged once (shared build context for all services)
2. All service images are built in parallel via the remote Build API
3. Images are registered in dependency order (from dependsOn in the devfile)
4. The app is created or updated as a single entity

Local BuildKit — when you pass build_mode: local to build_app or run komodo build --local:

1. buildctl runs against your local BuildKit daemon (BUILDKIT_HOST, default docker-container://buildkitd) and writes a docker-format image tarball per service (multi-service apps build images in parallel on the client)
2. Each tarball is uploaded to object storage via a prebuilt presigned URL from the Build API
3. The platform worker skips in-cluster BuildKit for that job but still runs Trivy, pushes to ECR, and signs the image — same security bar as remote builds
4. Only Komodo OAuth is required; there is no AWS_ROLE_ARN or direct push from your laptop to ECR

For MCP, set BUILDKIT_HOST on the MCP server environment — see BUILDKIT_HOST below.

To rebuild a single service without touching others, pass service_name:

build_app(project_path="/path/to/my-app", service_name="backend")

Or from the CLI, run komodo build from within a service subdirectory.

Service URLs and cross-service communication

Each service gets its own public HTTPS URL:

Service type	URL pattern
Primary	{app-name}.{account}.apps.{env}.onkomodo.com
Non-primary	{app-name}-{service}.{account}.apps.{env}.onkomodo.com

Use devfile template variables to wire services together at runtime:

• {{services.<name>.url}} — full public HTTPS base (use this for all HTTP clients)
• {{services.<name>.host}} — hostname only
• {{services.<name>.port}} — port number

Networking rules

All traffic between services — browser-to-API and container-to-container — must use public HTTPS URLs. Kubernetes service DNS, container hostnames, localhost, and nginx reverse proxying between services are not supported and will fail.

Browser → API: Use fetch(..., { credentials: "include" }) for cookie-based auth. The platform’s mesh auth sets a tenant-scoped cookie that covers all sibling service hostnames. The backend must enable CORS with an explicit CORS_ALLOWED_ORIGINS (not * when credentials are used).

Container → container: Use the same public URL (e.g., worker calls API at {{services.api.url}}). If the callee enforces auth, include the appropriate headers (for example an Authorization token).

Devfile environment variables

Service URLs must be passed as container.env, not dockerfile.args (build args are not resolved for service URL templates).

- name: backend
  container:
    env:
      - name: CORS_ALLOWED_ORIGINS
        value: "{{services.frontend.url}}"
- name: frontend
  container:
    env:
      - name: BACKEND_PUBLIC_URL
        value: "{{services.backend.url}}"

Service naming constraints

Container component names become part of DNS hostnames and Helm release names. Keep them under 12 characters, lowercase alphanumeric with hyphens. Examples: api, worker, frontend, backend. Names like authentication-service may cause Helm release-name overflow.

Devfile Configuration

Every app requires a devfile.yaml that defines its metadata and container configuration.

Single-service devfile

schemaVersion: 2.2.0
metadata:
  name: my-api
  displayName: My API Service
  description: A FastAPI service for inventory management
  komodo:
    fabrics: []
    permissions: []
components:
  - name: api
    container:
      image: my-api:latest
      endpoints:
        - name: http
          targetPort: 8000

Multi-service devfile

schemaVersion: 2.2.0
metadata:
  name: my-app
  displayName: My Full-Stack App
  description: React frontend with FastAPI backend
  komodo:
    fabrics: []
    permissions: []
    primaryService: frontend
components:
  - name: frontend-build
    image:
      imageName: my-app-frontend:latest
      dockerfile:
        uri: Dockerfile
        buildContext: .
  - name: backend-build
    image:
      imageName: my-app-backend:latest
      dockerfile:
        uri: backend/Dockerfile
        buildContext: .
  - name: frontend
    container:
      image: my-app-frontend:latest
      memoryLimit: 512Mi
      cpuLimit: 500m
      endpoints:
        - name: http
          targetPort: 80
      env:
        - name: BACKEND_PUBLIC_URL
          value: "{{services.backend.url}}"
      dependsOn:
        - backend
  - name: backend
    container:
      image: my-app-backend:latest
      memoryLimit: 512Mi
      cpuLimit: 500m
      endpoints:
        - name: http
          targetPort: 8000
      env:
        - name: CORS_ALLOWED_ORIGINS
          value: "{{services.frontend.url}}"

Key fields:

• metadata.name — becomes the app’s subdomain (must be lowercase, alphanumeric + hyphens, 1-63 chars)
• metadata.komodo.primaryService — the user-facing entrypoint service (multi-service only)
• components[].container.endpoints[].targetPort — must match the port your app listens on
• components[].container.dependsOn — deploy ordering; dependencies are registered first
• components[].image — one per service; references the service’s Dockerfile

The .app File

When an app is created, a .app file is written to the project directory containing the app’s UUID. Subsequent builds update the existing app rather than creating a new one. Commit this file to version control so team members deploy to the same app.

If you delete an app but the .app file remains, the next build will fail with a 404. Delete the .app file and rebuild to create a new app.

Building & Deploying via CLI

For users who prefer direct CLI control over MCP. See the App Builder CLI Reference for the complete command reference.

Build and Deploy

uv run komodo build

Discovers services, uploads context to the remote Build API, streams build logs, then creates/updates the app. Only Komodo OAuth is needed.

Local BuildKit + prebuilt upload

uv run komodo build --local

Uses BuildKit on your machine to build a docker image tar, uploads it via the Build API prebuilt path, then the platform runs Trivy, ECR push, and signing. Requires buildctl and a reachable BuildKit. No AWS_ROLE_ARN or client-side ECR credentials. Multi-service projects at the repo root follow the same orchestration as remote builds (parallel image tars, then dependsOn order for registration).

BUILDKIT_HOST

Both komodo build --local and MCP build_app with build_mode: local use buildctl against the address in BUILDKIT_HOST.

When unset	Value
Local machine (CLI or MCP)	docker-container://buildkitd — expects a Docker container named buildkitd

If that default fails, start BuildKit on TCP and point every build process at it:

docker run -d --name buildkitd --privileged -p 1234:1234 moby/buildkit:latest --addr tcp://0.0.0.0:1234
export BUILDKIT_HOST="tcp://127.0.0.1:1234"
komodo build check

MCP (Cursor / IDE): The Komodo MCP server runs outside your terminal. Set BUILDKIT_HOST in the MCP server’s environment (e.g. Cursor Settings → MCP → komodo → Environment), or ensure docker-container://buildkitd works from that process. A shell export alone does not fix build_app BuildKit errors.

See Troubleshooting — BuildKit.

Check Build Status

uv run komodo build status <BUILD_ID>

Use --poll to automatically poll every 10 seconds until the build completes.

App Management

uv run komodo app list

uv run komodo app get-status <APP_ID>

uv run komodo app display-latest-logs <APP_ID>

uv run komodo app delete <APP_ID>

Tip

The enable_app and disable_app actions are available through the MCP tools. From the CLI, use komodo app update to modify an app’s configuration.

Managing Your Apps in Launchpad

Launchpad is the web UI where you can discover, open, and manage your deployed applications.

Navigating to Your Apps

In the Launchpad sidebar, use the Apps entry (grid icon) to open the apps list. The main navigation includes Home, Apps, and Explore; the Apps page shows “My Apps” and a searchable grid of your applications.

Apps List

The apps list displays every deployed app as a card with:

• Name and description — from your app’s devfile metadata
• Status — Running, In Progress, or other deployment state
• Owner — the user who created or owns the app

A Create New App card at the top links to the flow for building a new app. Use the search bar to filter apps by name or description.

App Details

Select an app to open its App Details page. Here you can:

• Open the app — use “Open App” to open the live URL in a new tab
• View status and URL — see current status (e.g. Running) and the full app URL
• Inspect devfile contents — version, language, Komodo configuration (fabrics, RBAC permissions), and a summary of components
• See components — for each component, view image URI (ECR), resource limits (memory, CPU), and endpoints (e.g. HTTP port)

Mesh Networking

Mesh networking connects AWS resources in your subaccount to your deployed apps running on the shared Komodo platform. This lets your apps access databases, caches, and other services you manage in your subaccount.

What You Own

When your account has an AWS subaccount, you own the resources you provision there — for example:

• RDS databases (PostgreSQL, MySQL, etc.)
• ElastiCache clusters (Redis, Memcached)
• Amazon Bedrock endpoints

App Builder does not create these resources. It provides the connectivity: the mesh ensures your deployed apps can reach your subaccount resources across account boundaries.

How Mesh Works

Under the hood, mesh uses AWS VPC Lattice and AWS RAM (Resource Access Manager) to create cross-account connectivity:

1. A VPC Lattice resource gateway is created in your subaccount’s VPC
2. A resource configuration links the gateway to your resource (e.g. RDS endpoint)
3. The configuration is shared via AWS RAM to the Komodo Data Apps account
4. A VPC endpoint in the Data Apps VPC makes your resource reachable
5. Private DNS records provide a stable hostname for your app to connect to

Using Mesh via MCP

Ask your AI assistant:

“Mesh my RDS database at arn:aws:rds:us-west-2:021891586088:db:my-database to my app”

The assistant will create the mesh request and poll for completion.

Using Mesh via CLI

uv run komodo infra mesh <RESOURCE_ARN>

Check mesh status:

uv run komodo infra mesh-status <MESH_REQUEST_ID>

Use --poll to automatically poll every 10 seconds until completion. Status values: IN_PROGRESS, COMPLETED, FAILED.

See the App Builder CLI Reference — komodo infra for details.

Sharing & Permissions

Every app is backed by a Platform RBAC custom resource, and the app UUID doubles as the custom resource ID. You can grant other users access to your apps with one of three roles:

Role	Can view	Can edit	Can manage access
viewer	Yes	—	—
editor	Yes	Yes	—
owner	Yes	Yes	Yes

The roles you can grant depend on your own role. An owner can grant all three; an editor can grant editor and viewer.

Sharing via MCP

Ask your AI assistant:

“Who has access to my app?”

The assistant calls list_app_permissions and shows a table of users and roles.

“Grant editor access to alice@komodohealth.com on my app”

The assistant resolves the app, confirms the role, and calls grant_app_role.

“Revoke viewer from bob@komodohealth.com”

The assistant calls revoke_app_role. If details are missing, it prompts you interactively.

See the App Builder MCP Tools Reference — Sharing for the full parameter reference.

Sharing via CLI

The komodo app sharing command group provides list, roles, grant, and revoke subcommands. All support an interactive flow when flags are omitted.

List users with access:

uv run komodo app sharing list <APP_ID>

Show roles you can grant:

uv run komodo app sharing roles <APP_ID>

Grant a role (interactive when flags are omitted):

uv run komodo app sharing grant --app-id <APP_ID> --role editor --user alice@komodohealth.com

Revoke a role:

uv run komodo app sharing revoke --app-id <APP_ID> --role viewer --user <USER_ID>

See the App Builder CLI Reference — komodo app sharing for the full flag reference.

Secrets

Komodo Secrets lets you store sensitive values (API keys, database passwords, tokens) and inject them into your deployed applications as environment variables. Secret values are stored server-side in the Komodo Secrets Service (backed by a hardened secrets vault) and delivered to your app at runtime — the values never appear in your source code, container image, or devfile (only secret path references do).

Secret scopes

Scope	Description	Use case
user	Private to you	Personal API keys, tokens
app	Tied to a specific application (requires app_id)	Database credentials for one app
shared	Visible to all members of your account	Team-wide service keys

How secrets reach your app

1. Store a secret using MCP, CLI, or the SDK
2. Reference the secret in your devfile under components[].container.secrets
3. Deploy — the platform operator fetches the secret value and injects it as an environment variable into your running container

Devfile syntax

Add a secrets list to any container component. Each entry maps a secret path to an environment variable name:

components:
  - name: my-api
    container:
      image: my-api:latest
      endpoints:
        - name: http
          targetPort: 8000
      secrets:
        - name: DB_PASSWORD
          secretPath: db/password
        - name: STRIPE_KEY
          secretPath: stripe-api-key

Field	Description
name	The environment variable name injected into the container
secretPath	Path of the secret in the Komodo Secrets Service (as used with create_secret)

At runtime your application reads the value with os.environ["DB_PASSWORD"] (or your language’s equivalent).

Managing secrets via MCP

You: “Create an app secret called db-password with the value s3cret123 for my app”

The assistant calls create_secret with secret_type: "app", secret_path: "db-password", and data: '{"value": "s3cret123"}'.

You: “List all my secrets”

The assistant calls list_secrets with secret_type: "user" to show your personal secrets.

You: “Share my secret api-key with the team”

The assistant calls share_secret to copy your user secret into the shared namespace where all account members can access it.

See the App Builder MCP Tools Reference — Secrets for the full parameter reference.

Managing secrets via CLI

uv run komodo secrets create --type user --path my-api-key --data '{"key": "abc123"}'

uv run komodo secrets list --type user

uv run komodo secrets get --type user --path my-api-key

uv run komodo secrets update --type app --path db-password --app-id APP_ID --data '{"password": "new-pass"}'

uv run komodo secrets delete --type user --path my-api-key

See the App Builder CLI Reference — komodo secrets for the full flag reference.

Managing secrets via SDK

from komodo_internal_tools.sdk.secrets_api import SecretsApi, SecretType

api = SecretsApi(environment="production")

# Create a user secret
api.create_secret(
    secret_type=SecretType.USER,
    secret_path="my-api-key",
    data={"key": "abc123"},
)

# Read it back
secret = api.read_secret(SecretType.USER, "my-api-key")
print(secret.data)  # {"key": "abc123"}

See the Python SDK — SecretsApi for the full class reference.

Secret paths

Secret paths must not start with / or contain .. (path traversal is rejected). Use simple names like my-api-key or hierarchical paths like db/password.

Troubleshooting

Authentication Errors

Run komodo login and komodo account set to complete the browser-based OAuth flow and select your account.

Port Mismatch

If your app deploys but returns errors, verify targetPort in devfile.yaml matches the port your application actually listens on. Use validate_devfile (MCP) or review the devfile manually.

App Not Found (404)

If build_app fails with a 404, the app was deleted but the .app file remains. Delete the .app file and rebuild.

Build Failures

If a remote build fails, check the error message in the build_app response. Common causes:

• Invalid Dockerfile — ensure your Dockerfile builds successfully locally with docker build . before deploying
• Scan failures — the platform runs Trivy vulnerability scans; critical vulnerabilities may block the build. Use get_build_scan_report (MCP) or komodo build status <BUILD_ID> (CLI) to see details
• Timeout — large builds may exceed the default timeout; try reducing image size or contact Komodo support

Multi-Container Issues

• CORS errors or 302 redirects — the backend’s CORS_ALLOWED_ORIGINS must exactly match the frontend’s origin (no trailing slash). Use {{services.frontend.url}} via container.env, not dockerfile.args
• Preflight surprises — avoid sending Content-Type: application/json on GET requests unless you need it, since it can trigger an OPTIONS preflight that fails when CORS is misconfigured
• Backend sees no traffic — if BACKEND_PUBLIC_URL is empty, frontend calls to relative /api/* hit the primary app host and may 302 to login while your backend receives nothing. Ensure {{services.backend.url}} is injected via container.env
• Service unreachable — verify you’re calling the public {{services.<name>.url}}, not an internal hostname or localhost
• ImagePullBackOff — run a full build_app from the project root (without service_name) to re-sync all image URIs in the devfile
• One service FAILED — use get_app_logs with service_name to check logs for that specific service