DROP

DROP

Deploy, Run, Operate, Publish

A lightweight, self-hosted Platform as a Service (PaaS) engineered for the "drop folder and deploy" workflow. Zero-configuration deployment for Node.js, Python, Go, static sites, and containerized applications.

Drop a folder, get a URL. Zero configuration for 80% of use cases.

Features

• Zero-config deployment — auto-detects app type, builds, and starts
• Multi-runtime — Node.js, Python, Go, Docker, static sites and SPAs, with framework detection for Next.js, Nuxt, SvelteKit, Astro, Express, FastAPI, Flask and more
• Hostname routing and automatic HTTPS — Let's Encrypt certificates, per-app custom domains
• PostgreSQL auto-provisioning — apps get their own database with DATABASE_URL injected
• Managed Redis — opt in from drop.yaml
• Hot reload — edit files and the app rebuilds and restarts
• Monorepos — several services from one repo, sharing a hostname with same-origin /api routing
• MCP server — deploy and manage apps from Claude, Claude Code, Cursor and other agents
• Docker isolation — run tenant apps in containers with resource limits, for multi-user setups
• REST API and web dashboard — full API with JWT and API key auth, real-time monitoring UI
• Persistent data — app data survives upgrades via DROP_DATA_DIR
• Cross-platform — Windows, Linux and macOS

Documentation

Full documentation lives at [dropkit.sh/docs](https://dropkit.sh/docs), and every CLI command and API endpoint is catalogued in the [reference](https://dropkit.sh/docs/api). This README covers installing DROP, the trust model you should read before exposing it, and disaster recovery.

Also in this repo: HTTPS setup, git redeploy and custom domains, agent deploys.

Agents can deploy to DROP unaided with the deploy-to-drop skill (Claude Code, Cursor and any SKILL.md-compatible agent).

Requirements

Release install (recommended, Linux): a fresh Debian/Ubuntu box with root access. install.sh provisions Node.js, PostgreSQL, Caddy, and (if you choose --isolation=docker) Docker Engine for you — no toolchain to install yourself.

Build from source: Node.js 20+, npm 9+, and optionally Caddy 2.0+ for hostname routing.

Install

install.sh refuses to run piped straight from curl — it needs an on-disk copy of itself to work from — so save it first, then run it:

curl -fsSL https://github.com/JulesNsenda/drop/releases/latest/download/install.sh -o install.sh && sudo bash install.sh --from-release --isolation=docker

--from-release installs the latest published release: no git clone, and no TypeScript or Vite build on your machine. (Node.js is still required and the installer sets it up for you. npm may log a failed optional build for cpu-features — that is harmless; it is an optional native accelerator for ssh2 and the install completes without it.)

It requires you to pick an isolation mode explicitly on a first install:

• `--isolation=docker` (recommended) — tenant apps build and run in Docker containers with resource limits and no access to the platform's secrets.
• `--isolation=none` — tenant apps run as the drop system user, the same user that owns the platform's encryption key and JWT/OAuth secrets. Only choose this on a single machine where every deployer is fully trusted; see Security & Trust Model.

Add --domain=example.com --https --acme-email=you@example.com once DNS points at the box, or pin a specific version with --from-release=v1.0.0 instead of the latest.

Once the service is up, retrieve the one-time admin password from the platform log and change it immediately:

journalctl -u drop-platform -b --no-pager | grep -A1 'Default Admin Credentials'

Windows: install.sh targets systemd/apt Linux boxes. On Windows, run install.bat (or build from source) and start with drop serve directly — Windows is fully supported under isolation: none.

Verifying what you are about to run as root

install.sh verifies the downloaded tarball's SHA-256 checksum itself before installing anything. To also verify it was built by this repo's own GitHub Actions, check the build provenance attestation:

gh release download --repo JulesNsenda/drop -p drop-dist.tar.gz

gh attestation verify drop-dist.tar.gz --repo JulesNsenda/drop

Attestations are attached by the release workflow on every release built after this repository became public. If gh attestation verify reports no attestation for a given release, that release predates it — fall back to the published drop-dist.tar.gz.sha256, which install.sh checks automatically.

Every release also attaches drop-dist.tar.gz (compiled server, CLI and dashboard), its .sha256, and install.sh, so you can fetch and inspect them by hand on an air-gapped box. All releases are listed here.

Build from source

For contributors, or to run from a branch instead of a release:

git clone https://github.com/JulesNsenda/drop.git

cd drop npm install (cd src/dashboard && npm install) # the dashboard is a separate package npm run build # compiles the server AND builds the dashboard npm link # makes the 'drop' command available globally

If you only changed backend code, npm run build:server skips the dashboard build.

On first start, drop serve prints the one-time admin password to the console. Change it immediately.

Quick Start

drop serve                               # start the platform

cp -r my-app /var/drop/data/webapps/ # drop a folder in (Windows: xcopy to C:\drop\data\webapps\)

DROP detects the app type, installs dependencies, builds, provisions a PostgreSQL database if the app needs one, and starts it on an assigned port. Your app is then at http://localhost: , or at http://my-app.localhost with Caddy installed. Edit any file and it rebuilds and restarts.

The dashboard is at http://localhost:3000/dashboard — apps list, per-app start/stop/restart, secrets, custom domains, deploy history, logs, user management, and the Claude connector details.

For the CLI and REST API, see the reference. A running DROP redirects /dashboard/docs and /dashboard/reference there.

Security & Trust Model

Read this before exposing DROP to anyone you don't fully trust.

DROP ships two explicit isolation modes with different trust guarantees.

isolation: none (default) — single-user / trusted deployments

Deploying an app means running its code (install/build scripts and the app process) on the host as the DROP process user. A deployed app — or its build script — can read other apps' data and the platform's own files.

Use this when: it's your machine or a machine you control, and everyone with deploy access is trusted. Treat deploy access like shell access.

• Never enable allowSignup in this mode — DROP refuses at startup.
• Disable auth only on a trusted local machine (DROP_DISABLE_AUTH=true).
• Windows is fully supported in this mode.

isolation: docker — multi-user / invited users

Apps build and run in Docker containers with strict resource limits (--cap-drop=ALL, --security-opt no-new-privileges, memory/CPU caps, --pids-limit). Build containers have no access to platform secrets and cannot reach the LAN or cloud-metadata endpoints.

Honest residual risks (documented, not hidden):

• Shared kernel: containers are not VMs. A kernel exploit grants full host access. This is documented here, not mitigated.
• Egress: containers can reach the internet (package installs need it). Container→LAN/metadata is blocked; full egress policy is a future release.
• Shared-domain cookies: subdomains of one registrable domain share the same-site context. Apps at a.yourdomain.com and b.yourdomain.com can read each other's cookies. Use a dedicated baseDomain for multi-tenant use, or submit it to the Public Suffix List.
• Open signup (allowSignup: true) enables self-service registration. Abuse tooling, takedown runbooks, and egress enforcement for hostile public access are future work. Treat open-internet signup as documented residual risk until then.
• Deps must land in the app dir. Build and run happen in separate ephemeral containers sharing only the /app bind mount (no image commit), so only dependencies written *into the app dir* reach the runtime. Node (node_modules), Go (compiled binary) and Python (an /app-local .venv, whose bin/ is put on the runtime PATH) all land there. Anything a custom build command installs into system site-packages or a global prefix is discarded with the build container — the build "succeeds" and the app then fails to import at boot.

Requires Docker Engine on Linux (Docker Desktop on Windows/macOS is dev/best-effort only for this mode).

Build containers run as the platform's own (non-root) user so they can write the app source without needing CAP_DAC_OVERRIDE. Apps deployed through DROP (git deploy, webhook, drop deploy) are owned by that user automatically. If you instead place a folder into `data/webapps/` by hand, own it as the platform user (e.g. chown -R drop:drop) — a folder owned by a different user (a sudo cp as root) will fail the build with EACCES (fail-closed by design; DROP will not run an untrusted build as root to work around it).

What's hardened in both modes

• API auth (JWT + API keys), role tiers (readonly/user/admin)
• Rate limiting keyed on socket peer address (not spoofable x-forwarded-for)
• Path traversal and containment checks on all file I/O and deploy paths
• SSRF guard on webhook and git-clone URLs (private range + DNS-resolution check)
• Strict drop.yaml schema (unknown keys rejected; TLS paths confined to app dir)
• drop.yaml values never reach docker run args or mount specs directly
• Uploaded archives carrying .git metadata are refused outright
• Git credentials are passed to git through the environment, never written to .git/config or visible in ps
• Audit log for all deploy/build/start/secret/suspend operations
• Bundled PostgreSQL locked to scram-sha-256; unix socket restricted to peer auth

See .env.example for all security-relevant settings.

Backup & Restore

DROP keeps critical state in the file stores under data/drop-svc/ (credentials, encrypted secrets, the encryption key, webhooks, app state) and in PostgreSQL — both the internal drop_internal database and **every provisioned per-app d