> ## Documentation Index > Fetch the complete documentation index at: https://docs.cubby.pro/llms.txt > Use this file to discover all available pages before exploring further. # How Cubby Runs Your App > What happens when you deploy, how requests reach your app, and what Cubby handles for you # How Cubby Runs Your App Cubby turns a small web app into a live, authenticated, database-backed app with one command. You bring the code. Cubby verifies it, builds it, runs it, routes it, protects it with Cubby SSO, and injects the runtime pieces your app needs. This page explains the two flows that matter most: 1. **Deploy path** — what happens after `cubby deploy`. 2. **Request path** — what happens when someone opens your app URL. ## The short version ```text theme={null} Your laptop / AI IDE └─ cubby deploy └─ Cubby API ├─ verification + safety checks ├─ GCS staging ├─ Cloud Build ├─ Artifact Registry └─ GKE deployment └─ Envoy Gateway + Cloudflare route traffic to your app ``` Your app runs as an isolated container on Google Kubernetes Engine. Every request passes through Cubby's edge/auth layer before it reaches your code. Your app reads identity from trusted Cubby headers and reads its database and secrets from environment variables. ## What your app needs to know Most apps only need these rules: * Listen on `PORT`. * Read the current user from `X-Cubby-User-Id` and `X-Cubby-Username`. * Read `DATABASE_URL` at runtime; never hardcode a database connection string. * Use `cubby secrets set` for API keys and other secrets. * Do not add your own login system unless you have a very specific reason. Cubby SSO protects the app before traffic reaches it. * Keep the app small enough to build and boot cleanly in a container. ## Deploy path When you run `cubby deploy`, Cubby moves your app through a build-and-release pipeline: ```text theme={null} CLI └─ package source └─ upload to Cubby API └─ verify project └─ stage source in GCS └─ Cloud Build creates an image └─ push to Artifact Registry └─ apply Kubernetes resources └─ health check └─ live URL ``` ### 1. Package and upload The CLI packages your project, respecting ignore rules so the upload stays focused. It sends the package to the Cubby API with your app configuration from `cubby.yaml`. ### 2. Verify before build Cubby checks the project before spending time on a build: * blocked dependencies and platform-incompatible packages * accidental secrets in source * project structure and package manager fit * PWA manifest/icon readiness where Cubby can help * basic deployment safety rules You can run the same style of checks locally with `cubby check`. ### 3. Build and store the image Cubby stages the source in Google Cloud Storage, runs Cloud Build, and stores the resulting image in Artifact Registry. Your source package and image are separate from other users' apps. ### 4. Run on GKE Cubby applies Kubernetes resources for the app: Deployment, Service, routing, environment, secrets, resource limits, and database configuration. A health check confirms the new version can boot before the deploy is treated as successful. ## Request path When someone opens your app URL, traffic takes this path: ```text theme={null} User browser └─ Cloudflare DNS + TLS └─ Envoy Gateway └─ Cubby auth / ForwardAuth └─ your app Service └─ your app Pod └─ SQLite PVC or Neon Postgres ``` ### URL format Cubby app URLs are designed to keep app and username boundaries unambiguous: ```text theme={null} https://--.cubby.pro | | | └── your Cubby username └── your app name ``` ## Authentication Every Cubby app is protected by platform-level SSO. Your app does not need `next-auth`, OAuth setup, password screens, or invite logic just to know who is using it. * Envoy Gateway calls Cubby's auth layer before forwarding requests. * Unauthenticated users are sent through Cubby login. * Authorized requests get trusted identity headers. * The gateway strips spoofed identity headers and re-adds the trusted values. * Sharing controls decide which Cubby users can access which apps. Your app can scope data like this: ```ts theme={null} import { headers } from 'next/headers' const h = await headers() const userId = h.get('X-Cubby-User-Id') const username = h.get('X-Cubby-Username') ``` ## Database options Cubby is SQLite-first by default and offers Neon Postgres for Builder and Pro users who need a hosted Postgres workflow. ### SQLite — default on every plan SQLite is the simplest path for most first cubbies: * available on every plan, including Free * backed by a Kubernetes PersistentVolumeClaim * works well for personal tools, friend-group apps, small dashboards, and prototypes * `DATABASE_URL` is injected automatically * Prisma templates are already wired to read the runtime database URL ### Neon Postgres — Builder and Pro Choose Neon Postgres when you need Postgres semantics, branching, snapshots, or a stronger concurrent-write story: * Builder and Pro plans * Cubby-managed Neon project/database setup * `DATABASE_URL` and `DIRECT_URL` injected at runtime * compatible with `cubby db` commands * best for more serious apps or data workflows that already expect Postgres See [Building with Neon Postgres](/tutorials/neon-apps) for the dedicated path. ## Secrets and environment Use `cubby secrets` for secrets. Cubby encrypts them, injects them at runtime, and keeps them out of deploy logs and source code. ```bash theme={null} cubby secrets set OPENAI_API_KEY # prompts for the value cubby deploy ``` Your app should read secrets from `process.env` like any other server-side Node app. ## Isolation and resources Cubby keeps apps isolated at the platform layer: * app containers run separately from the Cubby control plane * user/app resources are separated in Kubernetes * traffic reaches app pods only through the gateway path * container resources are bounded so one app cannot consume the whole cluster * secrets are injected at startup and not returned through normal API responses Default app resources are intentionally modest and can be tuned through `cubby.yaml` as the platform exposes more controls. ## What Cubby owns vs. what you own | Cubby owns | You own | | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | Routing, TLS, auth gate, deploy pipeline, build infrastructure, runtime environment, database injection, secret injection | App code, dependencies, schema, migrations/data model, user-facing behavior, third-party API usage | That split is the point: Cubby takes the deployment/platform chores so you and your AI tools can stay focused on the app. ## Where to go next Deploy your first cubby in a few commands. Learn the app URL, auth, database, secrets, sharing, and billing model. Read trusted Cubby identity headers inside your app. Exact CLI flags, deploy output, and troubleshooting.