Skip to main content
Start with a working Engine installation. For a complete sample application, follow the quickstart.

​
Prepare the application

Nerdit detects Dockerfile, Python, Node.js and Next.js projects. A Dockerfile takes precedence. Node builds run the project’s build script when present and use the detected package manager and lockfile. Next.js server apps need build and start commands. For Python, set the actual command instead of relying on the default uvicorn main:app fallback.
nerdit.toml
This example requires your application to provide main:app, install Uvicorn, and implement /health. Bind to 0.0.0.0 inside the container. Use a stable DNS-label application name.
Containers drop Linux capabilities and use no-new-privileges by default. Images whose entrypoint needs chown, privilege changes, or privileged ports may fail. Build an image that works under these restrictions; do not disable the sandbox to make a stock image’s startup script work.

​
Preview and deploy

The dry-run validates configuration and shows planned changes without starting a build. Deployment uploads the folder, builds on the Engine, and starts a supervised service. Keep secrets out of the folder; upload exclusions are not a substitute for reviewing its contents. --wait exits 0 when the requested generation converges, 1 for failure or supersession, and 3 on timeout. A timeout alone does not mean the build failed:
Open the URL reported by the service. With the proxy disabled, that is a loopback address on the Engine machine. Enable HTTPS for routed URLs. Read the current endpoint after updates; health-gated cutover can change its effective host port.

​
Build presets and overrides

Engine 0.6.1 and later accept node, nextjs, python and dockerfile presets. Upgrade an older Engine if it reports unsupported build settings. Without a preset the Engine detects the runtime: a Dockerfile first, then Python markers, then package.json. A pyproject.toml that only carries tool configuration ([tool.ruff], [tool.black]) beside a package.json does not turn a Node app into a Python build.
Set install, build, start, node_version, package_manager or subdir in the same JSON object, or under [deploy.build_settings] in nerdit.toml. Use "build": false to skip compilation. Inspect the preview before deploying; it does not prove compilation or startup will succeed. Explicit overrides are saved for later deployments. Omitted fields keep saved choices; null clears an override and restores repository/default detection. For example, --build-settings '{"preset":null}' clears a saved preset. A Dockerfile always takes precedence. Commands appear in saved configuration, previews and generated images: never put credentials in them. Runtime environment settings are separate.

​
Public build variables

Compile-time frameworks (Vite, CRA, static Next.js) read their variables at build time. Declare them under [deploy.build_settings.public_env]; the Engine passes each one as a --build-arg:
nerdit.toml
These values are embedded in the browser assets you ship, so they are public by definition: a secret reference (${secrets.*} or ${github.*}) is refused with 422, never inlined, and the dry-run shows them in clear. Changing one needs a rebuild; a restart keeps the old bundle. Read deploy.build_settings.public_env in capabilities first — an Engine older than 0.6.2 refuses the field. Secret mounts at build time are not supported.

​
Deploy from Git or the store

Git runs on the Engine machine and must be installed there. Use an HTTPS repository on a host permitted by the Engine’s Git allowlist:
Replace the repository and branch with your own. Use --subdir when the deployable application lives in a subdirectory. For a private repository, pass a secret reference with --token-ref, never a credential embedded in the Git URL. A submitter token cannot write the shared scope, so on a private repository its error hint names the command the node owner runs (nerdit secrets set --shared --prompt GITHUB_TOKEN) and the reference to pass afterwards. Linked GitHub App deployment is an account integration; follow the App flow for its repository access.
Choose TEMPLATE_ID from the returned catalog and inspect its prerequisites before deploying it.

​
Update or roll back

For a folder deployment, repeat the folder command. For an application whose source is recorded as Git:
Folder and agent-workspace applications cannot use this Git-only redeploy operation. Upload the folder again or use the MCP workspace workflow. Roll back a folder application’s image to the retained previous version:
Nerdit retains recent image versions. A rollback does not restore application data or undo a database migration.

​
Understand cutover and migrations

When the proxy is available and the application uses no GPUs, eligible redeploys start a candidate container alongside the previous version and switch routing after readiness. A failed candidate leaves the previous version serving. Proxy-disabled, GPU, model, and database workloads do not use that same cutover path. Both application generations can touch the same persistent volumes during cutover. Make writes and schema changes compatible with that overlap. Set cutover = false under [deploy] if the application cannot tolerate it. An optional release command runs before promotion:
The image must contain the migration tool. Release commands run through a shell with the application’s environment and volumes. A nonzero exit blocks deployment, but changes already made to the database are not automatically undone. Design migrations to be repeatable, back up first, and investigate an interrupted migration before retrying. Removing the TOML line alone may retain the stored release command; clear it through configuration. Continue with service operations, models, and databases.