nkapp up

Reconcile the project's services, change-proportionally. up is the fast inner-loop command: it converges running containers onto what nanokit.yml declares, and does the minimum work the diff justifies.

nkapp up [service] [options]

up no longer provisions or syncs by default

up and deploy were split. By default nkapp up does not run the infrastructure plan/apply phase and does not sync your code to a remote host — nkapp deploy owns provisioning, host bootstrap and code sync.

Opt back in per-run with --infra / --sync, or restore the exact pre-split pipeline with --legacy (or NANOKIT_UP_LEGACY=1 for CI/scripts that cannot be edited).

Options

Flag	Type	Default	Description
-e, --env <env>	string	local	Target environment
--env-file <path>	string	—	Custom path for the base .env. The env overlay (.env.<env> / .env.local) still layers on top of it
--override-env	boolean	false	Let .env file values override variables already exported in the shell / injected by CI. Does not affect file-vs-file layering — .env.<env> always beats .env
-y, --yes	boolean	false	Skip confirmation prompts
--persist	boolean	false	Keep SSH tunnels alive even if no service ports are forwarded
--detach	boolean	false	Close all tunnels and exit immediately after orchestration
--force	boolean	false	Force execution of destructive actions (e.g. deleting databases/volumes)
-b, --branch <name>	string	—	Explicitly work with a database branch (isolate data)
--strict	boolean	false	Fail fast on the first service error instead of the default heal-and-continue reconcile
--reprovision	boolean	false	Force a full re-provision: recreate the service containers and re-run the dependency installs
--infra / --no-infra	boolean	skipped	Run / skip the infrastructure plan+apply phase
--sync / --no-sync	boolean	skipped	Run / skip the remote code sync
--legacy	boolean	false	Pre-split behavior — equivalent to --infra --sync (explicit --no-infra/--no-sync still win)

Environment variables:

Variable	Effect
NANOKIT_UP_LEGACY=1	Flag-less equivalent of --legacy
NANOKIT_NO_UP_SPLIT_NOTICE=1	Suppress the one-line split notice described below

---

Workflow

Default (nkapp up)

1. Configuration loading — parse nanokit.yml, merge the environment block, resolve the .env hierarchy.
2. Secret resolution — every vault:// and env:// reference across the config tree.
3. Service reconcile — scoped and change-proportional: containers, networking and the Caddy gateway are converged onto the declared state. Unchanged services are a no-op.
4. Tunnel handling — for remote environments, tunnels are kept alive or closed per --persist / --detach.

With --infra / --sync / --legacy

Two extra phases are inserted, in this order: the infrastructure plan + apply (with a confirmation prompt unless -y) after secret resolution, and the remote code sync before the service reconcile.

---

The split notice

On a run where the old default would have provisioned or synced — a remote environment with a deploy block, declared infra.instances, or a cloud provider — up prints a single line to stderr pointing at --infra / --sync / nkapp deploy / --legacy. It is informational and does not change the run. Suppress it with NANOKIT_NO_UP_SPLIT_NOTICE=1.

First-run guard

Against a never-provisioned remote Docker environment (zero Nanokit-labeled resources for the target env), up fails fast with a message telling you to run nkapp deploy to provision, or to pass --infra — instead of failing deep inside the reconcile. Local and cloud environments are exempt.

---

Safety guardrails

If the reconciliation plan includes the deletion of databases or volumes, the command fails unless --force is provided.

# This will fail if a database needs to be removed
nkapp up -e production

# Use --force to confirm destructive changes
nkapp up -e production --force

---

Targeted orchestration

By default nkapp up reconciles the whole project. Pass a name to target one service — the positional argument also accepts a database name.

nkapp up docs -e local

• Isolation: only the target is re-reconciled. Other running services are left untouched and are never deleted.
• Speed: unrelated components skip planning and orchestration entirely.
• Safety: infrastructure the target depends on (gateway, databases) is still ensured, but project-wide orphan cleanup is disabled.

---

--reprovision

Recreates the service containers and cache-busts the install sentinel in the persistent node_modules volume, so dependency installs run again. Use it after a corrupted install or when a dependency change was not picked up. It is one-shot: the next plain up is a normal no-op again.

nkapp up -e local --reprovision

---

Examples

# Start local development
nkapp up -e local

# Reconcile services on staging (no infra, no code sync)
nkapp up -e stage -y

# Provision infrastructure as well, for this run only
nkapp up -e stage --infra

# Exact pre-split pipeline (infra + remote code sync)
nkapp up -e stage --legacy

# Use a custom .env file
nkapp up -e local --env-file .env.custom

# Reconcile and exit immediately (CI/CD)
nkapp up -e stage -y --detach

TIP

After your first nkapp up -e local, run nkapp host trust to enable secure local HTTPS in your browser.

See also

• nkapp deploy — provisioning, code sync and remote deploys.
• nkapp plan — preview the reconcile without executing it.