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

# Niteshift setup script

> A bash script that gives every task a working dev environment, ready for the agent.

`niteshift-setup.sh` is the script every task runs before the agent gets control. Same shape as the
bootstrap script your developers run after cloning the repository: install dependencies, bring up
backing services, run migrations, start the dev server.

The script pairs with two other per-repository settings:
[env vars](/environment-configuration/overview#environment-variables) feed configuration in, and
[preview ports](/environment-configuration/overview#preview-ports) expose the HTTP services it
starts. Together they make up the dev environment every task boots into.

## The environment it runs in

The script runs as root inside an Ubuntu 24.04 environment with developer tools already installed:

* Docker (daemon already running, see [Docker support](/environment-configuration/docker-support))
* Node.js 22, pnpm, npm
* Python 3, uv
* Go 1.24
* gh, AWS CLI, ripgrep, jq, build-essential, unzip

For anything not pre-baked, install it with `apt-get` or any other package manager.

```bash theme={"dark"}
apt-get update && apt-get install -y postgresql-client redis-tools
```

## What it typically does

A realistic Niteshift setup script installs dependencies, brings up backing services, runs
migrations, and starts the dev server:

```bash theme={"dark"}
#!/usr/bin/env bash
set -euo pipefail

pnpm install --frozen-lockfile

# Bring up backing services (Postgres, Redis, etc.)
docker compose up -d

pnpm db:migrate
pnpm db:seed

pnpm dev
```

The script lives at **Settings → Repositories → \[repository]**. Edit it inline, or let the
[setup agent](/environment-configuration/setup-agent) draft, edit, and verify it.

## Environment variables

`niteshift-setup.sh` reads env vars configured under **Settings → Repositories → \[repository]**, on
the **Setup Script** tab. They're sourced into the shell before the script runs, so the script and
anything it spawns (including the dev server) inherit them. Common entries: build credentials,
`DATABASE_URL`, package registry tokens.

The neighboring **Agent** tab is a separate scope for runtime secrets the agent needs, like API keys
and GitHub tokens. Those reach the agent and its bash terminal, not the setup script.

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

## Environment cache

Environment cache speeds up task provisioning by preserving installed dependencies and built
artifacts between tasks. Once the setup script finishes, Niteshift snapshots the disk and uses that
snapshot as the base state for the next task.

When a new task starts, the repo is pulled to its latest commits and the setup script runs again.
Because the cached dependencies and artifacts are already on disk, the script can reuse them instead
of redoing the work.

Environment cache is enabled by default, and Niteshift rebuilds it daily to keep dependencies fresh.
You can reset or disable it from the setup section of **Settings → Repositories → \[repository]**.

See [Docker support](/environment-configuration/docker-support#docker-image-caching) for what
Environment cache does and doesn't cover for Docker.

<Tip>
  When Niteshift is rebuilding the cache, the setup script runs with `NITESHIFT_LIFECYCLE_BUILD=1`
  set. Use it to skip task-specific steps (like seeding ephemeral data) that shouldn't bake into the
  cached snapshot.
</Tip>

<Tip>
  Environment cache speeds up the setup script. To skip the wait for a fresh environment entirely,
  Niteshift can configure a **warm pool** of pre-provisioned environments for your repository. Reach
  out to [support@niteshift.dev](mailto:support@niteshift.dev) if this would help your workflow.
</Tip>

## Provisioning and resume

Tasks [auto-suspend after inactivity and resume on demand](/tasks#lifecycle). When a task resumes,
Niteshift re-runs `niteshift-setup.sh` to bring the dev server and backing services back up. The
filesystem persists across suspend/resume, so dependencies and built artifacts are still on disk
when the script runs again.

Two env vars expose which phase the script is in:

* `NITESHIFT_LIFECYCLE_PROVISION=1` on the task's first start
* `NITESHIFT_LIFECYCLE_RESUME=1` on each resume after a suspend

Optionally use them to skip work that's already done on resume, like dependency installs and
migrations:

```bash theme={"dark"}
if [ -z "${NITESHIFT_LIFECYCLE_RESUME:-}" ]; then
  pnpm install --frozen-lockfile
  pnpm db:migrate
  pnpm db:seed
fi

# Backing services and the dev server start on every run
docker compose up -d
pnpm dev
```

The script's stdout and stderr stream into `$NITESHIFT_LOG_FILE`, the same log file the
[task workspace](/tasks) logs tab reads from. Anything you `echo` from the script lands there.