Skip to main content

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

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

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: 
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: 
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: 
https://<app-name>--<username>.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: 
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 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. 
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 ownsYou own
Routing, TLS, auth gate, deploy pipeline, build infrastructure, runtime environment, database injection, secret injectionApp 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

Quickstart

Deploy your first cubby in a few commands.

Core concepts

Learn the app URL, auth, database, secrets, sharing, and billing model.

Authentication

Read trusted Cubby identity headers inside your app.

Deployment reference

Exact CLI flags, deploy output, and troubleshooting.