# Introduction Kubernetes makes deploying apps easy, well, sort of. But that 100 microservices app makes the development flow hard. You can't fit the whole app on your workstation, without pain. The most sensible way is probably running the development flow in Kubernetes itself. Have a pipeline to build and deploy your code changes. But the feedback is slow. Tools like Skaffold can sync your code changes to pods directly, and tools like Telepresence can intercept traffic to your local machine which enables you to do local debugging. That makes things feel like good old local development again. But, **How do you manage all the Kubernetes resources?** The deployments, ConfigMaps, services, secrets - who maintains them? Do developers share the same resources, or does everyone get separate environments? If they're separate, how do you keep them in sync? How do you ensure changes to the app propagate to all dev environments? And what about domains, DNS, and HTTPS for developers to actually access their work? ## Why Lapdev Lapdev Kubernetes Environment solves all these pains so that you don't have to. ### **Seamless Environment Management:** Lapdev reads your **production Kubernetes manifests directly from your cluster**. Just tell Lapdev which workloads your app needs, and it automatically replicates: * The workloads (Deployments, StatefulSets, DaemonSets, etc.) * Associated ConfigMaps and Secrets * Services and networking configuration **Your production manifests become the single source of truth** - no duplicate YAML files to maintain, no config drift between prod and dev. ### Stay in Sync with Production * Lapdev continuously monitors your production manifests for changes * App Catalogs automatically update when their source workloads change * Environments **notify you when updates are available** - sync with one click when you're ready * No surprise interruptions during development - you control when to pull in changes ### Flexible Environment Models **Personal Environments:** Each developer gets a complete, independent copy of all workloads. Perfect for testing breaking changes or complex multi-service interactions with full isolation. **Branch Environments (Cost-Effective):** A shared baseline environment runs all services once. Developers create lightweight "branch environments" for only the services they're actively modifying. Lapdev automatically routes your traffic to your version while everything else uses the shared baseline. ### Local Development with Devbox Lapdev includes **Devbox**, a CLI tool that integrates seamlessly with your environments: * Intercept cluster traffic to your local machine for real-time debugging * Use your local IDE, set breakpoints, and see live logs * Transparently access in-cluster services (databases, caches, internal APIs) as if you're running inside the pod * No complex VPN or tunneling setup required ### Preview URLs with Zero Configuration Create Preview URLs for any service in your environment: * Unique HTTPS URLs automatically generated for each service * Automatic TLS certificates and DNS configuration * Traffic proxied directly to your in-cluster services * Optional access control - configure URLs to be accessible only to Lapdev logged-in users * No firewall changes, no manual Ingress configuration, no cert-manager setup Share your work with teammates, PMs, or QA instantly - they can test your changes without any cluster access or VPN. ### Easy Installation in Your Cluster Lapdev requires just one deployment `lapdev-kube-manager` installed in your cluster. That's it. ## Getting Started 1. [Connect Your Kubernetes Cluster](/how-to-guides/connect-your-kubernetes-cluster) 2. [Create an App Catalog](/how-to-guides/create-an-app-catalog) 3. [Create Your First Environment](/how-to-guides/create-lapdev-environment) 4. [Start Local Development with Devbox](/how-to-guides/local-development-with-devbox) Learn more about [Core Concepts](/core-concepts/architecture). # Connect Your Kubernetes Cluster This guide walks you through connecting your Kubernetes cluster to **Lapdev**, so Lapdev can manage development environments inside your cluster. > Read [**Cluster**](/core-concepts/cluster) to understand cluster roles, permissions, and how kube-manager works. ### Create a Cluster in the Lapdev Dashboard 1. Go to the Lapdev dashboard: 2. Navigate to **Clusters** → click **Create New Cluster**. 3. Enter a **name** to identify your cluster (e.g. `staging-cluster` or `dev-cluster`). 4. After creating it, you’ll see an **authentication token** and **installation instructions** for your cluster. Keep this token handy — it’s used to securely register your cluster with Lapdev.
### Install the Lapdev Kube Manager Run the install command shown in the dashboard, or apply the manifest manually: ```bash kubectl apply -f "https://get.lap.dev/install/lapdev-kube-manager.yaml?token=" ``` Replace `` with the token generated when you created the cluster. The manifest creates the `lapdev` namespace (if needed), configures the required RBAC, and deploys the `lapdev-kube-manager` controller that securely connects your cluster to Lapdev. ### Configure Cluster Permissions After the cluster is connected, configure which environment types can be deployed to this cluster: 1. Go to the cluster details page in the dashboard 2. Find the **Permissions** section 3. Toggle permissions based on your needs: * **Personal Environments** - Allow developers to create isolated environments * **Shared Environments** - Allow team-wide baseline and branch environments You can change these settings at any time. > Learn more about cluster permissions and use cases in [**Cluster**](/core-concepts/cluster). ### Verify Connection Once the installation is complete: * Go back to the **Clusters** page in the Lapdev dashboard. * Your cluster should appear in the list with a status of **Active**. If the status doesn’t update after a minute, double-check that: * The `lapdev-kube-manager` pod is running: ```bash kubectl get pods -n lapdev ``` * Your network allows outbound HTTPS connections to `api.lap.dev`. ### Next Steps Your cluster is now connected to Lapdev! 🎉 You can start: * Creating an [App Catalog](/how-to-guides/create-an-app-catalog) from your cluster's workloads * Creating [Environments](/how-to-guides/create-lapdev-environment) from your App Catalog * Learn more about [Cluster concepts](/core-concepts/cluster) and architecture # Create an App Catalog An **App Catalog** defines which workloads make up your application — it's the blueprint Lapdev uses to create development environments. This guide walks you through creating an App Catalog from your connected cluster. > To understand why App Catalogs exist and how they fit into Lapdev, read [**App Catalog**](/core-concepts/app-catalog) first. ### Prerequisites Before creating an App Catalog, make sure: * You've connected at least one **Kubernetes cluster** to Lapdev. * The cluster you'll read workloads from shows as **Active** in the Lapdev dashboard. * The cluster contains the workloads you want to include (e.g. your production or staging workloads). > Don't have a cluster connected yet? See [**Connect Your Kubernetes Cluster**](/how-to-guides/connect-your-kubernetes-cluster). > 💡 The same cluster can be used later for both reading workloads **and** deploying environments. ### Open the Cluster in the Dashboard 1. Go to . 2. Navigate to the **Clusters** tab. 3. Click the cluster you want to use as the **source**. ### Select Workloads Once inside the cluster details page: 1. Lapdev lists all **workloads** (Deployments, StatefulSets, DaemonSets, etc.) discovered in the cluster. 2. You can: * Filter workloads by **Namespace** or **Workload Type**. * Optionally check **Show System Workloads** to include system components. 3. Select the workloads that make up your app.
### Create the App Catalog 1. After selecting workloads, click **Create App Catalog**. 2. In the dialog: * Enter a **Name** for the catalog (e.g. `checkout-service`, `internal-tools`). * Optionally add a **Description**. * Review the list of selected workloads. 3. Click **Create**.
Lapdev will create the catalog and register it in the **App Catalogs** section of your dashboard. > 💡 Don’t worry if you missed something — you can edit the catalog later to add or remove workloads. ### Verify Your App Catalog 1. Go to the **App Catalogs** tab in the dashboard. 2. You’ll see your newly created catalog listed with: * The **name** and **description** * The **number of workloads** included * The **source cluster** Click a catalog name to view its details. *Example screenshot:* ### Next Steps Once your App Catalog is ready, you can: * Create a [Lapdev Environment](/how-to-guides/create-lapdev-environment) from it * Learn about [Environment types](/core-concepts/environment) * Understand [Cluster roles](/core-concepts/cluster) for multi-cluster setups # Create Lapdev Environment A **Lapdev Environment** is a running instance of your app inside a Kubernetes cluster. It's created from an existing **App Catalog**, which defines which workloads make up your application. This guide shows how to create **personal** and **shared** environments from an App Catalog, and how to create **branch** environments from a shared environment. > Read [**Environment**](/core-concepts/environment) to understand environment types and how they work. ### Prerequisites Before creating an environment: * You must have at least one **connected Kubernetes cluster** (Active in the Lapdev dashboard). * You must have an existing **App Catalog** that defines your app's workloads. > If you haven't created one yet, see [**Create an App Catalog**](/how-to-guides/create-an-app-catalog). ### Start from an App Catalog (Personal or Shared) 1. Go to the **App Catalogs** tab in the Lapdev dashboard. 2. Select the catalog you want to use as the base for your environment. 3. Click **Create Environment**.
### Select Environment Type (Personal or Shared) Lapdev supports three environment types depending on your workflow and cost needs. When you create an environment from an App Catalog you can choose between: #### **Personal Environment** * A fully isolated copy of your app, deployed into a per-developer namespace. * Ideal for local testing, debugging, or experimentation without affecting others. #### **Shared Environment** * A single shared version of your app that multiple developers can access. * Useful for integration testing or a team staging setup. Branch environments are created from an existing shared environment. See the next section for that workflow. ### Create a Branch Environment Branch environments reuse an existing shared environment as their baseline. 1. Go to the **Environments** tab in the Lapdev dashboard. 2. Open the shared environment you want to branch from. 3. Click **Create Branch Environment**. 4. Select the services you plan to modify and provide a name/description for the branch. 5. Click **Create**. Only the services you modify are duplicated alongside the shared workloads in the same namespace; everything else continues to run on the shared versions. > 🧠 Use **branch environments** for feature work — they're lightweight, fast to spin up, and cost-efficient. ### Verify and Access Your Environment After creation: * The environment will appear in the **Environments** list. * Lapdev automatically provisions: * All workloads from the App Catalog * Associated ConfigMaps, Secrets, and Services * Kubernetes namespace and networking You can monitor status, logs, and sync state directly from the dashboard. ### Next Steps Your environment is ready! You can now: * Create [Preview URLs](/how-to-guides/use-preview-urls) for HTTPS access to your services * Use [Devbox](/how-to-guides/local-development-with-devbox) to connect locally for live debugging * Learn more about [Environments](/core-concepts/environment) # Local Development With Devbox This guide shows how to set up and use **Devbox** for local development with your Lapdev environments. > Read [**Devbox**](/core-concepts/devbox) to understand what it does and when to use it. ### Prerequisites Before using Devbox, you need: * **Lapdev CLI installed** - Devbox is built into the `lapdev` command * **An active Lapdev environment** - Personal, shared, or branch environment ### Install the Lapdev CLI Run one of the following commands based on your operating system. #### Linux or macOS ```bash curl -fsSL https://get.lap.dev/lapdev-cli.sh | bash ``` This script detects your architecture, downloads the latest release, and places the `lapdev` binary in `/usr/local/bin` (or `~/.local/bin` if needed). Re-run it at any time to upgrade or pass `--version ` to pin a specific build. #### Windows PowerShell ```powershell irm https://get.lap.dev/lapdev-cli.ps1 | iex ``` Run the command in an elevated PowerShell window if your execution policy requires it. The installer copies `lapdev.exe` into `%LOCALAPPDATA%\Lapdev\bin` and appends that directory to your user `PATH`. Restart your shell (or VS Code terminal) after installation so the new path is picked up. After installing, verify everything is ready with: ```bash lapdev --version ``` ### Connect to Lapdev First, connect your Devbox CLI to Lapdev: ```bash lapdev devbox connect ``` This establishes a secure connection between your local machine and Lapdev. ### Set Active Environment After connecting, set which environment you want to work with in the Lapdev dashboard: 1. Go to the **Environments** tab 2. Select the environment you want to use 3. Click **Set as Active Environment** Once set, all traffic interception and service access will route through this active environment. ### Intercept a Service Once connected, you can intercept traffic for a specific workload through the Lapdev dashboard: 1. Open your environment in the Lapdev dashboard 2. Stay on (or switch to) the **Workloads** tab 3. Locate the workload that owns the service you want to intercept (e.g., `checkout-service`) 4. Click **Start Intercept** inside that workload’s row Lapdev automatically mirrors each container port, reusing any overrides from your most recent intercept. If you need custom local ports after starting the intercept, use the **Edit Ports** button on the intercept card and update the mappings there.
After enabling interception: * All cluster traffic for that service routes to your local machine * You can make edits, hot-reload, or debug directly in your IDE * Other services in the cluster remain unaffected ### Access In-Cluster Services While connected via Devbox, you can access any service in your environment using their cluster DNS names (e.g., `postgres-service:5432`, `redis-service:6379`) directly from your local code. Devbox handles the tunneling automatically — no port forwarding or VPN needed. ### Next Steps * Learn more about [Devbox architecture](/core-concepts/devbox) * Understand [traffic routing](/core-concepts/architecture/traffic-routing-architecture) * Create [preview URLs](/how-to-guides/use-preview-urls) to share your work # Use Preview URLs Lapdev lets you create **Preview URLs** for your environments so you can securely access and share running services — without setting up DNS, ingress, or TLS certificates manually. Each Preview URL points to a specific **service** inside your environment (for example, your `frontend`, `api-gateway`, or `admin` service).\ You can create multiple Preview URLs per environment, each targeting a different service. > Read [**Preview URL**](/core-concepts/preview-url) to understand what they are and why they're useful. ### Prerequisites Before you begin: * You must have at least one **active environment** in Lapdev (personal, shared, or branch). * The environment must show a status of **Active** in the Lapdev dashboard. * Your app must expose at least one **Service** in Kubernetes. ### Create a Preview URL 1. Open the Lapdev dashboard: 2. Go to the **Environments** tab. 3. Select the environment you want to create a preview for. 4. In the environment details page, scroll to the **Preview URLs** section. 5. Click **Create Preview URL**. *Example screenshot:*\\ 6. In the **Create Preview URL** dialog: * Choose the **Service** you want this URL to point to (for example, `frontend`, `api-gateway`, or `admin`). * Optionally, enter a **Description** (e.g., “Frontend QA demo”). * Select the **Access Level** (`Organization` by default, or `Public`). 7. Click **Create**.
Lapdev will: * Automatically generate a unique HTTPS domain for the selected service * Handle routing, DNS, and TLS certificates for that URL * Route traffic directly to the selected service inside your environment ### View and Open Preview URLs Once created: * All Preview URLs for the environment appear in the **Preview URLs** section. * Each entry lists: * The **Service name** it targets * The **URL** itself * The **Access level** (`Organization` or `Public`) Click the URL to open it in your browser. ### Share the Preview URL You can safely share a Preview URL with: * Teammates or QA engineers for quick testing * PMs or designers for feature reviews * Automated test systems for integration runs Just copy and share the link — no VPN, firewall, or cluster access needed. > 💡 Tip: You can create multiple Preview URLs in the same environment if your app exposes multiple services (e.g., `frontend`, `admin`, `gateway`). ### Manage Access Control Each Preview URL has its own access policy. To update it: 1. In the **Preview URLs** section, click the settings icon next to a URL. 2. Choose who can access it: * **Organization (recommended, default):** Only authenticated Lapdev users can view. * **Public:** Anyone with the link can view. * *(Coming soon)* **Custom rules** for organization-level access. 3. Click **Save**. > 🔒 Use organization access for internal branches or unreleased features. ### Delete a Preview URL To remove a Preview URL: 1. Go to the **Preview URLs** section of your environment. 2. Click the **Delete** icon next to the URL. 3. Confirm deletion. Deleting a Preview URL does **not** affect the environment or its workloads — it only removes that specific public endpoint. ### Troubleshooting | Issue | Possible Cause | Solution | | ------------------------ | ----------------------------------------- | -------------------------------------------------------- | | Service not listed | The service has no exposed port | Check that the Kubernetes Service defines a valid `port` | | Preview URL doesn’t open | Service not ready or endpoint unreachable | Verify pods and services are running | | HTTPS warning | Certificate still propagating | Wait 30–60 seconds; Lapdev handles TLS automatically | ### Next Steps * Learn more about [Preview URLs](/core-concepts/preview-url) and how they work internally * Use [Devbox](/how-to-guides/local-development-with-devbox) for real-time debugging connected to your environment * Explore [App Catalogs](/how-to-guides/create-an-app-catalog) to define which workloads appear in your environments # Architecture This document explains how Lapdev works and how its components interact to provide seamless Kubernetes development environments. ### Overview Lapdev consists of three main components: 1. **Lapdev API Server** (SaaS) - Manages users, authentication, and orchestrates environment creation 2. **Lapdev-Kube-Manager** (In your cluster) - Reads production manifests, manages dev environments, and pushes routing/intercept state to sidecars 3. [**Devbox**](/core-concepts/devbox) **CLI** (Developer's machine) - Enables local debugging with cluster connectivity * Plus an auto-injected **Sidecar Proxy** per pod that enforces routing and intercepts at runtime ### Architecture Diagram ### Component Details #### Lapdev API Server (SaaS) The Lapdev cloud service handles: * **User authentication and authorization** - GitHub/GitLab OAuth, team management * **Environment orchestration** - Receives environment creation requests from users * **Secure tunnel management** - Establishes websocket tunnels between your cluster and Lapdev * [**Preview URL**](/core-concepts/preview-url) **routing** - Routes traffic from automatically generated HTTPS URLs to your cluster **Security:** * Communicates with your cluster via secure websocket tunnels (TLS encrypted) * No direct access to your cluster's API server * Receives workload manifests (Deployments, StatefulSets, ConfigMaps, Secrets) from lapdev-kube-manager to build App Catalogs * You control which workloads Lapdev can access through App Catalog selection * No access to runtime application data (databases, logs, persistent volumes) #### Lapdev-Kube-Manager (In Your Cluster) Deployed as a single Kubernetes deployment in your cluster, `lapdev-kube-manager`: * **Reads production manifests** - Discovers Deployments, StatefulSets, ConfigMaps, Secrets, and Services from your production namespace to build [App Catalogs](/core-concepts/app-catalog) * **Creates dev** [**environments**](/core-concepts/environment) - Replicates selected workloads into isolated or shared namespaces * **Manages sync** - Monitors production manifests for changes and updates dev environments * **Publishes traffic routing** - For [branch environments](/core-concepts/architecture/branch-environment-architecture), computes routing tables and distributes them to sidecars (sidecars enforce routing; see [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture)) * **Establishes secure tunnel** - Maintains websocket connection to Lapdev API Server for orchestration **Permissions:** * Read access to production namespace (to read manifests) * Full access to Lapdev-managed namespaces (to create/update environments) * No access to other cluster resources #### Devbox CLI (Developer Machine) The `lapdev devbox` command-line tool enables local development: * **Traffic interception** - Routes requests for specific services to `localhost` (controlled via Lapdev dashboard) * **Cluster connectivity** - Provides transparent access to in-cluster services (databases, APIs, caches) * **Secure tunnel** - Establishes encrypted connection to Lapdev API Server, which proxies to your cluster **How it works:** 1. Developer runs `lapdev devbox connect` and sets their active environment in the dashboard 2. Devbox establishes secure tunnel: `Developer → Lapdev API` * Lapdev-Kube-Manager stays in the control plane, pushing intercept metadata and (optional) direct-connect hints to sidecars, but is not on the data path. 3. Sidecar receives intercept config, opens its own tunnel to Lapdev API for that workload, and forwards intercepted pod traffic over the tunnel to the Devbox CLI 4. Developer's code processes requests on localhost; responses flow back through the same tunnel to the pod 5. Non-intercepted traffic continues to the in-cluster service transparently Learn more: [Devbox Concept](/core-concepts/devbox) | [Local Development with Devbox](/how-to-guides/local-development-with-devbox) ### Learn More **Specialized Architecture Documentation:** * [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture) - How Lapdev routes traffic between components * [Branch Environment Architecture](/core-concepts/architecture/branch-environment-architecture) - Cost-effective environment model details **Core Concepts:** * [Cluster](/core-concepts/cluster) - How clusters connect to Lapdev * [App Catalog](/core-concepts/app-catalog) - Blueprint for your application * [Environment](/core-concepts/environment) - Running instances of your app * [Preview URL](/core-concepts/preview-url) - HTTPS access to your services **Getting Started:** * [Connect Your Kubernetes Cluster](/how-to-guides/connect-your-kubernetes-cluster) * [Create an App Catalog](/how-to-guides/create-an-app-catalog) * [Create Lapdev Environment](/how-to-guides/create-lapdev-environment) # Traffic Routing Architecture This document explains how traffic flows through Lapdev for both preview URLs and local development with Devbox. ### Overview Lapdev handles two main traffic patterns: 1. [**Preview URL**](/core-concepts/preview-url) **Traffic** - External users accessing your development environment via browser 2. [**Devbox**](/core-concepts/devbox) **Traffic** - Developers debugging locally while accessing cluster services Both patterns use secure tunnels through the Lapdev cloud service, eliminating the need for VPNs or firewall changes. ### Architecture Diagram ### Components #### In Your Cluster **Lapdev-Kube-Manager** * Orchestrates environment creation and management * Maintains control-plane connection to Lapdev cloud service (route updates, heartbeats) * Pushes branch/service routing tables and Devbox intercept metadata to sidecars **Lapdev** [**Environment**](/core-concepts/environment) **(Namespace)** * Contains your replicated workloads * Each environment is isolated in its own namespace * Multiple environments can coexist in the same cluster **App Workload Pod** * Your application container(s) * Runs unmodified in Personal and Shared environments * [Branch environments](/core-concepts/architecture/branch-environment-architecture) may require header propagation (see Branch Environment Routing below) **Lapdev Sidecar Proxy** * Automatically injected into each pod in Lapdev environments * Routes traffic for branch environments based on tracestate headers * Handles Devbox intercepts directly (opens tunnels to Lapdev cloud and shuttles pod traffic over them) * Falls back to in-cluster service when no intercept is active #### External Components **Lapdev Cloud Service** * Routes preview URL traffic to your cluster * Manages secure websocket tunnels * Handles authentication for preview URLs **Devbox (Developer Machine)** * CLI tool running on developer's laptop * Establishes secure tunnel to cluster * Intercepts traffic for specific services * Provides transparent access to in-cluster services ### Traffic Flows #### Preview URL Traffic When a user accesses a Preview URL: 1. **Browser** → Request to automatically generated HTTPS URL 2. **Lapdev Cloud Service** → Authenticates request (if access control enabled) 3. **Lapdev Cloud Service** → Routes through WebSocket tunnel to kube-manager 4. **Kube-Manager** → Forwards to appropriate environment namespace 5. **Sidecar Proxy** → Routes to target service based on environment type: * **Personal/Shared:** Routes directly to service * **Branch:** Checks tracestate header and routes to branched or shared version 6. **Service** → Processes request and returns response The response flows back through the same path to the user's browser. #### Devbox Intercept Traffic When a developer intercepts a service with Devbox: 1. **Developer runs** `lapdev devbox connect` and enables intercept in dashboard 2. **Devbox CLI** → Establishes secure tunnel: `Local machine → Lapdev Cloud → Sidecar Proxy` * Kube-Manager stays on the control plane (publishing intercept metadata and optional direct-connect hints) but is **not** on the data path. 3. **Sidecar Proxy** for the intercepted pod: * Receives routing rules from Kube-Manager * Opens the tunnel to Lapdev Cloud using the intercept token * Forwards intercepted traffic to the developer’s local machine 4. **Local service** → Developer's code running on localhost processes the request 5. **Response** flows back through the same tunnel to the pod When no intercept is active, traffic routes normally to the in-cluster service. #### Branch Environment Routing Branch environments use intelligent routing based on tracestate headers: 1. **Request enters** through Preview URL with branch-specific tracestate header (auto-injected by Lapdev) 2. **Sidecar Proxy** reads tracestate header to identify the branch 3. **Routing decision:** * Service modified in branch? → Route to branch version * Service not modified? → Route to shared environment version 4. **Header propagation:** Application must forward headers to downstream services 5. **Next hop:** Process repeats at each service This enables multiple developers to test different modifications simultaneously without conflicts. > **Important:** Branch environment routing requires your application to propagate the tracestate header in HTTP calls. See [Branch Environment Architecture](/core-concepts/architecture/branch-environment-architecture) for implementation details. ### Component Roles Summary | Component | Purpose | When Used | | ----------------- | ------------------------------------------------------------------------ | ----------------------- | | **Sidecar Proxy** | Routes traffic based on environment type and headers | All environments | | **Kube-Manager** | Orchestrates environments and pushes routing/intercept state to sidecars | Always running | | **Lapdev Cloud** | Routes external traffic and manages authentication | Preview URLs and Devbox | ### Learn More **Specialized Routing Documentation:** * [Branch Environment Architecture](/core-concepts/architecture/branch-environment-architecture) - Tracestate header propagation, routing mechanism, and troubleshooting * [Architecture Overview](/core-concepts/architecture) - Overall system design and component interactions **Core Concepts:** * [Environment](/core-concepts/environment) - Personal, Shared, and Branch environment types * [Devbox](/core-concepts/devbox) - Local development with cluster connectivity * [Preview URL](/core-concepts/preview-url) - HTTPS access to your services **How-To Guides:** * [Use Preview URLs](/how-to-guides/use-preview-urls) - Create and manage preview URLs * [Local Development with Devbox](/how-to-guides/local-development-with-devbox) - Set up traffic interception and cluster access * [Create Lapdev Environment](/how-to-guides/create-lapdev-environment) - Set up different environment types # Branch Environment Architecture Branch environments are a cost-effective way to run development environments in Kubernetes. Instead of duplicating all services for each developer, branch environments build on a [shared environment](/core-concepts/environment) and only run the services you're actively modifying. ### Architecture Diagram ### Concept Without Branch Environments: ``` 10 developers × 100 services each = 1000 pods total Every developer runs a complete copy of all services ``` With Branch Environments: ``` Shared environment: 100 services (shared by everyone) + 10 developers × 2 modified services each = 20 branched services Total: 120 pods ``` **Example:** Alice modifies `api`, Bob modifies `worker` - they only run their modified services while sharing the rest. **Savings: 88% reduction in infrastructure costs** ### Prerequisites Branch environments require: * **HTTP/HTTPS communication only** - Non-HTTP components (databases, message queues, gRPC) remain shared across all branches * **Header propagation** - Your application must forward OpenTelemetry `tracestate` headers in service-to-service calls **Important:** While Lapdev automatically injects the tracestate header for incoming requests, your application code must forward headers in service-to-service HTTP calls for routing to work correctly. ### How It Works #### The Shared Environment One shared environment runs all your services: * Contains a complete copy of all workloads * Shared by all developers * Acts as the foundation for all branch environments #### Your Branch Environment When you create a branch, you specify which service(s) you're modifying: * Only those services run as branched workloads alongside the shared copies in the same namespace * Everything else routes to the shared environment #### Traffic Routing Overview When someone accesses your branch [preview URL](/core-concepts/preview-url), Lapdev routes traffic intelligently: * Requests to services you've modified → route to your branch version * Requests to all other services → route to the shared environment **Example:** If Alice's branch modifies only the `api` service, then requests for `api` go to her branch while `web`, `worker`, and all other services use the shared environment. #### Routing Mechanism **1. Header Injection** When a request enters through a [preview URL](/core-concepts/preview-url), Lapdev automatically injects an OpenTelemetry `tracestate` header that identifies which branch the request belongs to. **2. Header Propagation (Your Responsibility)** Your application must forward the `tracestate` header in all HTTP service-to-service calls. **How to implement:** Most HTTP clients automatically forward headers when you pass them explicitly. For example: ```javascript // Forward all incoming headers to downstream services const response = await axios.get('http://other-service:8080/api', { headers: request.headers // This includes the tracestate header }); ``` **Framework-specific approaches:** ✅ **Automatic with these frameworks:** * Spring Cloud Sleuth (auto-propagates OpenTelemetry headers) * OpenTelemetry-instrumented applications (SDK handles propagation) ⚠️ **Manual forwarding required:** * Express.js, Fastify, Koa (pass `request.headers` to HTTP client) * Go HTTP clients (copy headers from incoming request) * Any custom HTTP client implementation **3. Routing Decision** The Lapdev Sidecar Proxy (automatically injected by Lapdev into each pod in managed environments) sits in front of your workload traffic: 1. Intercepts incoming requests headed to your service 2. Reads the `tracestate` header to identify the branch 3. Checks if the target service has a branch override for this branch 4. If a Devbox intercept is active for this branch/service, routes to the developer’s local process; otherwise routes to the branched service if present 5. Falls back to the shared environment if no branch-specific target exists 6. The header continues downstream, so the next hop can repeat the decision > **Note:** The sidecar proxy is automatically added when Lapdev creates your environment. No manual configuration needed. For more details, see [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture). ### Key Benefits * **Cost-effective:** Only run what you're changing (up to 88% infrastructure reduction) * **Instant creation:** Branch environments are created instantly - branched workloads are only deployed when you modify them * **Realistic testing:** Test your changes against real production-like services, not mocks * **No conflicts:** Multiple developers can work on different services simultaneously ### Limitations #### 1. Header Propagation Required Your application must forward the `tracestate` header in service-to-service HTTP calls, otherwise routing will break mid-request chain. See the **Routing Mechanism** section above for implementation guidance. #### 2. HTTP/HTTPS Traffic Only Branch routing works exclusively for HTTP/HTTPS communication. Other protocols are always shared: * **Shared across all branches:** Databases, message queues, gRPC services, TCP connections * **Implication:** Be careful with database schema changes or queue message format changes #### 3. Stateful Services Considerations Services with persistent state (databases, caches) are shared across branches: * Database writes from one branch affect all other branches * Redis/Memcached entries are visible to all branches * File uploads or background jobs may interfere between branches **Best Practice:** Use branch-specific prefixes for cache keys and database records when testing data modifications. ### Troubleshooting #### Traffic not routing correctly to my branch **Symptoms:** * Changes aren't visible when accessing your branch preview URL * Some requests use your branch version, others use the shared version (inconsistent routing) **Possible causes:** 1. **Headers not propagated:** Your services aren't forwarding the `tracestate` header in HTTP calls 2. **Service not branched:** The service is not actually deployed in your branch environment 3. **Wrong preview URL:** You're accessing the shared environment URL instead of your branch URL **Debug steps:** * Verify your HTTP clients forward incoming headers to downstream services (see example above) * Check the Lapdev dashboard to confirm which services are branched in your environment * Check sidecar proxy logs to see routing decisions * Look for the `tracestate` header in your service logs - if it's missing after the first hop, headers aren't being propagated #### Database changes from my branch affect other developers This is **expected behavior**. Branch environments share databases and other stateful services. **Solutions:** * Use branch-specific database prefixes or namespaces * Test with read-only database operations * Use separate test databases per branch (requires manual configuration) ### Learn More **Related Architecture Documentation:** * [Traffic Routing Architecture](/core-concepts/architecture/traffic-routing-architecture) - Detailed explanation of how routing works across all environment types * [Architecture Overview](/core-concepts/architecture) - Overall system design and component interactions **Core Concepts:** * [Environment](/core-concepts/environment) - Understanding Personal, Shared, and Branch environments * [Preview URL](/core-concepts/preview-url) - HTTPS access to your services * [App Catalog](/core-concepts/app-catalog) - Blueprint for your application **How-To Guides:** * [Create Lapdev Environment](/how-to-guides/create-lapdev-environment) - How to create branch environments * [Use Preview URLs](/how-to-guides/use-preview-urls) - Access and share your branch environment # Cluster A **Cluster** in Lapdev refers to a Kubernetes cluster you've connected to Lapdev for managing development environments. Clusters can serve two roles: * **Source Cluster** - Provides production manifests for creating App Catalogs * **Target Cluster** - Hosts development environments The same cluster can serve both roles, which is the most common setup. ### Why Connect Clusters Connecting your Kubernetes cluster to Lapdev enables: * **App Catalog Creation** - Read production manifests to define your app * **Environment Deployment** - Run development environments in the cluster * **Production Parity** - Ensure dev environments match production exactly * **Centralized Management** - Manage multiple clusters from one dashboard ### How It Works #### Lapdev Kube Manager When you connect a cluster, Lapdev deploys a lightweight controller called **lapdev-kube-manager** inside your cluster. The kube-manager: * **Establishes secure connection** - Opens a WebSocket tunnel to Lapdev API Server (TLS encrypted) * **Reads production manifests** - Discovers Deployments, StatefulSets, ConfigMaps, Secrets, and Services * **Creates dev environments** - Replicates selected workloads into isolated or shared namespaces * **Handles traffic routing** - For branch environments, routes traffic to the correct version of services * **Manages synchronization** - Keeps environments updated with production changes **Security Model:** * Connection is **outbound-only** from your cluster (no inbound firewall rules needed) * Lapdev API Server **never** accesses your cluster's API server directly * Kube-manager has **read access** to production namespaces * Kube-manager has **full access** to Lapdev-managed namespaces only * Cannot access other cluster resources or namespaces #### Token-Based Authentication Each cluster is authenticated using a unique token: * Generated when you create the cluster in Lapdev dashboard * Used by kube-manager to establish the secure tunnel * Stored as a Kubernetes Secret in your cluster ### Cluster Roles #### Source Cluster A **source cluster** is where Lapdev reads production manifests to create App Catalogs. * Typically your **staging** or **production** cluster * Contains the workloads you want to replicate in dev environments * Kube-manager reads manifests but doesn't modify them * You can designate any cluster as a source **Common setups:** * Use production cluster as source (safest, always up-to-date) * Use staging cluster as source (if staging mirrors production) * Use dedicated "template" cluster (for controlled rollout) #### Target Cluster A **target cluster** is where Lapdev deploys development environments. * Can be the same as your source cluster or different * Hosts all Personal, Shared, and Branch environments * Kube-manager creates and manages namespaces here * Choose based on resource availability and cost **Common setups:** * Same cluster as source (simplest, most common) * Dedicated dev cluster (isolates dev from production) * Multiple dev clusters (for different teams or regions) ### Cluster Permissions Cluster permissions control **which types of environments** can be deployed to a cluster. #### Personal Environments Permission When enabled, developers can create **Personal Environments** in this cluster. * Each developer gets fully isolated namespaces * Higher resource usage (every dev runs complete app) * Best for: staging/dev clusters with sufficient resources **Enable when:** * Developers need full isolation for testing * Cluster has resources for multiple complete environments * You want individual developers to experiment freely #### Shared Environments Permission When enabled, admins can create **Shared Environments** and developers can create **Branch Environments** in this cluster. * Shared environments are team-wide baselines * Branch environments are lightweight personal modifications * Lower resource usage (shared baseline + modifications only) * Best for: cost-efficient development at scale **Enable when:** * Team uses branch environment workflow * You want cost-efficient development environments * Multiple developers work on the same application #### Permission Use Cases | Cluster Type | Personal | Shared | Use Case | | --------------- | -------- | ------ | -------------------------------- | | Dev Cluster | ✅ | ✅ | Full flexibility for developers | | Staging Cluster | ❌ | ✅ | Team-wide testing baseline only | | Testing Cluster | ✅ | ❌ | Isolated testing environments | | Production | ❌ | ❌ | Source only, no dev environments | > You can change these permissions at any time in the cluster settings. ### Relationship to Other Components Clusters are foundational to Lapdev's workflow: ``` Source Cluster ↓ (provides manifests) App Catalog ↓ (blueprint) Target Cluster ↓ (deploys to) Environments (Personal/Shared/Branch) ``` | Component | Role with Clusters | | ---------------- | ------------------------------------------------ | | **Cluster** | Provides infrastructure and manifests | | **App Catalog** | Created by reading manifests from source cluster | | **Environment** | Deployed into target cluster using App Catalog | | **Kube Manager** | Runs inside cluster, bridges to Lapdev API | ### Multiple Clusters You can connect multiple clusters to Lapdev for different purposes: **Common multi-cluster setups:** * **Source + Multiple Targets:** * Production cluster (source only) * Dev cluster A (target for team A) * Dev cluster B (target for team B) * **Regional Separation:** * US cluster (source + target) * EU cluster (target only, for EU developers) * **Environment Segregation:** * Staging cluster (source + shared environments) * Dev cluster (personal environments only) Each cluster appears in your Lapdev dashboard with its own status, permissions, and environments. ### Next Steps Ready to connect your cluster? See [**Connect Your Kubernetes Cluster**](/how-to-guides/connect-your-kubernetes-cluster) for step-by-step instructions. # App Catalog The **App Catalog** is the foundation of how Lapdev understands and manages your application in Kubernetes. It defines **which workloads belong to your app** — such as deployments, statefulsets, and their associated configuration — and acts as the **blueprint** Lapdev uses to create consistent and production-aligned development environments. ### Why App Catalogs In most Kubernetes setups, application configuration is scattered across multiple manifests or Helm charts.\ Developers often need to manually manage which workloads belong to which app, and this can easily lead to configuration drift between environments. The App Catalog solves this by: * **Defining your app once** — directly from your production workloads. * **Reusing that definition** to create any number of environments (personal, shared, or branch). * **Keeping everything in sync** with your production manifests — no duplicate YAML or manual updates. ### How It Works 1. Lapdev connects to your **source cluster** and reads all workloads running in it. 2. You select the workloads that make up your application (for example, `frontend`, `api`, and `database`). 3. Lapdev groups those workloads — along with their related **ConfigMaps**, **Secrets**, and **Services** — into an **App Catalog**. 4. The catalog is stored in Lapdev and can be reused to create environments on any connected cluster. > 💡 The **source cluster** is typically your staging or production cluster.\ > You can also use a dedicated cluster that mirrors production manifests.\ > Learn more about cluster roles in [**Cluster**](/core-concepts/cluster). ### Relationship Between App Catalogs and Environments | Concept | Purpose | Example | | --------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | **App Catalog** | Defines what your app is — a collection of workloads and their configuration. | `checkout-service` (includes `checkout-api`, `payment-api`, `frontend`) | | **Environment** | A running instance of that app in a specific cluster. | `mia-checkout-feature` (personal env) or `staging-checkout` (shared env) | You can think of an **App Catalog** as a *template* and an **Environment** as a *live deployment* of that template. ### Editing an App Catalog After creating an App Catalog, you can modify it anytime: * Add or remove workloads * Update its description * Sync it with your source cluster to reflect production changes Lapdev automatically tracks these updates and keeps associated environments consistent with the latest configuration. ### Typical Usage Pattern App Catalogs fit into your workflow like this: ``` Source Cluster (Production/Staging) ↓ App Catalog (Blueprint) ↓ Multiple Environments (Personal/Shared/Branch) ``` Once created, catalogs can be synced when production manifests change, keeping all environments up to date. > For step-by-step instructions, see [**Create an App Catalog**](/how-to-guides/create-an-app-catalog). ### Benefits of App Catalogs ✅ **No config drift:** Use production manifests as the single source of truth.\ ✅ **Reusable blueprint:** Create multiple environments from the same catalog.\ ✅ **Simplified management:** Centralize workloads and configuration in one place.\ ✅ **Scalable:** Works across clusters and environment models. ### When to Use Multiple App Catalogs You can create more than one App Catalog if: * Your organization manages multiple independent apps (e.g. `checkout`, `search`, `analytics`). * You want to separate internal tools from core services. * Different teams own different parts of your system. Each App Catalog can have its own lifecycle and permissions. # Environment The **Lapdev Kubernetes Environment** is the foundation of Lapdev’s platform. It’s where you **develop**, **test**, and **demo** your applications — all directly within Kubernetes. Lapdev’s unique strength is that it manages the **entire environment lifecycle** — from creation to synchronisation — in a seamless, automated way. You don’t need to manually manage YAML files, sync resources, or worry about configuration drift. ### How It Works Environments are created from **App Catalogs**, which serve as blueprints for your application. When you create an environment: 1. Select an existing App Catalog that defines your app's workloads 2. Choose an environment type (Personal, Shared, or Branch) 3. Lapdev deploys the workloads: * Personal/Shared: into a dedicated namespace * Branch: into the shared base environment's namespace 4. ConfigMaps, Secrets, and Services are automatically included The result: a fully functional copy of your app that mirrors production exactly, with zero manual YAML management. > App Catalogs are created by reading production manifests directly from your cluster. Learn more about [**App Catalogs**](/core-concepts/app-catalog). ### Environment Types Lapdev supports three environment types, depending on your workflow and cost requirements: * **Personal Environments** — fully isolated, ideal for independent development * **Shared Environments** — team-wide baseline, ideal for integration testing * **Branch Environments** — lightweight personal modifications on shared foundation, ideal for large teams All types support **Devbox** for local development and debugging. #### 1. Personal Environments A **Personal Environment** is a completely isolated workspace for a single developer. Each personal environment runs in its **own Kubernetes namespace**, so: * One developer’s work never affects another’s. * Multiple environments can be created per developer (e.g., one per feature or bug fix). * You can switch between environments freely. Because every personal environment contains a **full set of workloads**, it guarantees total isolation — but that comes with higher resource usage. Lapdev helps mitigate this cost by allowing you to **pause and resume environments on demand**, automatically scaling down resources when you’re not using them. **Best for:**\ Developers who need full isolation or want to test complex changes safely. #### 2. Shared Environments A **Shared Environment** is a team-wide baseline that runs a complete version of your app. * Created and managed by admins * Accessible by all team members * Acts as the foundation for branch environments * Ideal for integration testing or staging setups **Best for:**\ Teams who need a stable, shared environment for testing or as a baseline for branch environments. #### 3. Branch Environments **Branch Environments** provide a cost-effective way to test changes by building on top of a shared environment. When you create a branch environment: * Initially, it references all workloads from the shared environment * Only when you modify a service does Lapdev create a branched copy * The branched copy runs alongside the shared version inside the shared environment's namespace, and Lapdev handles routing between them * Unmodified services continue using the shared environment * Multiple developers can work simultaneously without conflicts This Git-like branching model means: * **Near-instant creation** - no waiting for full environment deployment * **Minimal cost** - only run what you're changing (up to 88% infrastructure reduction) * **Realistic testing** - test against real production-like services, not mocks **How it works:** Lapdev uses intelligent traffic routing to direct requests to your branched services while everything else uses the shared baseline. This enables multiple developers to safely test changes in parallel. **Requirements:** * Services must communicate via HTTP/HTTPS * Your application must forward `tracestate` headers in service calls * Non-HTTP components (databases, message queues) remain shared **Best for:**\ Large teams doing frequent feature development with cost efficiency in mind. > For technical details on routing, sidecar proxies, and header propagation, see [**Branch Environment Architecture**](/core-concepts/architecture/branch-environment-architecture). ### Local Development with Devbox All environment types support **Devbox**, Lapdev's CLI tool for local development. Devbox allows you to: * **Intercept cluster traffic** to your local machine for real-time debugging * Use your **local IDE** to edit, build, and debug as if running in the cluster * **Access in-cluster resources** (databases, caches, internal APIs) transparently When connected via Devbox, your local process integrates seamlessly with your environment. Other services automatically route traffic to your local instance, combining fast local iteration with accurate cluster integration. > Learn more about [**Devbox**](/core-concepts/devbox) and how to use it. ### Preview URLs Every Lapdev environment can expose one or more **Preview URLs** — public HTTPS endpoints for accessing or sharing your running services. Preview URLs are created **per service**. You choose which service to expose, and Lapdev automatically handles DNS, certificates, routing, and security. When requests come in through a Preview URL in a branch environment, Lapdev automatically manages the **`tracestate` header** to route traffic to the correct branch environment. > Learn more about [**Preview URLs**](/core-concepts/preview-url). ### Comparison | Feature | Personal Environment | Shared Environment | Branch Environment | | --------------- | ------------------------------------- | ------------------------------------- | ----------------------------------- | | **Isolation** | Fully isolated (per namespace) | Shared by all team members | Shared base, routed isolation | | **Cost** | Highest | Medium | Lowest | | **Ideal For** | Deep testing, multi-service debugging | Integration testing, team staging | Large teams, frequent branching | | **Performance** | Slower to start, full workloads | Full workloads, shared infrastructure | Instant setup, minimal overhead | | **Access** | Single developer | Entire team | Single developer (with shared base) | ### Summary Lapdev Kubernetes Environments let you: * Reproduce production exactly, without manual setup * Stay notified when production changes - sync with one click when you're ready * Choose between **full isolation**, **team-wide sharing**, or **cost-efficient branching** * Use **Devbox** for fast, local-style development in Kubernetes * Collaborate efficiently with consistent, shareable environments Whether you're developing alone, testing as a team, or scaling across a large organization, Lapdev ensures every environment stays consistent, efficient, and production-accurate. # Devbox **Devbox** is Lapdev’s local development companion — a CLI tool that connects your local machine directly to your Lapdev Kubernetes environment. It bridges the gap between *local iteration speed* and *production realism*. ### Why Devbox Developing in Kubernetes usually means slow feedback loops: rebuild, redeploy, and wait for pods to restart just to test a single change.\ Devbox changes that by letting you **run your code locally while still connected to your real cluster environment**. This means: * You can test your app against live in-cluster services (databases, APIs, caches). * Cluster traffic can be routed to your local process for real-time debugging. * You no longer need complex port-forwarding, VPNs, or separate mock setups. ### How It Works When you start Devbox inside a Lapdev environment: 1. It authenticates with Lapdev and connects to your active environment’s namespace. 2. It synchronizes local and cluster networking rules. 3. It can optionally intercept service traffic and forward it to your local process. 4. It provides seamless access to other workloads and in-cluster dependencies. > 💡 Devbox doesn't replace Kubernetes — it *extends* it for developers.\ > You keep your production topology and cluster configuration, but develop with local speed. ### Core Capabilities * **Intercept Service Traffic:** Redirect in-cluster service requests to your local code. * **In-Cluster Connectivity:** Access internal APIs and databases as if you were inside the pod. * **Seamless IDE Debugging:** Run locally, attach debuggers, and see live logs. * **Compatible with All Environment Types:** Works with personal, shared, and branch environments. ### How It Fits in the Lapdev Model | Concept | Role | | --------------- | ---------------------------------------------------------------------- | | **App Catalog** | Defines what your app consists of (the workloads). | | **Environment** | A running instance of that app in Kubernetes. | | **Devbox** | Bridges your local machine with that environment for live development. | ### When to Use Devbox * When you need fast feedback without redeploying to Kubernetes. * When debugging complex issues that depend on real cluster state. * When integrating or testing locally while keeping the rest of the system in-cluster. ### Next Steps Ready to use Devbox? See [**Local Development with Devbox**](/how-to-guides/local-development-with-devbox) for setup instructions. # Preview URL A **Preview URL** is a unique, automatically generated HTTPS endpoint that lets you access services in your Lapdev environment directly from the web — without any manual DNS or Ingress configuration. You can create Preview URLs for any environment type (**personal**, **shared**, or **branch**), exposing specific services for access and sharing.\ This makes it easy to preview changes, share work with teammates, and test production-like behavior in real time. ### Why Preview URLs In traditional Kubernetes setups, exposing your app for testing often means: * Creating or editing Ingress rules * Configuring DNS records * Managing TLS certificates * Waiting for ops to approve changes That’s slow, error-prone, and not scalable for dozens of developers or short-lived environments. Lapdev solves this with **automatic Preview URLs** — secure, per-environment endpoints that “just work.” ### How It Works When you create a Preview URL for a service in your environment, Lapdev: 1. Detects the service you want to expose (e.g. `frontend`, `api`, `gateway`) 2. Automatically generates a unique HTTPS domain for that service 3. Configures TLS certificates automatically — no `cert-manager`, DNS setup, or manual YAML needed 4. Routes traffic through Lapdev's managed proxy layer directly to your service inside the cluster All routing and TLS termination are handled by Lapdev's control plane, so your cluster stays secure and simple. Each Preview URL is unique and automatically managed by Lapdev, making it safe to share with your team. ### Access Control Preview URLs default to **Organization** access, but you can configure per Preview URL: * **Organization (default):** Only members of your Lapdev organization can access (after login) * **Public:** Anyone with the link can access without authentication Access settings are managed per Preview URL in the Lapdev dashboard. ### Benefits ✅ **Instant access:** No waiting for ops or configuring ingress.\ ✅ **Secure by default:** Auto-managed HTTPS and certificates.\ ✅ **Shareable:** Send links to PMs, QA, or teammates easily.\ ✅ **Isolated:** Each environment’s URL maps only to its own workloads.\ ✅ **Consistent:** Same domain and routing system across all environments. ### How It Relates to Other Lapdev Components | Component | Role | | --------------- | --------------------------------------------------------------------------- | | **App Catalog** | Defines which workloads are part of the app. | | **Environment** | A running instance of the app in Kubernetes. | | **Preview URL** | Provides web access to that environment — with automatic routing and HTTPS. | ### Usage Pattern Preview URLs make collaboration effortless: * Create an environment and expose the services you want to share * Lapdev generates secure HTTPS URLs automatically * Share URLs with teammates, QA, or stakeholders instantly * No infrastructure changes, ingress configuration, or firewall rules needed > For step-by-step instructions, see [**Use Preview URLs**](/how-to-guides/use-preview-urls).