Skip to content

Go to the docs contents

Dev mode

Dev mode serves your machine’s dev server at a while address. The organization’s members open it in their browser and leave their notes there, without a deployment.

Updated November 21, 2026.

View as Markdown

Dev mode: the dev server on your laptop opened by your colleagues in their browser, the same app on both screens, without deploying

You, to your AI: Show what I’m working on, without deploying it.

When to use it

To show your work in progress to your colleagues or a client, without deploying it: run npx while-sh dev.

How it works

Dev mode serves your machine’s dev server at a while address, <project>-dev-<name>.while.cloud. The organization’s members open it in their browser, without a deployment.

  1. Node 22 or later is required. If your dev server is already running, run npx while-sh dev --project boutique (here, boutique is the project’s slug). Otherwise, let while-sh start it: npx while-sh dev --project boutique -- npm run dev.
  2. The first time, while-sh gives a while page and a sign-in code. Open the page and check that it shows the same code.
  3. while-sh writes the address to stdout. Whoever gets into the project’s app in production gets into this address.
  4. At this address, pages have a notes widget: a member points out there what is wrong. Their note reaches your machine within a few seconds, on stderr and in .while/remarques/<n>.md. Your AI reads it in that file, or with the MCP tool list_page_notes.
  5. Someone who has no while account, a client for example, gets in through a sharing link. Create it in Project › Settings › Links, “Dev addresses” group. Your AI gives you that page with the MCP tool request_access_link { dev_address }: you are the one who creates the link. It lasts 1 to 7 days.

What to know

while-sh has no dependencies and runs without installing through npx. Once installed (npm install -g while-sh), it runs as wh:

wh dev --project boutique
wh dev status        # in another terminal: the addresses served from this machine
wh dev stop [name]   # stops all these addresses, or the one with that name
wh login             # signs this machine in
wh logout            # forgets this machine's sign-in

Without —project, while-sh takes the project if this machine can serve only one; otherwise, it lists them. The port is the one given by —port, otherwise the first one listening among 5173, 3000, 4321 and 8080. stdout receives a single line: the address, or with —json the address, the host, the project and the port. The rest goes to stderr: the session’s status, the notes and the dev server’s output.

With a command after —, while-sh starts it and waits for one of the usual ports to listen. Vite refuses a Host header it does not know. Astro, SvelteKit and Nuxt, built on Vite, do the same. So the server started this way receives the dev address in __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS, the variable Vite reads for that. A Vite started separately refuses the address (403 “Blocked request”). while-sh then says what to do, only once: restart Vite after —, or add the address to server.allowedHosts in vite.config.

In the address, the default name is 4 characters, drawn by while, always the same for you on this project. With —name, you choose it: 2 to 20 characters, letters, digits and hyphens, no hyphen at the start or end. A name is yours alone, and you have a limited number of them per project. A default name changes only if its address becomes that of an app or a project: another one is then drawn. The address is never indexed by search engines.

Members sign in with their organization account (its realm), as for an internal app. Hot reload (HMR, over WebSocket) goes through for them.

The machine’s first sign-in follows the OAuth device flow. The token it receives opens only dev mode, in the organization you chose: no other API permission, and not MCP. The machine’s tokens go in ~/.config/while/identifiants.json (mode 0600) and renew by themselves. You must be able to deploy the project (project.deploy permission). A trial project without an account has no dev mode.

A session lasts 12 hours, then while-sh reopens one by itself, at the same address. It resumes the same way after a network drop or a restart of while’s relay, which carries requests from the address to your machine. It stops and says why in two cases. In while, your permissions, this machine’s sign-in or the project are withdrawn, or your account is disabled. Or the same address is served a second time, from this machine or under your account. Permissions withdrawn, an account disabled or the machine’s sign-in revoked cut the session in under 10 seconds.

The relay adds the notes widget (/__while/retours.js) to the dev server’s HTML pages. while-sh writes a note’s file in the current folder. The member’s text is quoted there as data, so that your AI does not take it for an instruction.

Only the person serving the address creates a sharing link, with the project.configure permission. The link’s password is optional. The link is active right away, with no approval, even if the project is in production, since the address serves your machine’s code.

A link’s visitor arrives without an identity. Pages go through for them, with their resources and the calls their scripts make to the address. WebSockets do not, so neither does hot reload. A link is revoked when its author leaves the organization or no longer has project.configure, and when the default name of its address changes.

while-sh also opens, on a local port of your machine, a database, a cache or an internal app of one of the project’s environments. You get in under your identity, with your permissions.

wh dev database [name] --env <env> [--project <slug>] [--port 5432] [--json] [-- <command>]
wh dev cache <name> --env <env> [--project <slug>] [--port 6379] [--json] [-- <command>]
wh dev service [name] --env <env> [--project <slug>] [--port 8000] [--json] [-- <command>]

Here, name is that of the database, the cache or the app. For a cache, it is required: it is its name in while.yaml. Without a name, database and service take the default database or app.

database opens a PostgreSQL database of the environment, under your SQL role and your permissions. The address written to stdout contains a local password drawn for this session. The command started after — receives it in DATABASE_URL. In production, the database is read-only. It opens in two cases only: you are an admin or an owner and you confirm, or you have been granted time-limited access. For a production database, while-sh stops at the end of the session and asks you to run the command again, because access to production is confirmed again.

cache opens a Valkey cache of the environment, under your ACL user. data.read on the environment gives reading; data.write gives writing, outside production. The address written to stdout, in redis://, contains a local password. The command started after — receives it in REDIS_URL. KEYS is closed: use SCAN.

service opens an internal app of the environment, the one you would open at its address in your browser. It receives you under your identity, as in the browser. The address written to stdout is http://dev:<local password>@127.0.0.1:8000. The command started after — receives it in WHILE_SERVICE_URL. In production, only GET and HEAD go through.

A person serves at most 3 addresses, an organization 20. A session accepts at most 64 requests at the same time, 50 MB per request body and 5 GiB in all.

The organization’s activity log says “connected their workstation in dev mode”, with the address. It then says “disconnected their workstation from dev mode”, with the duration, the bytes and the reason.

Your agent’s MCP tools

Your agent handles it with the list_page_notes and request_access_link tools.

Give your AI the message, and it takes care of the rest

Give this to your AI

Read while.sh/agents and help me get started with while.

Copy the message

In 3 minutes, with no sign-up, the tool has its own address. To keep it, create your account.

For a company project, write to the while team: hello@while.sh