Setup and resume

.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, and Niteshift starts them after setup succeeds. .niteshift/resume runs each time a suspended task resumes. 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.

.niteshift/setup

#!/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)
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 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 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 logs tab. A setup failure also surfaces inside the task, so the agent can read the log and diagnose it.

Start

Environment configuration

Platform

Interfaces

Customizing agents

The environment they run in

Environment variables

Environment cache

Support files

Logs

​The environment they run in

​Environment variables

​Environment cache

​Support files

​Logs

The environment they run in

Environment variables

Environment cache

Support files

Logs