Deploying

marimohub ships as a single container image (apps/server/Dockerfile) that serves both the API and the web UI. Pick a platform below; each guide covers the image, configuration, the three backends (storage / compute / auth), and background maintenance.

• Helm — install/upgrade any cluster from the published, versioned marimohub chart (single-tenant).
• Single instance — one Linux box (cloud VM or on-prem) with fs storage + docker compute; no object store, no cluster.
• CoreWeave (CKS) — CAIOS + CoreWeave Sandboxes + OIDC.
• Kubernetes — any cluster (EKS/GKE/AKS/self-managed) with native Pod kernels via the kubernetes compute backend.
• GCP — GKE or Compute Engine with GCS or persistent disk storage. Cloud Run uses GCS in this guide.
• AWS — EKS or EC2 with S3 or persistent disk storage. ECS/Fargate hub deployments use S3 in this guide.
• Azure — AKS or Azure VMs with Blob Storage or persistent disk storage.
• Cloudflare — Workers + R2 + Containers + Access (serverless).

The AWS, GCP, and Azure pages cover compute, storage, auth, features, security, and operations. Each page lists platform choices and links to detailed setup guides. Backend choices depend on the hub host and its persistent storage support.

These guides document the following pairings:

Hub host	Notebook compute	Hub storage
EKS	kubernetes or fargate	S3 (s3), or fs on a persistent volume claim (PVC)
ECS/Fargate	fargate	S3 (s3)
EC2	docker	S3 (s3), or fs on EBS
GKE	kubernetes	Cloud Storage (gcs), or fs on a PVC
Compute Engine	docker	Cloud Storage (gcs), or fs on Persistent Disk
Cloud Run	External compute, such as modal or e2b	Cloud Storage (gcs)
AKS	kubernetes	Blob Storage (azure), or fs on a PVC
Azure VM	docker	Blob Storage (azure), or fs on Managed Disk

Every fs pairing requires a persistent filesystem mount and exactly one hub process, including maintenance. The platform guides do not provide an fs recipe for a hub hosted on Cloud Run or ECS/Fargate. Notebook compute runs separately from the hub's storage mount.

Path prefix

To publish the Node deployment at https://hub.example.com/marimohub/, set:

MARIMOHUB_APP_BASE_URL=https://hub.example.com/marimohub
MARIMOHUB_AUTH_OIDC_REDIRECT_URI=https://hub.example.com/marimohub/api/auth/callback

Configure nginx to strip the prefix and forward WebSocket connections:

location = /marimohub {
    return 308 /marimohub/;
}

location /marimohub/ {
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
    proxy_buffering off;
    proxy_pass http://marimohub:3000/;
}

The redirect adds the trailing slash to the public URL. The trailing slash on proxy_pass strips the prefix. X-Forwarded-Proto preserves HTTPS in public links. The timeouts permit one hour between WebSocket I/O operations. nginx passes streamed responses without buffering. The path prefix is runtime configuration, so one image can serve different prefixes.

If MCP is enabled, also proxy its root discovery path without stripping any path segment:

location = /.well-known/oauth-protected-resource/marimohub/mcp {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_pass http://marimohub:3000;
}

MCP clients can request this root path before they receive an authentication challenge. It serves metadata for both Hub and external authorization. Replace marimohub in this path with your deployment prefix. The metadata URL in the WWW-Authenticate challenge stays under /marimohub/ and uses the existing prefix proxy rule.

After deploy, validate the same core flow on every platform:

1. Check /api/health.
2. Sign in through the configured auth backend.
3. Create a project and notebook.
4. Start a kernel.
5. Save the notebook and confirm it survives a server restart.

See Configuration for every variable and Troubleshooting for common startup, login, and kernel failures.