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.

​
Deploy Verification

Every deploy goes through a 3-phase verification pipeline. Checks can pass, warn, or fail. Failures block deployment. Warnings are informational. Some issues are auto-fixed by Cubby.

​
Phase 1: Pre-Build Checks

Pre-build checks run on your source code before the Docker image is built. All four checks run concurrently.

​
Blocked Dependencies

Detects payment and authentication libraries that conflict with Cubby’s built-in features. Blocked payment libraries (Cubby does not support in-app payment processing):
  • stripe, @stripe/stripe-js, @stripe/react-stripe-js
  • @paypal/checkout-server-sdk, @paypal/react-paypal-js
  • @lemonsqueezy/lemonsqueezy.js, @paddle/paddle-js
  • braintree, square, revenuecat
Blocked auth libraries (Cubby provides built-in SSO):
  • next-auth, @auth/core, @auth/nextjs
  • @clerk/nextjs, @clerk/backend
  • passport, passport-local, passport-jwt
  • lucia, @lucia-auth/adapter-prisma
  • better-auth, @supabase/auth-helpers-nextjs
If found in your package.json dependencies or devDependencies, the deploy is blocked with a fail status.

​
Secret Detection

Scans your source files for committed API keys, tokens, and private keys. Uses pattern matching for known secret formats:
  • High confidence (blocks deploy): AWS access keys (AKIA...), Stripe live keys (sk_live_...), GitHub tokens (ghp_...), Anthropic keys (sk-ant-...), OpenAI keys (sk-...), private key blocks (-----BEGIN PRIVATE KEY-----), and more
  • Medium confidence (warning only): Generic patterns like api_key = "..." assignments
The scanner skips node_modules, .next, dist, .git, binary files, and .env.example files.
Use cubby secrets set to store API keys securely instead of committing them to your code.

​
Project Structure

Validates that required files exist and configuration is correct:
  • package.json: Required. Deploy fails if missing.
  • cubby.yaml: Recommended. Warning if missing or malformed. Must contain a name field.
  • Dockerfile: If present, validated for security. Must include a non-root USER instruction. Dangerous patterns are flagged.

​
Service Worker Cache Versioning

Scans for service worker files (sw.js, service-worker.js, and their .ts variants) and checks if they use static cache names. If your service worker calls caches.open('my-cache') with a hardcoded string (no version or hash), you get a warning. Static cache names cause stale UI after redeploy, especially on iOS Safari PWAs. See PWA Support for how to version your cache names.

​
Phase 2: AI Review

A two-pass AI pipeline reviews your source code for security, content, authentication, and PWA issues.

​
Pass 1: Haiku (Fast Scan)

Claude Haiku scans your source files for common issues. This is a quick pass that covers:
  • Security: Code vulnerabilities, dangerous patterns
  • Content: Inappropriate or problematic content
  • Auth integration: Correct usage of Cubby auth headers
  • PWA compliance: Manifest and service worker issues
If Haiku finds nothing, the review is complete and the deploy continues.

​
Pass 2: Sonnet (Escalation)

If Haiku flags any issues, Claude Sonnet performs a deeper review to confirm or dismiss each finding. This reduces false positives — Sonnet may dismiss findings that Haiku flagged. Confirmed findings are reported as:
  • block: Critical issue, deploy is blocked
  • warn: Advisory, deploy proceeds
  • dismiss: False positive, no action needed

​
PWA Auto-Fix

As part of the AI review phase, Cubby runs a deterministic (non-AI) check on your PWA assets:
  • Missing manifest.json: Generates one with your app name, theme color, display mode, and icons
  • Missing icons: Generates 192x192 and 512x512 PNG icons with a color derived from your app name
  • Missing manifest link: Warns if your layout file lacks a <link rel="manifest"> tag
Auto-fixed items appear in your deploy report with status fixed.

​
AI Cost Transparency

Each AI review reports the model used and token counts, so you can see the cost of the review in your deploy report.

​
Phase 3: Post-Build Checks

Post-build checks run after your Docker image is built and the container starts.

​
Health Check

Sends an HTTP GET request to the root path (/) of your running container. Expects an HTTP 200 response within 30 seconds. If the health check fails:
  • Container startup logs are captured for debugging
  • The deploy is blocked
  • The error message includes the logs to help you diagnose the issue

​
Manifest Validation

If the HTTP health check passes, Cubby also checks that manifest.json is accessible and valid at the running app URL. A missing or invalid manifest produces a warning (not a failure) — your app still deploys, but PWA install may not work correctly.

​
Check Statuses

StatusMeaningDeploys?
passCheck passedYes
warnAdvisory issue foundYes
failCritical issue foundNo
fixedIssue auto-fixed by CubbyYes
errorCheck itself failed to runYes (degraded)
The overall deploy status is determined by the worst individual check status: any fail or error blocks the deploy. Warnings and fixes allow it to proceed.

​
Viewing Results

Verification reports are shown in the CLI during cubby deploy: 
Verification Report
-------------------
Pre-Build Checks:
  blocked-dependencies ............ PASS
  secret-detection ................ PASS
  structure-package-json .......... PASS
  structure-cubby-yaml ............ PASS
  sw-cache-versioning ............. PASS

AI Review:
  PWA Manifest .................... FIXED (generated manifest.json and icons)
  AI Review (haiku) ............... PASS

Post-Build Checks:
  http-health ..................... PASS
  manifest-json ................... PASS
Reports are also available in the dashboard under each app’s deploy history.