# Autofix Source: https://docs.niteshift.dev/autofix Automatically resolve CI failures and address PR review comments in the background. Autofix watches PRs you opened with Niteshift. When a CI check fails or a review comment lands, the agent runs in the background to address it. It pushes a fix to the PR branch, replies on threads it acted on, and resolves the ones it fixed. It keeps running until CI is green and the PR is ready to merge. ## When it activates Autofix runs when: * CI on your PR finishes with at least one failed check. Autofix waits for the full run to complete before acting. * A review comment is posted from a source Autofix is set to address. Bot comments are on by default; your own comments and other reviewers' comments are off by default (see [which comments it addresses](#which-comments-it-addresses)). * You (the PR author) post `/niteshift` on the PR. This kicks off Autofix on the task tracking the PR, or creates a new task with Autofix enabled if none is tracking it yet. Append a prompt to steer the run, e.g. `/niteshift focus on the failing snapshot tests`. While Autofix is working, a **Niteshift Fixes** check run appears on the PR and links to the task. Most code review bots (CodeRabbit, Cursor Bugbot, Codex Review, Claude Code Review) only post on ready PRs. To get Autofix iterating on bot feedback automatically, set your PR preference to **ready** instead of draft. ## Which comments it addresses Autofix decides whether to engage a review comment based on who left it. Each source has its own default, set under **Settings → Preferences**: * **Bot comments**: on by default. Actionable feedback (CodeRabbit, Cursor Bugbot, Codex Review, Claude Code Review) gets fixed; noise is ignored. * **Your own comments**: off by default. Turn this on to have Autofix act on comments you leave on your own PR. * **Other reviewers' comments**: off by default. Turn this on to have Autofix act on comments from teammates reviewing the PR. Failed CI checks are always addressed while Autofix is on, regardless of these settings. ## Where to turn it on Autofix can be turned on at three levels: * **Repository**: under **Settings → Preferences**. Applies to every PR you create with Niteshift in that repository. * **Per integration**: separate toggles for tasks created from Linear or Slack, in **Settings → Integrations**. * **Per task**: override the default for a single task, on the task page. ## Mentioning @niteshiftdev Mention `@niteshiftdev` in a comment on the PR, including an inline comment on a line of the diff, to have Niteshift address it, regardless of your comment-source settings. Text after the mention is passed to Niteshift as a prompt, e.g. `@niteshiftdev rewrite this using the existing helper`. Only the PR author can mention `@niteshiftdev`. # Automations Source: https://docs.niteshift.dev/automations Automations launch a Niteshift task on a schedule or when a webhook fires. Use webhooks to respond to alerts, address tickets, or react to deploys. Use schedules to run audits, triage dependencies, or send weekly reports. ## Examples * **Datadog alerts, root-caused in Slack** — when a Datadog monitor fires, the agent investigates with the Datadog MCP and posts the root cause back to the alert's Slack thread. * **Weekly flaky test fixes** — every Monday morning, the agent scans the last week of GitHub Actions runs for flaky tests and opens a PR with an attempted fix for each. * **Nightly bug hunt** — every night, the agent reads the last 24 hours of commits, flags the riskiest changes, and opens a PR with fixes for any bugs it finds. ## Scheduled tasks Use a schedule for recurring work like dependency bumps, periodic test runs, code-quality scans, or weekly maintenance passes. Configure: * **Environment**, **branch**, and **model** * **Schedule and task**: describe in plain language what the agent should do and when it should run. Niteshift parses it into a task prompt, cron expression, timezone, and a human-readable schedule label. ## Webhook triggers Use a webhook for event-driven work like CI failures, monitoring alerts, deploy notifications, or anything else that emits an HTTP webhook. Configure: * **Name**, **environment**, **branch**, and **model** * **Task prompt template**: the instructions the agent gets each time a request hits the URL. Use `{{payload.field}}` (dot paths into the JSON) or `{{payload_json}}` / `{{payload}}` to insert the full request body as pretty-printed JSON. ### Authentication Each trigger has a single shared secret. Incoming requests authenticate with one of: * **HMAC (preferred)**: send `x-niteshift-signature` and `x-niteshift-timestamp` headers. The signature is `sha256=` where the HMAC is computed over `.` using the trigger secret. Includes timestamp-based replay protection. * **Bearer token**: send `Authorization: Bearer `. Use this for sources like Datadog that can set static custom headers but can't compute a per-request signature. ### Rate limiting Each webhook URL is limited to **10 requests per rolling minute** and **100 per 24 hours**. The burst rule runs first; a request only counts toward the daily cap if it would have passed the burst check, so a flood of throttled calls does not use up the whole day. `429` responses: JSON with `error` and `retryAfter` (seconds), plus the `Retry-After` and `X-RateLimit-*` headers. Header values match whichever limit blocked you; `X-RateLimit-Reset` is a Unix time in **seconds** for the end of that limit's current window. # Browser automation Source: https://docs.niteshift.dev/browser-automation The agent drives a real Chromium against your preview, captures screenshots and demo videos, and posts them back to the PR. Every Niteshift environment runs a persistent Chromium browser. The agent uses it to verify changes, drive your app, and capture visual artifacts that get posted back to the PR. ## When the agent uses the browser The agent uses the browser automatically when you ask it to "use the browser", "verify the change works", "open the dashboard and check the new chart", or "reproduce issue #421". Explicitly, with a slash command: `/browser` If you'd like to encourage your agents to use the browser more often, or to consistently take screenshots, we recommend adding that to your environment instructions on the [settings page](https://niteshift.dev/settings). An example custom instruction to encourage maximum browser usage: ``` If a change is testable via a browser (e.g. a UI change to web app) you must use /browser /screenshots and /demo ``` ## Browser skills Niteshift exposes a few built-in skills that teach the agent how to use the browser. ### /browser The agent will use browser automation to visually verify UI changes, navigate through the relevant flow, and confirm the result works as expected. ### /screenshots The agent will take screenshots of its changes and add them to your PR description. ### /demo The agent will record a demo walkthrough of its changes and add them to your PR description. ### /browser-profiler The agent will use the Chrome profiler to measure your app's performance. # MCP Source: https://docs.niteshift.dev/customizing-agents/mcp Connect agents to external tools and services via the Model Context Protocol. MCP (Model Context Protocol) connects agents to services like Datadog, Linear, Slack, Notion, and Sentry. Configure MCP servers from **Settings → Environments → \[environment] → MCP Servers**. [Skills](/customizing-agents/skills) and [plugins](/customizing-agents/plugins) shape what the agent knows and how it behaves. MCP expands what the agent can reach. Niteshift also provides an [MCP Server](/interfaces/mcp-server) so you can kick off and orchestrate Niteshift tasks from external MCP enabled agents. ## How it works Add MCP servers from the catalog, or add a custom server by URL or local command. Each server is scoped in one of two ways: * **This environment**: shared with everyone using the environment. * **Just for you**: available only to tasks you start in that environment. Shared servers do not automatically share personal OAuth accounts. If a teammate uses a shared OAuth server, they connect their own account. API-key servers read secrets from the environment's **Agent** environment variables. The Connected section shows what is enabled for the environment and what is enabled for you. For shared servers, you can opt out for yourself; admins can also disable the shared default. Disabled servers are not included in the agent's MCP config for your tasks. ## Auth Remote MCP servers use one of three auth modes: * **OAuth**: connect your account through the provider's OAuth flow. For custom servers, this only works when the server supports [Dynamic Client Registration (DCR)](https://workos.com/blog/dynamic-client-registration-dcr-mcp-oauth). Niteshift stores the token for your user and refreshes it when the provider allows refresh. * **API key**: store the secret as an **Agent** environment variable. Niteshift passes it to the MCP server through headers such as `Authorization`. * **No auth**: no credentials are needed. Niteshift can detect this for custom remote servers that do not advertise OAuth metadata. Local `stdio` servers run inside the task environment and use a command, args, and optional env values instead of OAuth. ## Catalog The catalog has pre-built configs for common services. Search for a provider, choose a scope, and pick an auth method if the provider supports more than one. OAuth providers start the connect flow after you add them. API-key providers show the required **Agent** env vars and report `Missing keys` until those vars are saved. | Provider | What the agent can reach | | --------------------------- | -------------------------------------------- | | Amplitude | Events, users, cohorts | | Asana | Projects, tasks, workspaces | | Atlassian | Jira issues and Confluence pages | | Braintrust | Projects, experiments, evaluation logs | | Buildkite | Pipelines, builds, annotations | | Context7 | Up-to-date docs for libraries and frameworks | | Datadog | Metrics, APM, logs, monitors | | Granola | Meeting notes and decisions | | Hex | Notebooks, projects, data workspaces | | Hugging Face | Models, datasets, spaces | | LangSmith | LLM traces, datasets, evaluations | | LaunchDarkly | Feature flags, experiments, AI configs | | Linear | Issues, projects, cycles, and comments | | Neon | Postgres branches, databases, queries | | Notion | Pages, databases, and comments | | PlanetScale | Databases, branches, schema, insights | | Postman | Collections, tests, mocks, API specs | | PostHog | Events, funnels, feature flags | | Render | Deployments, services, logs | | Sanity | Content, schemas, datasets | | Sentry | Errors, performance, and releases | | Slack | Messages, channels, canvases | | Sourcegraph | Code search across repositories | | Stripe | Payments, customers, subscriptions | | Supabase | Postgres, auth, storage | | Webflow | CMS, sites, asset management | **Coming soon**:
Figma Vercel
## Custom servers Use **Add custom server** when the catalog does not include the service you need. * **No auth**: select `http` or `sse`, enter the URL, and leave headers blank. If the server does not advertise OAuth metadata, Niteshift marks it `No auth`. * **OAuth**: select `http` or `sse`, enter the URL, and leave headers blank. If the server advertises OAuth metadata and supports DCR, Niteshift redirects you to authorize the connection. * **API key**: add the secret as an **Agent** env var, then reference it in headers with `${ENV_VAR}`. ```txt theme={"dark"} Authorization=Bearer ${ACME_MCP_TOKEN} X-Workspace=${ACME_WORKSPACE_ID} ``` For a local MCP server, choose `stdio` and provide the command, args, and optional env values. Make sure your setup script installs any package or binary the command needs. ## Config preview Niteshift writes the right config format for each agent: JSON for Claude Code and TOML for Codex. The settings page includes a read-only raw config preview so you can inspect what each agent will receive. # Plugins Source: https://docs.niteshift.dev/customizing-agents/plugins Install Claude Code plugins per environment, from marketplaces or git repos. Plugins are supported for Claude Code. For other model providers, contact [support@niteshift.dev](mailto:support@niteshift.dev). Plugins ship [skills](/customizing-agents/skills), slash commands, and other agent extensions to your environment's tasks without committing them to a repository. Niteshift uses [Claude Code's plugin model](https://code.claude.com/docs/en/plugins) directly, so the same configuration works locally and in tasks. ## How they work A plugin lives inside a **marketplace**: a git repo with a `.claude-plugin/marketplace.json` manifest listing one or more plugins. Configure two things per environment at **Settings → Environments → \[environment] → Plugins**: * **Marketplaces**: where plugins come from. Add a GitHub shorthand (`owner/repo`, `owner/repo@ref`) or a full git URL. * **Enabled plugins**: which plugins to install, identified as `plugin-name@marketplace-name`. The marketplace name comes from the manifest's `name` field. Niteshift pre-installs the resolved plugins to your environment so they're available to the agent on task start. We automatically add the `claude-plugins-official` marketplace, but you should add any others. ## Importing from `.claude/settings.json` If you already have plugins configured locally in Claude Code, drag your `.claude/settings.json` into the Plugins panel. Niteshift imports [`extraKnownMarketplaces` and `enabledPlugins`](https://code.claude.com/docs/en/settings#plugin-settings) directly, so the same config travels without translation. # Skills Source: https://docs.niteshift.dev/customizing-agents/skills Skills work natively in Niteshift Niteshift agents auto-load skills committed to your repositories, so you can codify domain knowledge, custom workflows, and slash commands per project. Every task that checks out a repository gets its skills. ## How they work Skills are the open [Agent Skills](https://agentskills.io) standard. Niteshift runs Claude Code or Codex inside the task environment, and both agents honor that standard natively. A skill is a subdirectory containing a `SKILL.md` file with frontmatter (`name`, `description`) and instructions. Commit them under the directory the agent expects: | Agent | Directory | | ----------- | ----------------- | | Claude Code | `.claude/skills/` | | Codex | `.codex/skills/` | ``` .claude/skills/ deploy/ SKILL.md test-e2e/ SKILL.md ``` The `name` becomes a slash command. The prefix differs: in Claude Code it's `/deploy`; in Codex it's `/prompts:deploy`. The `description` is what the agent reads to decide when to apply the skill on its own, so write it for an agent deciding "is this relevant to what I'm being asked?", not for a human browsing a list. ## What skills are good for * Domain-specific instructions: "when touching the billing service, always run `pnpm vitest run apps/web/src/billing` first." * Reusable workflows: `/deploy` codifies the steps for cutting a release. * Integration cheat sheets: how to query your internal API, where the staging credentials live, which feature flags gate what. ## Example ```markdown SKILL.md theme={"dark"} --- name: deploy description: Cut a release. Use when the user says "deploy", "ship", or "cut a release". --- 1. Verify `main` is green: `gh run list --branch main --limit 1`. 2. Bump the version in `package.json`. 3. Tag the commit: `git tag v$(jq -r .version package.json)`. 4. Push the tag: `git push origin --tags`. 5. The release workflow handles the rest. ``` A teammate later running `/deploy` in a Niteshift task gets the same procedure. ## Pair with your environment setup Skills handle agent behavior; they don't provision infrastructure. If your skill assumes a tool is installed or an env var is set, make sure your [environment setup](/environment-configuration/overview) puts it there. # Browser authentication Source: https://docs.niteshift.dev/environment-configuration/browser-authentication Configure how the agent and your previews authenticate into your application. The agent's browser and your preview links share a single authentication session per task, so an app with a login opens already signed in instead of on a login wall. The service that serves the login declares an `auth` block in [`services.yaml`](/environment-configuration/services#preview-authentication). Three types, by where the session comes from: * **`magic-dev-login-url`**: the app serves a development-only login route that authenticates a seeded user, sets the session cookie, and redirects. The best fit when such a route exists: Niteshift stores no auth state, and every visit gets a fresh session. * **`cookie-file`**: a command signs in without user interaction (a seeded user, a CLI, an API) and writes browser state that Niteshift injects into the agent's browser and syncs to preview viewers. * **`recorded`**: Niteshift replays a session you record once by hand, from the **Recorded sessions** section of **Settings → Environments → \[environment]**. Prefer `magic-dev-login-url` or `cookie-file`: they mint sessions automatically, without your involvement. Use `recorded` only when nothing can sign in on its own (SSO, 2FA, CAPTCHA); recorded sessions expire and pull you back in to re-record. The agent picks and wires a type during setup. To change it, ask the agent in any task: agents know how to edit `.niteshift/` configuration and open a PR with the change. [Classic environments](/environment-configuration/setup-script) configure this in Niteshift settings instead: see [Preview authentication (classic)](/environment-configuration/classic-preview-auth). ## Recording a session The recording flow uses a real task to capture real cookies. There's no separate "recording mode". Set `auth.type: recorded` on the service in `services.yaml`, then open the **Recorded sessions** section of **Settings → Environments → \[environment]**. Niteshift starts a short-lived task that boots an environment and opens the browser at your app. The task pauses and surfaces a **Control Browser** prompt. Take over the browser tab and log in the way a user would: SSO, 2FA, anything. The agent waits. Once you're logged in and on a page that proves it, click **Save**. Niteshift exports cookies and localStorage, encrypts them, and stores them scoped to that environment and to your user. Every future task on that environment, started by you, boots with the recorded session pre-loaded. Recordings are per-user. Each developer records once per environment they work on. ## Debugging login issues Most preview-auth failures share a root cause: when your app needs to authenticate, it sends the user to a hosted sign-in page (AuthKit, Clerk, Okta) that refuses to render inside an iframe. The preview blanks out or breaks. For the stored-state types (`cookie-file` and `recorded`), Niteshift sidesteps this by issuing a bootstrap request to the preview domain to plant cookies, then loading your application. Because the session is already in place, your app doesn't redirect to a hosted sign-in and the iframe-bust never triggers. Without authentication configured, apps that redirect to a login on mount or require a "Sign in with X" click will fail to load in the preview. If previews still fail to authenticate, ask the agent in a task to configure authentication for your previews. It can debug cookie shape, redirect behavior, or bootstrap config. Still stuck? Reach out at [support@niteshift.dev](mailto:support@niteshift.dev). # Preview authentication Source: https://docs.niteshift.dev/environment-configuration/classic-preview-auth How classic environments seed the browser session for the agent and previews. This page covers environments on the [classic setup script](/environment-configuration/setup-script). Environments with committed `.niteshift/` configuration declare auth in the service manifest: see [Browser authentication](/environment-configuration/browser-authentication). Configure how the agent's browser and your preview links authenticate at **Settings → Environments → \[environment] → Preview Authentication**. Four strategies: * **No auth**: previews show the unauthenticated view. No credentials are stored or injected. * **Use static cookies across all tasks**: record a session once (or paste cookies in by hand) and Niteshift injects them into every task's browser and preview links. Best for hosted auth providers (AuthKit, Clerk, Okta) and persistent backing services (Neon, Supabase). * **Per-task login**: your setup script writes cookies to `/tmp/agent-browser-state.json`, and Niteshift syncs that file to the agent's browser on launch and to preview links so you see the same authenticated session the agent does. Best for per-task seeded users or short-lived sessions. Use **Edit with agent** to have the setup agent draft the seeding code for you. * **Manual login (username & password)**: add [custom instructions](https://niteshift.dev/settings) with test credentials (e.g. `user@example.com` / `test123`) and the login flow. The agent drives the login itself each task, and you can also log in manually on previews. ## Recording a session Select **Use static cookies across all tasks**, click **Save**, then click **Record session**. From there the flow is the [same as for `.niteshift/` environments](/environment-configuration/browser-authentication#recording-a-session): a short-lived task boots an environment and opens the browser at your app, you take over via **Control Browser** and log in, and **Save** stores the encrypted session scoped to the environment and your user. ## Debugging login issues Login failures share the [same causes and fixes](/environment-configuration/browser-authentication#debugging-login-issues) as `.niteshift/` environments. The cookie strategies (**Use static cookies across all tasks** and **Per-task login**) plant cookies before loading your application, so hosted sign-in pages that refuse to render in an iframe never trigger; with **No auth**, apps that redirect to a login on mount will fail to load in the preview. # Database branches Source: https://docs.niteshift.dev/environment-configuration/database-branches Connect Neon and every Niteshift task gets its own isolated Postgres branch, with the connection string injected as an env var. When Neon is connected to an environment, every task gets its own Postgres branch forked from a base branch you pick. The agent can run migrations, seed data, and exercise destructive queries without touching shared environments. ## Setup Open **Settings → Environments → \[environment] → Database**. Paste a project-scoped Neon API key (starts with `napi_`), verify it, then configure: * **Parent branch**: the Neon branch new task branches fork from. Defaults to your project's primary branch (typically `main`). * **Environment variable**: name of the env var the connection string is injected as. Defaults to `DATABASE_URL`. * **TTL (days)**: how long Neon keeps the branch around. Default 30. * **Delete on task archival**: drop the branch when the task is archived (e.g. after PR merge). Default on. ## Branch lifecycle When a task starts, Niteshift creates a fresh Neon branch forked from the parent branch and injects the connection string into the environment under your chosen variable name. Your [setup](/environment-configuration/setup-and-resume) can read the connection string and run migrations against the new branch before the agent starts work: ```bash theme={"dark"} pnpm db:migrate pnpm db:seed ``` Resumed tasks reuse the same branch they had before, so state survives across pause-resume. Branches are deleted when the task is archived (if enabled) or when the TTL expires. If a long-running task outlives its branch's TTL, the next run forks a new branch from the parent. Raise the TTL if you need the same branch to persist longer. # Docker support Source: https://docs.niteshift.dev/environment-configuration/docker-support Docker-in-Docker is supported. The daemon runs by default, so the setup script and agent can use docker directly. Niteshift environments ship with a Docker daemon already running. Your setup script and the agent can run `docker`, `docker compose`, and Dockerfile builds directly. Don't start `dockerd` yourself; a second daemon will fail with socket conflicts. ## Constraints ### Ephemeral state By default, Docker's data directory (`/var/lib/docker`) lives on tmpfs. Volumes, pulled images, and stopped containers do **not** survive across the [task lifecycle](/tasks#lifecycle) (suspend and resume). Each resume starts from a fresh Docker state and re-pulls images on demand. Persisting Docker state across the task lifecycle is possible, but comes with performance trade-offs, so it's opt-in. Email [support@niteshift.dev](mailto:support@niteshift.dev) to enable it. ### Networking Docker runs with `--iptables=false`, so containers should use host networking to communicate with each other and reach the internet. Run containers with `--network=host` (or `network_mode: host` in compose). Services then talk to each other via `localhost:` and have normal outbound access. The agent that writes your [environment setup](/environment-configuration/overview) applies this automatically when adapting an existing compose file during onboarding. # Multi-repository environments Source: https://docs.niteshift.dev/environment-configuration/multi-repo An environment can include multiple repositories, so tasks can change code and run services across your whole stack. A Niteshift environment can run your full stack, even when it spans several repositories. Tasks in that environment can change code in any of them and open pull requests against each one. ## Environments and repositories An environment defines where Niteshift tasks run. A repository is one source of code available inside that environment. For example, an environment might include these repositories: * `frontend` * `backend` * `infra` The environment configuration lives in one of those repositories. It could live in `frontend` while still telling Niteshift to include the other two. The repository that stores the configuration does not limit what tasks can work on. Once the repositories are part of the environment, tasks can make changes and open pull requests across any of them. ## Adding another repository You do not need to edit the configuration by hand. Start a task in the environment and ask the agent to add the repository. For example: > Add the `backend` repository to this environment and set up the backend services so the frontend > can run against them. The agent checks the repository out into the current task, records it in `.niteshift/settings.yaml`, and opens a pull request with the change. After you merge the PR, future tasks in the environment start with both repositories. ## Changing the agent's working directory By default the agent starts in the repository that holds the environment configuration. You can ask the agent to change the agent's working directory. It will edit `settings.yaml` and it will take effect for future tasks after you merge it. ## Naming an environment By default an environment is named after the repository that holds its configuration. Give it a more descriptive name, like "full stack", in **Settings → Environments → \[environment]**. # Overview Source: https://docs.niteshift.dev/environment-configuration/overview Niteshift environments are described by files committed under .niteshift/: setup, resume, services, settings, and instructions. A Niteshift environment is described by files committed to your repository under `.niteshift/`. When a task starts, Niteshift checks out your repository and any other repositories it needs. Then it runs your setup and brings up your declared services automatically. The `.niteshift` directory may contain these files: * [`.niteshift/setup`](/environment-configuration/setup-and-resume): finite work for a fresh environment. Installs, builds, migrations, seeds. * [`.niteshift/resume`](/environment-configuration/setup-and-resume): recovery work that runs each time a suspended task resumes. * [`.niteshift/services.yaml`](/environment-configuration/services): the long-running processes Niteshift supervises. Dev servers, databases, workers. Ports declared here become [preview URLs](#previews-and-tunnels). * `.niteshift/instructions.md`: custom instructions added to every task's system prompt on this repository. * `.niteshift/settings.yaml`: [additional repositories](/environment-configuration/multi-repo) and other settings. The `settings.yaml` file is the only required file, though it only needs to contain a `version: 1` entry to be valid. The agent may add additional helpers as needed (scripts, container definitions) under `.niteshift/files/`. ## Configuring an environment You don't write these files by hand. From **Settings → Environments → \[environment]**, click **Set up with agent**. A task works out how to install, run, and verify your project. It tests the setup and then opens a PR committing the .niteshift/ files. Nothing changes for other tasks until you merge it. To change the configuration later, ask the agent in any task: agents know how to edit and verify `.niteshift/` files, and the change arrives as a PR. The settings section also shows the committed files on any branch, with two shortcuts: * **Edit with agent** starts a task pre-prompted to change the configuration. * **Test in a sandbox** provisions an environment from the selected branch and reports whether its committed configuration boots cleanly, so you can validate a configuration PR before merging it. ## Environment variables Secrets stay out of the repository. Configure them at **Settings → Environments → \[environment]**, in two scopes: * **Setup script** scope: sourced while `.niteshift/setup` and `.niteshift/resume` run. * **Agent** scope: available to the agent process and its terminal. Services receive only what their manifest declares: reference a stored variable by name with a `secret` entry in [`services.yaml`](/environment-configuration/services#environment). Values are encrypted at rest and never shown back in plaintext after save. ## Previews and tunnels Each service that declares a `port` gets a secure URL: ``` https://ns-{port}-{previewId}.preview.niteshift.dev ``` These URLs are scoped to your organization and require an authenticated Niteshift session to view. The preview panel opens the first declared port. For an endpoint an external system must reach without Niteshift authentication (a webhook provider, for example), declare a [tunnel](/environment-configuration/services#tunnels). ## Classic setup Environments configured before `.niteshift/` became the default use the [classic Niteshift setup script](/environment-configuration/setup-script): a single `niteshift-setup.sh` stored in Niteshift settings. It keeps working, and nothing forces a migration. For classic environments, settings shows a **Migrate to Config v2** action that starts a task to translate the existing setup into committed `.niteshift/` files and open a PR; the environment switches over once a `.niteshift/` directory lands on the default branch. ## Going deeper * [Setup and resume](/environment-configuration/setup-and-resume): the lifecycle scripts, the toolchain they run in, environment cache. * [Services](/environment-configuration/services): the manifest format, ports, per-service environment, tunnels. * [Browser authentication](/environment-configuration/browser-authentication): how the agent and previews authenticate into your app. * [Docker support](/environment-configuration/docker-support): Docker-in-Docker, image caching. * [Database branches](/environment-configuration/database-branches): per-task isolated Postgres branches via Neon. # Services Source: https://docs.niteshift.dev/environment-configuration/services .niteshift/services.yaml declares the long-running processes Niteshift supervises: dev servers, databases, workers. `.niteshift/services.yaml` declares the long-running processes an environment needs. Niteshift supervises them: they start automatically after [setup](/environment-configuration/setup-and-resume) on every task, restart after a resume, and restart on failure. ```yaml .niteshift/services.yaml theme={"dark"} services: - name: postgres command: docker compose up postgres - name: web command: pnpm dev cwd: apps/web port: 3000 environment: - name: DATABASE_URL value: postgres://localhost:5432/app - name: STRIPE_KEY secret: STRIPE_KEY - name: storybook command: pnpm storybook port: 6006 autostart: false tunnels: - name: stripe-webhooks port: 3001 ``` ## Fields | Key | Required | Meaning | | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | yes | Service name. | | `command` | yes | Bash command to supervise. Use `\|` for multiple lines. | | `port` | no | Port the service listens on, exported as `$PORT`. A port publishes a [preview URL](/environment-configuration/overview#previews-and-tunnels). | | `cwd` | no | Working directory, relative to the root of the repository that contains the environment settings. | | `autostart` | no | Defaults to `true`. Set `false` for an on-demand service the agent starts when needed. | | `restart` | no | `always` (default), `on-failure`, or `no`. | | `stopGracePeriod` | no | How long the process gets to exit on its own before `SIGKILL`. Defaults to `10s`. | | `environment` | no | Per-service environment entries, see below. | | `auth` | no | How previews get an authenticated session, see [Browser authentication](/environment-configuration/browser-authentication). | The file is validated against a strict schema. Unknown keys and duplicate names are rejected, and validation errors name the offending entry. ## Ports and previews Each declared `port` publishes an authenticated preview URL, and the preview panel opens the first one, so put the primary UI first among services that declare ports. A few ports are reserved by environment infrastructure; validation names them if a service tries to claim one. ## Environment Services receive only what they declare, plus `PORT` and a small set of Niteshift-provided variables. Environment variables from settings are not inherited. Each entry sets a `name` and exactly one of: * `value`: a literal, for non-secret configuration. * `secret`: a reference to an [environment variable](/environment-configuration/overview#environment-variables) stored encrypted in Niteshift. The value is fetched each time the service starts, so rotations take effect on restart. Never put a secret value in `value` or `command`. Reference it with `secret`. ## Preview authentication For an app with a login, the service that serves it declares `auth`, so previews open already signed in. Three types: * `magic-dev-login-url`: the app serves a development-only login route that mints a session and redirects. * `cookie-file`: a command signs in without user interaction and writes browser state for Niteshift to inject. * `recorded`: Niteshift replays a session you record once by hand. Prefer `magic-dev-login-url` or `cookie-file`; `recorded` is the last resort, since recorded sessions expire and need re-recording. At most one service declares `auth`. [Browser authentication](/environment-configuration/browser-authentication) covers choosing between the types and recording sessions. ## Tunnels A tunnel exposes a port at a stable public URL with no Niteshift authentication, for external systems that must reach the environment, like webhook providers. The random URL acts as a credential: share it only with the intended integration, and keep tunnels off the port whose service declares `auth`. ## Inside a task The agent (and you, from the terminal tab) can inspect and drive services with the `ns` CLI: ```bash theme={"dark"} ns services status # setup result and every service's state ns services logs web -n 100 ns services restart web ns services restart web --env PILOT_FEATURE_OVERRIDES=desk ``` `restart --env NAME=VALUE` temporarily overrides a manifest service for the current task without editing `services.yaml`. Other declared environment entries, including secrets, remain available; the next start, ordinary restart, or manifest reconciliation restores the declared values. The agent can also supervise task-scoped services that aren't in the manifest for one-off needs; only committed services come back after a resume. # Setup agent Source: https://docs.niteshift.dev/environment-configuration/setup-agent An AI agent interviews your repository, writes niteshift-setup.sh, and verifies the environment boots. The setup agent maintains the [classic setup script](/environment-configuration/setup-script). On committed [`.niteshift/` configuration](/environment-configuration/overview) there is no separate setup agent: ask the agent in any task to change the configuration, or use the **Set up with agent** and **Edit with agent** shortcuts in environment settings. Either way the change arrives as a PR against the committed files. The setup agent writes your [`niteshift-setup.sh`](/environment-configuration/setup-script) for you. It reads your code, asks what it can't infer, and produces the script that every task on the environment will run. ## Two modes **Initial setup** starts from scratch. The agent inspects your codebase to infer framework, package manager, dev server command, and ports, then asks targeted questions about anything ambiguous: which env vars to populate, which port is the primary preview, whether to seed test users. It produces a working Niteshift setup script and verifies the dev server boots. You can rerun initial setup at any time from the environment settings page. **Edit with agent** iterates on your existing setup. From **Settings → Environments → \[environment]**, click **Edit with agent** to start a new run; the setup agent loads your existing [`niteshift-setup.sh`](/environment-configuration/setup-script) and prior conversation as context. ### Iterating on your setup After kicking off a session via **Edit with agent** you can prompt the agent to iterate on your setup. This can include anything required for your dev environment: * installing dependencies, starting a new service, and exposing its ports * setting up seed data for your application * configuring authentication for the agent and/or previews * installing custom devtools you want available to the agent ## Editing without the agent You don't have to use the agent for every change. The setup section has an inline editor. Click **Edit** to modify the script directly, save, and the next task will use the new version. The same editor handles env vars and preview ports. # Setup and resume Source: https://docs.niteshift.dev/environment-configuration/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 environments 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 ``` An environment 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 [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 → Environments → \[environment]**. ## 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. # Niteshift setup script Source: https://docs.niteshift.dev/environment-configuration/setup-script A bash script that gives every task a working dev environment, ready for the agent. Classic setup applies to environments configured before committed [`.niteshift/` configuration](/environment-configuration/overview) 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](#environment-variables) feed configuration in, and [preview ports](#preview-ports-and-tunnels) 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](/environment-configuration/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](/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. ```bash theme={"dark"} 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: ```bash theme={"dark"} #!/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 → Environments → \[environment]**. Edit it inline, or let the [setup agent](/environment-configuration/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: ``` https://ns-{port}-{previewId}.preview.niteshift.dev ``` 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](/environment-configuration/docker-support#docker-image-caching) 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](mailto:support@niteshift.dev) if this would help your workflow. ## Provisioning and resume Tasks [auto-suspend after inactivity and resume on demand](/tasks#lifecycle). 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: ```bash theme={"dark"} 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](/tasks) logs tab reads from. Anything you `echo` from the script lands there. # GitHub Source: https://docs.niteshift.dev/interfaces/github Trigger and observe Niteshift tasks from pull requests, with check runs and PR comments wired to your repository. GitHub is Niteshift's primary surface. The Niteshift GitHub App grants repository access and lets you trigger tasks from PR comments, with results posted back as check runs and comments on the PR. ## Setup From the setup page (or [niteshift.dev](https://niteshift.dev) on first sign-in), install the Niteshift GitHub App on your account or organization. Pick **All repositories** or select specific ones. Niteshift only sees repositories you grant. Open your GitHub organization settings to add or remove repositories at any time. The Niteshift dashboard reflects the new list immediately. ## How to use Comment `/niteshift` on any pull request you authored to start a task scoped to that PR. Only the PR author can trigger `/niteshift` commands. ``` /niteshift fix the failing tests ``` Niteshift checks out the PR branch and uses it for any commits the agent pushes; tasks don't open a new branch. The prompt includes the PR title, body, and diff, and [autofix](/autofix) activates automatically so the agent addresses CI failures and review comments as part of its work. A bare `/niteshift` with no prompt runs autofix against the PR's current state. If a task is already running on the PR, a second `/niteshift` routes to the same task: your prompt becomes a follow-up message, or a bare `/niteshift` re-triggers autofix. See [Autofix](/autofix) for how Niteshift iterates on CI failures and review comments automatically. ## Issues Comment `/niteshift` (or `@niteshiftdev`) on a GitHub issue to start a task from it. Any organization member can trigger from an issue — there is no author restriction. ``` /niteshift add a retry with backoff here ``` The task starts on the repository's default branch with the issue title, description, and your comment as its prompt; a bare `/niteshift` asks the agent to resolve the issue as written. The agent answers questions as a comment on the issue and opens a pull request that references the issue when it finishes. Later `/niteshift` or `@niteshiftdev` comments on the same issue route to the running task as follow-up messages (`/niteshift:new` forces a fresh task instead). Once the pull request exists, PR comments reach the same task too. ## What you receive The trigger comment gets reactions as the task progresses: * 👀: command detected * 🚀: task started * 👎: failed to start Niteshift then posts: * A reply comment with a link to the task workspace * A check run named **Niteshift Fixes** with results * Commits pushed back to the PR branch when the agent finishes Niteshift uses a stop hook that asks the agent to commit changes when it finishes. PRs respect your repository's PR preference (defaults to draft). If you want code review bots like CodeRabbit, Cursor Bugbot, Codex Review, or Claude Code Review to fire on every push so [autofix](/autofix) can iterate on their feedback, switch the preference to **ready**. Most of these bots skip drafts. You can opt into auto-archiving the task when the PR closes from your user preferences. It's off by default. # Linear Source: https://docs.niteshift.dev/interfaces/linear Link Linear issues to Niteshift tasks for automatic status transitions, progress comments, and PR attachments. Link Linear issues to Niteshift tasks for automated progress updates, PR attachment, and status transitions on the issue. ## Setup Open **Settings → Integrations → Linear** and click **Connect**. The OAuth flow links your Linear workspace to Niteshift. Pick which Linear teams should have Niteshift available. Issues in other teams are ignored. Each user sets a default environment for Linear-triggered tasks under the same settings panel. Without it, assignment-triggered tasks fail with a prompt to configure one. ## How to use Two paths trigger a Niteshift task from Linear: **Assign a Linear issue to Niteshift.** Niteshift creates a task in your default environment. The issue title, description, recent comments, and up to 5 images are passed in the agent prompt. If the agent needs more context (sub-issues, parent issues, additional comments or images, related tickets, etc.), configure the [Linear MCP server](/customizing-agents/mcp). **Tag `@Niteshift` in a Linear comment.** Use this when you want to add a specific instruction beyond what's already in the ticket. The comment body becomes the prompt; the rest of the issue context loads the same way as an assignment. Follow-up prompts in Linear work until a prompt arrives from another source (web UI, GitHub) — after that, send follow-ups from the web UI. ## What you receive When a task is linked to an issue, Niteshift: * Moves the issue to **In Progress** when the task starts * Moves it to **In Review** when the task completes * Posts agent thoughts, summaries, and PR links as Linear comments * Attaches the pull request to the issue Image attachments in the issue description and recent comments (anything hosted at `uploads.linear.app`) are downloaded into the task so the agent can see them. This is the issue-tracker integration. Separately, the [Linear MCP server](/customizing-agents/mcp) lets agents read and write Linear data directly during a task, useful for "go check related tickets" or "update the parent issue when done" workflows. # MCP server Source: https://docs.niteshift.dev/interfaces/mcp-server Kick off and orchestrate Niteshift tasks from any other MCP-enabled agent. Niteshift provides an MCP server that allows your external agent to: * start new tasks * read task transcripts * send follow up prompts * manage Niteshift [Automations](/automations) To enable locally in claude/codex: ```bash theme={"dark"} claude mcp add --transport http niteshift https://mcp.niteshift.dev/unstable ``` ```bash theme={"dark"} codex mcp add niteshift --url https://mcp.niteshift.dev/unstable ``` The Niteshift MCP server supports [Dynamic Client Registration](https://oauth.net/2/dynamic-client-registration/), so you can use it from any MCP client or write your own. The Niteshift MCP is available to all agents running as Niteshift tasks. You can toggle this feature on/off in Settings > Workflow & notifications > Task orchestration. Try telling your agents to kick off a Niteshift task, or delegate some work to a Niteshift task with a different harness or model. # Slack Source: https://docs.niteshift.dev/interfaces/slack Trigger Niteshift tasks from Slack. DM the bot for private work or @mention it in a channel for team-visible tasks. Trigger and interact with tasks from Slack. DM the bot for private tasks, or mention `@Niteshift` in a channel to start a team-visible one. ## Setup Open **Settings → Integrations → [Slack](https://niteshift.dev/settings#integrations)** and click **Add to Slack**. The OAuth flow installs Niteshift workspace-wide. Run `/invite @Niteshift` in any channel where you want to trigger tasks. The bot only sees channels it's been invited to. ## How to use **DM the bot** for private tasks. Only you see the conversation:
Slack direct message with Niteshift showing a user prompt and Niteshift starting work on the task.
**Mention `@Niteshift` in a channel** for team-visible tasks. The bot starts with your prompt, plus the thread and recent messages in the channel as context. It will keep you updated in the thread as it works.
Slack thread with a Datadog alert, a user asking Niteshift to identify a root cause and open a pull request, and Niteshift responding with a root cause and task links.
Reply in the same Slack thread to send follow-up prompts to the same task. The agent picks up your reply and continues working. Other members of your team can reply in the same thread to create their own independent tasks. Slack is a natural place for "respond to a production alert" workflows. With an [MCP server](/customizing-agents/mcp) like Datadog or Sentry posting alerts to a channel, you can reply `@Niteshift fix this` and the agent picks up the alert context as part of the prompt. # Introduction Source: https://docs.niteshift.dev/introduction Niteshift, cloud coding agents that close the loop What separates a good coding agent run from a great one is the developer experience around it: a fast, reliable feedback loop. Niteshift gives every task a cloud environment with dependencies installed, dev server running, and a browser ready, alongside a live preview to collaborate with the agent as it works.