Services

.niteshift/services.yaml declares the long-running processes an environment needs. Niteshift supervises them: they start automatically after setup on every task, restart after a resume, and restart on failure.

.niteshift/services.yaml

services:
  - name: postgres
    command: docker compose up postgres
  - name: web
    command: pnpm dev
    cwd: apps/web
    port: 3000
    environment:
      - name: DATABASE_URL
        value: postgres://localhost:5432/app
      - name: STRIPE_KEY
        secret: STRIPE_KEY
  - name: storybook
    command: pnpm storybook
    port: 6006
    autostart: false
tunnels:
  - name: stripe-webhooks
    port: 3001

Fields

Key	Required	Meaning
`name`	yes	Service name.
`command`	yes	Bash command to supervise. Use `\|` for multiple lines.
`port`	no	Port the service listens on, exported as `$PORT`. A port publishes a preview URL.
`cwd`	no	Working directory, relative to the repository root.
`autostart`	no	Defaults to `true`. Set `false` for an on-demand service the agent starts when needed.
`restart`	no	`always` (default), `on-failure`, or `no`.
`stopGracePeriod`	no	How long the process gets to exit on its own before `SIGKILL`. Defaults to `10s`.
`environment`	no	Per-service environment entries, see below.
`auth`	no	How previews get an authenticated session, see Browser authentication.

The file is validated against a strict schema. Unknown keys and duplicate names are rejected, and validation errors name the offending entry.

Ports and previews

Each declared port publishes an authenticated preview URL, and the preview panel opens the first one, so put the primary UI first among services that declare ports. A few ports are reserved by environment infrastructure; validation names them if a service tries to claim one.

Environment

Services receive only what they declare, plus PORT and a small set of Niteshift-provided variables. Repository environment variables from settings are not inherited. Each entry sets a name and exactly one of:

value: a literal, for non-secret configuration.
secret: a reference to a repository environment variable stored encrypted in Niteshift. The value is fetched each time the service starts, so rotations take effect on restart.

Never put a secret value in value or command. Reference it with secret.

Preview authentication

For an app with a login, the service that serves it declares auth, so previews open already signed in. Three types:

magic-dev-login-url: the app serves a development-only login route that mints a session and redirects.
cookie-file: a command signs in without user interaction and writes browser state for Niteshift to inject.
recorded: Niteshift replays a session you record once by hand.

Prefer magic-dev-login-url or cookie-file; recorded is the last resort, since recorded sessions expire and need re-recording. At most one service declares auth. Browser authentication covers choosing between the types and recording sessions.

Tunnels

A tunnel exposes a port at a stable public URL with no Niteshift authentication, for external systems that must reach the environment, like webhook providers. The random URL acts as a credential: share it only with the intended integration, and keep tunnels off the port whose service declares auth.

Inside a task

The agent (and you, from the terminal tab) can inspect and drive services with the ns CLI:

ns services status          # setup result and every service's state
ns services logs web -n 100
ns services restart web

The agent can also supervise task-scoped services that aren’t in the manifest for one-off needs; only committed services come back after a resume.

Start

Environment configuration

Platform

Interfaces

Customizing agents

Fields

Ports and previews

Environment

Preview authentication

Tunnels

Inside a task

​Fields

​Ports and previews

​Environment

​Preview authentication

​Tunnels

​Inside a task

Fields

Ports and previews

Environment

Preview authentication

Tunnels

Inside a task