> ## 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.

# Overview

> How Niteshift configures the cloud environment each task boots into: Niteshift setup script, env vars, preview ports, and tunnels.

Niteshift environments are composed of three primary components:

* **Niteshift setup script** ([`niteshift-setup.sh`](/environment-configuration/setup-script)): bash
  script that bootstraps your dev environment. Installs dependencies, runs migrations, and starts
  any services your dev environment needs.
* **Environment variables**: secrets and configuration injected into the environment, scoped to
  either the Niteshift setup script or the agent.
* **Preview ports & tunnels**: HTTP services exposed to a browser (preview ports) and non-HTTP
  services like databases (tunnels).

## Niteshift setup script

[`niteshift-setup.sh`](/environment-configuration/setup-script) runs at the start of every task,
before the agent gets control. It's the cloud equivalent of a fresh-clone bootstrap script your
developers run locally: `pnpm install && pnpm db:migrate && pnpm dev`. The
[setup agent](/environment-configuration/setup-agent) drafts and iterates on it for you, and you can
edit it inline from settings.

### Where it's stored

By default, your setup configuration is stored in Niteshift. We generally recommend this so the
setup agent can iterate on your configuration. However, if your repo has a `niteshift-setup.sh`
stored at its root, Niteshift uses that instead.

Once a `niteshift-setup.sh` is detected in your repo, the settings page exposes a toggle allowing
you to swap between the version stored in Niteshift and your git-versioned `niteshift-setup.sh`.

## Environment variables

Environment variables have two scopes:

* **Setup script** scope: available while `niteshift-setup.sh` runs (database URLs, build
  credentials, anything install steps need)
* **Agent** scope: available to the agent process and the dev server it spawns (API keys for runtime
  services, feature flags)

Values are encrypted at rest and never shown back in plaintext after save.

## Preview ports & tunnels

### Preview ports

You can open up to **5 HTTP ports**. This commonly includes port 3000 (for web apps) along with any
ports for services that need to be accessible by your web app (e.g. your API). Each port your
Niteshift setup script binds gets a secure URL:

```
https://ns-{port}-{previewId}.preview.niteshift.dev
```

These URLs are scoped to your organization and require an authenticated Niteshift session to view.

### Tunnels

For non-HTTP services (Postgres, Redis, custom TCP protocols), configure a **tunnel**. Tunnels
expose a port from the environment to a stable external address you can connect to from outside.

## Going deeper

* [Niteshift setup script](/environment-configuration/setup-script): what the script can do, the
  environment it runs in, environment cache, lifecycle env vars.
* [Setup agent](/environment-configuration/setup-agent): how the agent writes and iterates on
  `niteshift-setup.sh`.
* [Docker support](/environment-configuration/docker-support): Docker-in-Docker, Docker image
  caching, persistent storage options.
* [Database branches](/environment-configuration/database-branches): per-task isolated Postgres
  branches via Neon.