Skip to main content
Classic setup applies to environments configured before committed .niteshift/ configuration became the default. It keeps working; environment settings offers Migrate to Config v2, which starts a task that translates the existing setup into committed files and opens a PR.
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-environment 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.

​
Where it’s stored

By default, your setup configuration is stored in Niteshift. We generally recommend this so the setup agent can iterate on your configuration. However, if your repo has a niteshift-setup.sh stored at its root, Niteshift uses that instead. Once a niteshift-setup.sh is detected in your repo, the settings page exposes a toggle allowing you to swap between the version stored in Niteshift and your git-versioned niteshift-setup.sh.

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

​
What it typically does

A realistic Niteshift setup script installs dependencies, brings up backing services, runs migrations, and starts the dev server:
The script lives at Settings → Environments → [environment]. Edit it inline, or let the setup agent draft, edit, and verify it.

​
Environment variables

niteshift-setup.sh reads env vars configured under Settings → Environments → [environment], 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.

​
Preview ports and tunnels

You can open up to 5 HTTP ports. This commonly includes port 3000 (for web apps) along with any ports for services that need to be accessible by your web app (e.g. your API). Each port your Niteshift setup script binds gets a secure URL:
These URLs are scoped to your organization and require an authenticated Niteshift session to view. For non-HTTP services (Postgres, Redis, custom TCP protocols), configure a tunnel. Tunnels expose a port from the environment to a stable external address you can connect to from outside. Both are configured under Settings → Environments → [environment].

​
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 → Environments → [environment]. 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. 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:
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.