Skip to main content

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.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
The script lives at Settings → Repositories → [repository]. Edit it inline, or let the 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.

​
Image caching

Image caching 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. Image caching is enabled by default, and Niteshift rebuilds the cache daily to keep dependencies fresh. You can reset or disable it from the setup section of Settings → Repositories → [repository]. See Docker support for what image caching 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.
Image caching 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 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: 
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 logs tab reads from. Anything you echo from the script lands there.