> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niteshift.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Services

> .niteshift/services.yaml declares the long-running processes Niteshift supervises: dev servers, databases, workers.

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

```yaml .niteshift/services.yaml theme={"dark"}
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](/environment-configuration/overview#previews-and-tunnels). |
| `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](/environment-configuration/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](/environment-configuration/overview#environment-variables) stored encrypted
  in Niteshift. The value is fetched each time the service starts, so rotations take effect on
  restart.

<Warning>Never put a secret value in `value` or `command`. Reference it with `secret`.</Warning>

## 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](/environment-configuration/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:

```bash theme={"dark"}
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.