Skip to Content
CLI Referencenkapp up

nkapp up

Full-stack orchestration: reconciles infrastructure and deploys services. Now supports targeted service management for faster iteration.

nkapp up [service] [options]

Options

FlagTypeDefaultDescription
-e, --env <env>stringlocalTarget environment
--env-file <path>string—Custom path to .env file
--override-envbooleanfalseOverride existing process.env variables with values from .env files
-y, --yesbooleanfalseSkip confirmation prompts
--persistbooleanfalseKeep SSH tunnels alive even if no service ports are forwarded
--detachbooleanfalseClose all tunnels and exit immediately after orchestration
--forcebooleanfalseForce execution of destructive actions (e.g. deleting databases/volumes)
-b, --branch <name>string—Explicitly work with a database branch (isolate data)

Safety Guardrails

nkapp up includes built-in protection against accidental data loss. If the reconciliation plan includes the deletion of databases or volumes, the command will fail unless the --force flag 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 entire project. However, you can target a specific service for faster iteration:

nkapp up docs -e local

Key Benefits:

  • Isolation: Only the target service is re-reconciled. Other running services are left untouched and will NOT be deleted or restarted.
  • Speed: Skips planning and orchestration phases for unrelated components.
  • Safety: Infrastructure (Gateway, DBs) is still ensured for the target service, but project-wide “orphan cleanup” is disabled.

Workflow

nkapp up executes a deterministic multi-stage pipeline:

1. Configuration Loading

Loads nanokit.yml, applies environment merges, resolves .env file hierarchy.

2. Secret Resolution

All vault:// and env:// references across the entire config tree are resolved via SecretsManager.resolveSecrets().

3. Infrastructure Planning

Compares the desired infrastructure state with the current provider state:

  • toCreate: New instances to provision
  • toDelete: Orphaned resources to remove

If changes are needed, a confirmation prompt is shown (unless -y is passed).

4. Code Sync (Remote Only)

For remote Docker providers with SSH, the project source is synchronized to the target host using the configured deploy.method (rsync or git).

5. Service Orchestration

The Reconciler deploys all services, handling container creation, networking, and Caddy gateway configuration.

6. Tunnel Persistence

For remote environments, Nanokit keeps the process alive to maintain SSH tunnels:

  • --persist: Force tunnel persistence even without active service ports
  • --detach: Skip persistence entirely, close tunnels and exit
  • Default: Auto-detect based on active service port forwarding

Examples

# Start local development
nkapp up -e local
 
# Deploy to staging with auto-confirm
nkapp up -e stage -y
 
# Use a custom .env file
nkapp up -e local --env-file .env.custom
 
# Deploy 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.

nkapp stopOverview