Cron Jobs

Nanokit provides a native, declarative way to schedule periodic tasks directly in your nanokit.yml. This system handles the orchestration of a sidecar scheduler and manages the execution of tasks across different environments.

Overview

Cron jobs are defined at the top level of your configuration. Each job specifies a schedule (crontab format) and a command to execute.


cron:
  daily-backup:
    schedule: "0 2 * * *"
    service: db
    command: "/scripts/backup.sh"

Configuration

Property	Type	Description
`schedule`	`string`	Required. Standard crontab expression (5 or 6 fields).
`service`	`string`	The service context to run the job in. Uses `job-exec` mode.
`image`	`string`	Explicit Docker image to use. Uses `job-run` mode.
`command`	`string`	Required. The command to execute.
`env`	`object`	Environment variables to inject into the job.
`enabled`	`boolean`	Whether the job is active. Defaults to `true`. Set to `false` (or toggle it off in the Hub) to keep the definition but skip scheduling.

Enable / disable without deleting: set enabled: false to pause a job while keeping its definition in nanokit.yml. You can also flip this from the Automation → Cron Jobs view in the Hub using the per-job switch — it writes the enabled flag back to your config and re-syncs the scheduler.


cron:
  nightly-report:
    schedule: "0 3 * * *"
    service: api
    command: "node ./scripts/report.js"
    enabled: false   # defined but paused

Execution Modes

Nanokit automatically chooses the best execution mode based on your configuration:

Integrated Mode (`job-exec`)

When you specify a service without an explicit image, Nanokit executes the command inside the already running container of that service.

Namespace: Runs within the service container (e.g., nk-project-local-hub).
Context: Inherits all environment variables, mounted volumes, and the current source code of the service.
Requirement: The target service must be running.

Standalone Mode (`job-run`)

When you specify an image (with or without a service), Nanokit creates a new ephemeral container for each execution.

Namespace: Containers are created with random names but include Nanokit labels for easy filtering.
Context: Completely isolated. You must specify all necessary environment variables or volumes manually.
Advantage: Runs independently of your other services’ status.

Scheduler Infrastructure

When you define at least one cron job, Nanokit automatically provisions a sidecar scheduler container:

Local/VPS: Uses an ofelia sidecar managed by the Docker provider.
Cloud: Integrates with native providers (e.g., AWS EventBridge).

The scheduler is automatically managed:

Created during nkapp up if jobs are present.
Updated if the schedules or commands change.
Pruned if all cron jobs are removed from your configuration.

Best Practices

Namespace Discovery: Even if standalone containers have random names, you can always find them using labels: docker ps --filter label=nk-kind=cron-job

Define your job

Add a cron block to your nanokit.yml. Use standard 5-field cron syntax; Nanokit will automatically handle the seconds field for you.

Verify locally

Run nkapp up -e local. Check the scheduler logs to confirm registration: docker logs nk-project-local-scheduler

Monitor in Hub

Open the Automation > Cron Jobs view in the Nanokit Hub to see a visual overview of your scheduled tasks and their status.