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

# Setup and resume

> Two committed scripts prepare the environment: .niteshift/setup on a fresh start, .niteshift/resume when a task wakes up.

`.niteshift/setup` runs automatically when Niteshift prepares a fresh environment. It owns work that
finishes: installing dependencies, building, running migrations, seeding data. Long-running
processes don't belong here; declare those in
[`services.yaml`](/environment-configuration/services), and Niteshift starts them after setup
succeeds.

`.niteshift/resume` runs each time a suspended task [resumes](/tasks#lifecycle). The filesystem
persists across suspend and resume, so dependencies, builds, and data are still in place; resume
holds only recovery for state that goes stale while suspended, like expired development credentials
or leftover lock files. Most repositories don't need one. Declared services restart automatically
after it runs.

Both are ordinary executables. Start each with a shebang; bash is typical, but any interpreter in
the environment works.

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

pnpm install --frozen-lockfile

# Start the declared database early so migrations can run. `ns services start`
# returns as soon as the process launches, so poll until Postgres accepts
# connections before migrating.
ns services start postgres
timeout 30 bash -c 'until docker compose exec postgres pg_isready --quiet; do sleep 1; done'

pnpm db:migrate
pnpm db:seed
```

A repository whose services need no preparation can carry only `services.yaml`.

## The environment they run in

Scripts run 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.

## Environment variables

Repository [environment variables](/environment-configuration/overview#environment-variables) in the
**Setup script** scope are sourced before the scripts run. Services don't inherit them; declare what
each service needs in the [manifest](/environment-configuration/services#environment).

## Environment cache

Once setup succeeds, Niteshift snapshots the environment and starts subsequent tasks from the
snapshot instead of rerunning setup. The cache rebuilds when the `.niteshift/` files change and
periodically to keep dependencies fresh. Reset or disable it from the **Environment cache** section
of **Settings → Repositories → \[repository]**.

## Support files

A helper another tool consumes directly, a script shared by setup and resume, or anything not
written in bash lives under `.niteshift/files/`, referenced by path from setup, resume, or a service
command.

## Logs

The scripts' stdout and stderr stream into the [task workspace](/tasks) logs tab. A setup failure
also surfaces inside the task, so the agent can read the log and diagnose it.