in progress

Made-with: Cursor

Author: Ryan

.gitignore

@@ -56,4 +56,9 @@ backend/app.db
 backend/app.db-journal
 backend/uploads/
 
-.claude/
+.claude/
+
+# Cloudflare Wrangler local state (account id, project cache, dev secrets)
+.wrangler/
+.dev.vars
+.dev.vars.*

backend/_modal.py

@@ -0,0 +1,87 @@
+"""Modal deployment for the dploy backend.
+
+Deploy with:
+
+    cd backend && modal deploy _modal.py
+
+Architecture
+------------
+The FastAPI app runs on Modal as a single-instance ASGI app. Single instance
+is intentional: `app.services.sandbox_pool` (the warm Modal-sandbox pool) and
+the WebSocket terminal session registry both live in process memory. Multiple
+containers would split that state and break sandbox lookup mid-deploy.
+
+Throughput is gated by `@modal.concurrent(max_inputs=100)` — one container
+serves up to 100 concurrent HTTP/WS requests, plenty for current load.
+
+State
+-----
+A Modal Volume is mounted at `/data` and used for the SQLite database. The
+Secret sets `DATABASE_URL=sqlite+aiosqlite:////data/app.db` so the URL
+survives container restarts/redeploys. (Switch to managed Postgres later if
+you need backups, replicas, or zero-downtime deploys.)
+
+Note: `backend/uploads/` is currently in-container only. It's not wired up
+to the deploy flow yet (`upload-based deployments not yet supported`), so
+losing it on restart is a no-op for now. When uploads ship, repoint
+`UPLOAD_DIR` at `/data/uploads`.
+
+Modal credentials
+-----------------
+This function runs *inside* Modal, so `modal.Sandbox.create()` authenticates
+implicitly via the workspace identity — no `MODAL_TOKEN_*` env vars needed.
+
+Secrets (one-time setup)
+------------------------
+Create a Modal Secret named `dploy-backend` before the first deploy:
+
+    modal secret create dploy-backend \\
+        ANTHROPIC_API_KEY=... \\
+        GITHUB_CLIENT_ID=... \\
+        GITHUB_CLIENT_SECRET=... \\
+        SESSION_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(48))')" \\
+        FRONTEND_URL=https://dploy.ryantanen.com \\
+        GITHUB_REDIRECT_URI=https://api.dploy.ryantanen.com/api/v1/auth/github/callback \\
+        CORS_ORIGINS='["https://dploy.ryantanen.com"]' \\
+        SESSION_COOKIE_SECURE=true \\
+        DATABASE_URL=sqlite+aiosqlite:////data/app.db
+"""
+
+import modal
+
+app = modal.App(name="dploy-backend")
+
+# Image build:
+#   1. `pip_install_from_pyproject` reads ./pyproject.toml at deploy time and
+#      installs the runtime deps. Cached across deploys unless pyproject changes.
+#   2. `add_local_python_source("app")` ships the `app/` package (including
+#      non-Python files like openclaw.json) into the image at deploy time.
+#      This is the bit that was missing — without it, `from app.main import
+#      create_app` fails with ModuleNotFoundError.
+image = (
+    modal.Image.debian_slim(python_version="3.13")
+    .pip_install_from_pyproject("pyproject.toml")
+    .add_local_dir("app", remote_path="/root/app")
+)
+
+volume = modal.Volume.from_name("dploy-backend-data", create_if_missing=True)
+
+
+@app.function(
+    image=image,
+    secrets=[modal.Secret.from_name("dploy-secrets")],
+    volumes={"/data": volume},
+    # Pin to one container — sandbox_pool + WS terminal sessions are in-memory.
+    min_containers=1,
+    max_containers=1,
+    # WebSocket terminal sessions can stay open for a long time.
+    timeout=60 * 60,
+    # Don't aggressively idle the container out — keeps the warm sandbox
+    # pool alive between bursts of traffic.
+    scaledown_window=60 * 30,
+)
+@modal.concurrent(max_inputs=100)
+@modal.asgi_app()
+def fastapi_app():
+    from app.main import create_app
+    return create_app()

backend/app/models/__init__.py

@@ -7,6 +7,15 @@
 )
 from app.models.session import Session
 from app.models.user import User
+from app.models.warm_sandbox import (
+    WARM_ALIVE_STATUSES,
+    WARM_STATUSES,
+    WARM_STATUS_CLAIMED,
+    WARM_STATUS_FAILED,
+    WARM_STATUS_READY,
+    WARM_STATUS_WARMING,
+    WarmSandbox,
+)
 
 __all__ = [
     "AGENT_KINDS",
@@ -16,4 +25,11 @@
     "Deployment",
     "Session",
     "User",
+    "WARM_ALIVE_STATUSES",
+    "WARM_STATUSES",
+    "WARM_STATUS_CLAIMED",
+    "WARM_STATUS_FAILED",
+    "WARM_STATUS_READY",
+    "WARM_STATUS_WARMING",
+    "WarmSandbox",
 ]

backend/app/models/warm_sandbox.py

@@ -0,0 +1,75 @@
+"""Persistent state for the warm sandbox pool.
+
+Each row tracks one Modal sandbox that's been pre-provisioned (gateway up,
+model set) and is either still being warmed, ready to claim, or already
+claimed by a deployment.
+"""
+
+import uuid
+from datetime import datetime
+from typing import Final
+
+from sqlalchemy import DateTime, Index, String, Text
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+WARM_STATUS_WARMING: Final = "warming"
+WARM_STATUS_READY: Final = "ready"
+WARM_STATUS_CLAIMED: Final = "claimed"
+WARM_STATUS_FAILED: Final = "failed"
+
+WARM_STATUSES: Final = (
+    WARM_STATUS_WARMING,
+    WARM_STATUS_READY,
+    WARM_STATUS_CLAIMED,
+    WARM_STATUS_FAILED,
+)
+
+WARM_ALIVE_STATUSES: Final = (WARM_STATUS_WARMING, WARM_STATUS_READY)
+
+
+def _new_id() -> str:
+    return uuid.uuid4().hex
+
+
+class WarmSandbox(Base):
+    __tablename__ = "warm_sandboxes"
+
+    # Local slot id. Stable from the moment _replenish() reserves a slot,
+    # before we know the Modal sandbox_id.
+    id: Mapped[str] = mapped_column(String(32), primary_key=True, default=_new_id)
+
+    # Modal sandbox object id. NULL while warming; set when status flips to
+    # `ready`. Indexed because the diagnostics page joins by it.
+    sandbox_id: Mapped[str | None] = mapped_column(String(64), nullable=True)
+
+    model: Mapped[str] = mapped_column(String(128), nullable=False)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default=WARM_STATUS_WARMING)
+
+    # `created_at` / `updated_at` come from Base. We add explicit ready/claimed
+    # timestamps so the diagnostics endpoint can show how long warmup took
+    # and how stale a claim is.
+    ready_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+    claimed_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    error: Mapped[str | None] = mapped_column(Text, nullable=True)
+
+    __table_args__ = (
+        # Hot path: "find me a ready sandbox for this model, oldest first".
+        Index(
+            "ix_warm_sandboxes_status_model_created",
+            "status", "model", "created_at",
+        ),
+    )
+
+
+__all__ = [
+    "WarmSandbox",
+    "WARM_STATUS_WARMING",
+    "WARM_STATUS_READY",
+    "WARM_STATUS_CLAIMED",
+    "WARM_STATUS_FAILED",
+    "WARM_STATUSES",
+    "WARM_ALIVE_STATUSES",
+]