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 feed configuration in, and
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)
- 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.
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:
#!/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
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 for what
Environment cache does and doesn’t cover for Docker.
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.
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 if this would help your workflow. Provisioning and resume
Tasks auto-suspend after inactivity and resume on demand. 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 startNITESHIFT_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:
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
$NITESHIFT_LOG_FILE, the same log file the
task workspace logs tab reads from. Anything you echo from the script lands there.
