Deploy to Crayy

Get your app live in under a minute. Works with Node.js, Next.js, Flask, FastAPI, Streamlit, Gradio, and static HTML.

1. Quick Start

Claude Code will read these docs, walk you through naming your app, and handle the deploy automatically. Or follow the manual steps below.

2. How the Platform Works

Understanding the deploy pipeline helps you prepare your app correctly and troubleshoot any issues.

What happens when you POST to /api/deploy

The server runs this pipeline (takes 2–5 minutes total):

1. Extract tarball to a staging directory
2. Detect app type — looks for package.json (Node.js), requirements.txt (Python), or .html files (static)
3. AI code review (Onboarding Agent) — an AI agent reads your source code and performs:
   • Security scan: checks for shell injection, file system exploits, reverse shells, crypto mining, secrets exfiltration
   • Content check: checks for illegal/harmful content (lenient — finance apps with aggressive language are fine)
   • Auto-fix: if your app is missing a /health endpoint or doesn't read the PORT env var, the agent generates minimal patches and applies them automatically
   • Profile: generates a category, summary, capabilities list, and tags for platform discovery

   This step calls Claude and takes 5–15 seconds. If the AI API is down, the review is skipped and the deploy proceeds (fail-open).

4. Decision gate:
   • approve → proceed to build
   • approve_with_changes → apply the AI's patches to the source, then build
   • reject → stop, return rejection reason, no container created
5. Reserve name + allocate port — atomic SQLite transaction assigns the next available port (3001, 3002, ...)
6. Docker build — copies a Dockerfile template into the app, runs docker build. This installs dependencies (npm install / pip install) inside the container. Takes 30–120 seconds depending on dependency count.
7. Run container — starts the container on the allocated port, connected to the crayy-apps Docker network, with CPU/memory limits (0.5 CPU, 1GB RAM)
8. Health check — polls GET /health (or framework-specific path) every 2 seconds, up to 15 retries (30 seconds total). If the app responds with HTTP 2xx/3xx, it passes.
9. Go live — updates nginx config to route /appname/ traffic to the container, reloads nginx. The app is now accessible at https://mvp.crayy.com/appname.

How containers run your code

Next.js apps (built from source automatically)

The platform auto-detects Next.js apps (by checking for next in package.json dependencies) and builds them from source inside Docker. You do NOT need to run npm run build locally. Just send the source code like any other Node.js app.

If your app uses output: "standalone" in next.config (recommended), the platform handles the standalone setup. If not, it falls back to next start. Either way, just send source code.

App URLs — path-based, NOT subdomains

Common failure modes and what they mean

Container environment

• Base images: node:20-slim (Node.js), python:3.11-slim (Python), nginx:alpine (static)
• Resource limits: 0.5 CPU, 1GB RAM per container
• Network: containers are on the crayy-apps Docker bridge network
• The PORT env var is set to the internal port (3000/5000/8501/etc.) — your app should read it
• Containers restart automatically (unless-stopped policy)
• No persistent storage — data written inside the container is lost on restart/redeploy
• Selenium auto-detection: If selenium appears in your requirements.txt, Chromium and chromedriver are automatically installed in the container. Environment variables CHROME_BIN and CHROMEDRIVER_PATH are set automatically.

3. App Requirements

• Health endpoint: GET /health returning HTTP 200. The platform polls this to confirm your app started. Streamlit and Gradio have built-in health. The AI agent can auto-add /health if you forget, but client-side is more reliable.
• Entry point: Node.js auto-detects from package.json or common files. Next.js auto-detects standalone server. Flask needs app.py at root.
• Single port: Read from the PORT env var or use the framework default.
• Tarball max size: 1GB. Exclude node_modules, .git, __pycache__, .next, out (platform installs deps and builds from source). INCLUDE .env files and data files (.db, .sqlite) — apps need their API keys and data to work in production.
• No auth required: Apps are served at https://mvp.crayy.com/appname.

4. Deploy Steps

Step 1: Choose an app name (new deploys only)

Step 2: Verify name availability

curl -s https://mvp.crayy.com/api/check-name/{name}
# Response: { "name": "my-app", "available": true }

Step 3: Get user's email (new deploys only)

Step 4: Ensure /health endpoint exists

Check the source for a /health endpoint. If missing, add one (see framework examples in section 6).

Step 5: Prepare the app

For ALL app types, just send the source code. The platform handles building and dependencies.

• Node.js (Express, etc.): Tarball the source directly. The platform auto-detects the entry point.
• Next.js: Tarball the source directly — same as Node.js. Do NOT build locally. The platform detects Next.js, runs npm run build inside Docker, and sets up the standalone output automatically.
• Flask: Tarball the source directly. The platform auto-detects the entry file (looks for Flask(__name__)).
• FastAPI: Tarball the source directly. The platform auto-detects the FastAPI app and launches it via uvicorn. Do NOT add a if __name__ == "__main__": uvicorn.run(...) block.
• Static: Just tarball the HTML/CSS/JS files.

Step 6: Create the tarball

Same command for ALL app types (including Next.js). Use EXACTLY these excludes — no more, no less:

tar -czf /tmp/crayy-deploy-${name}.tar.gz --exclude=node_modules --exclude=__pycache__ --exclude=.git --exclude=.crayy --exclude=.next --exclude=out -C <appDir> .

Step 7: Deploy

curl -s --max-time 600 -X POST https://mvp.crayy.com/api/deploy \
  -F "file=@/tmp/crayy-deploy-${name}.tar.gz" \
  -F "name=my-app" \
  -F "displayName=My Cool App" \
  -F "description=One-line description" \
  -F "email=user@example.com"

Step 8: Handle the response

The response is JSON. Check the status field:

"deployed" — Success!

{
  "status": "deployed",
  "app": { "name": "my-app", "url": "https://mvp.crayy.com/my-app", "displayName": "My Cool App" },
  "deployToken": "abc123...",
  "oaChanges": [{ "file": "...", "description": "..." }],
  "message": "App deployed successfully!"
}

Save the deploy token for future updates:

mkdir -p .crayy && cat > .crayy/config.json << 'EOF'
{
  "appName": "my-app",
  "deployToken": "abc123...",
  "url": "https://mvp.crayy.com/my-app"
}
EOF

The oaChanges array shows any auto-fixes the AI applied (e.g., added /health endpoint). Show these to the user so they know what changed.

"rejected" — AI review rejected the app:

{ "status": "rejected", "reason": "...", "securityNotes": "...", "contentNotes": "..." }

No container was created. The user needs to fix the issues described in reason and try again.

"failed" — Build or health check failed:

{ "status": "failed", "error": "...", "logs": "..." }

The logs field contains the last 50 lines of container output. Common causes: the app crashed on startup, a dependency failed to install, or /health didn't respond in time.

5. Update / Redeploy

When .crayy/config.json exists, the app has been deployed before. Do NOT ask the user for an app name or email. Everything you need is in the config file.

1. Read .crayy/config.json for appName and deployToken. Use these values directly — do not prompt the user.
2. Prepare and tarball the app (same as initial deploy — remember to include ALL data files: .db, .sqlite, .csv, data/ directories, etc.)
3. POST with the deploy token included:

   curl -s --max-time 600 -X POST https://mvp.crayy.com/api/deploy \
     -F "file=@/tmp/crayy-deploy-${name}.tar.gz" \
     -F "name=my-app" \
     -F "displayName=My Cool App" \
     -F "description=Updated description" \
     -F "email=user@example.com" \
     -F "deployToken=abc123..."

The server stops the old container, builds a new image, runs it on the same port, and health checks. On success, returns status: "updated". On failure, the old container is gone — a fix and redeploy is needed.

If the deploy token is wrong, you get a 403. If the app name doesn't exist, you get a 404.

6. Adding /health — Framework Examples

Express (Node.js)

app.get('/health', (req, res) => res.status(200).json({ status: 'ok' }));

Next.js (App Router)

// app/health/route.ts
export async function GET() {
  return Response.json({ status: 'ok' });
}

Next.js (Pages Router)

// pages/api/health.ts — serves at /api/health
export default function handler(req, res) {
  res.status(200).json({ status: 'ok' });
}
// Add rewrite in next.config.js to serve at /health:
// async rewrites() { return [{ source: '/health', destination: '/api/health' }] }

Flask

@app.route('/health')
def health():
    return {'status': 'ok'}, 200

FastAPI

@app.get('/health')
def health():
    return {'status': 'ok'}

Streamlit

Built-in at /_stcore/health. No action needed.

Gradio

Built-in at /. No action needed.

Static HTML

Create a health file or health/index.html. The platform nginx config handles it.

7. API Reference

Check Name Availability

GET /api/check-name/:name
Response: { "name": "my-app", "available": true }

Deploy / Update App

POST /api/deploy  (multipart/form-data, --max-time 600)

Fields:
  file         file    required   .tar.gz of the app
  name         string  required   lowercase alphanumeric + hyphens, 1-40 chars
  displayName  string  optional   human-readable name
  description  string  optional   one-line description
  email        string  optional   creator email
  deployToken  string  optional   include for updates (from .crayy/config.json)

Responses:
  "deployed"  → { status, app: {name, url, displayName}, deployToken, oaChanges, message }
  "updated"   → { status, app: {name, url, displayName}, oaChanges, message }
  "rejected"  → { status, reason, securityNotes, contentNotes }
  "failed"    → { status, error, logs }

Discover Apps

GET /api/discover
Response: { platform, version, apps: [{ name, displayName, description, type, url, status, profile }] }