Dev Servers
Shep can start a repository’s dev server for you, for the main checkout, for any feature’s worktree, or for an app, so you can click through a change before you approve it. It works out which command to run, installs dependencies when needed, waits until the server answers, and shows you the URL.
From the CLI
shep dev start # the repository or worktree you're in
shep dev start --feature <id> # a feature's worktree
shep dev start --repo ~/src/shop # a repository by path
shep dev start --app <id> # an appstart streams the run through its stages (analyzing, installing, booting, ready) and prints the URL once the server answers. Press Ctrl-C to stop following the output; the dev server keeps running.
| Command | What it does |
|---|---|
shep dev start | Start the dev server and stream it until it’s ready |
shep dev stop | Stop it |
shep dev status [--json] | State, URL, port, the command it runs, and where that plan came from |
shep dev logs [-F] [-n <count>] | Show the server’s output; -F keeps following, -n shows the last lines only |
shep dev plan show [--json] | Show the resolved run plan |
shep dev plan set -c "<command>" … | Pin your own run plan |
shep dev plan clear | Drop the cached plan so the next start re-analyzes |
shep dev approve [--fingerprint <hash>] | Review and approve the commands in a committed .shep/dev.json |
Every subcommand takes one target: -a, --app <id>, -f, --feature <id> or -r, --repo <path-or-id>. With none, Shep uses the folder you’re in. --app and --feature need the full id.
From the web UI
- Repository node on the Control Center canvas: the Run · start local environment row starts the server. Once it’s up, the node shows the
localhostlink. - Feature drawer: a dev-server bar runs the feature’s worktree.
- App page: the preview tab runs the app and shows it inline. Its collapsed Run plan panel shows the command, with Edit and Re-analyze.
The repository and feature controls are behind the Deployments flag (envDeploy, on by default). If they’re missing, run shep settings flags enable envDeploy.
How Shep decides what to run
The answer is a run plan: the command, the working directory, setup commands, and the expected port. Shep resolves it in this order and stops at the first answer:
| Order | Source | Notes |
|---|---|---|
| 1 | .shep/dev.json committed in the repository | Re-read on every start. Runs only after you approve it (see below) |
| 2 | The cached plan for this path | Reused until the repository’s config files change. A plan you pinned is reused even then |
| 3 | Built-in detectors | No agent call, no tokens |
| 4 | Your agent | Only when every detector falls through (for example JVM, .NET or PHP projects) |
If no agent is configured and no detector matches, the start fails with a message telling you what to set.
Built-in detectors
The first one that matches wins:
| Ecosystem | Looks for | Runs |
|---|---|---|
| Node | package.json with a dev, start or serve script | <pm> run <script> (npm, bun) or <pm> <script> (pnpm, yarn), chosen by lockfile |
| Deno | deno.json / deno.jsonc with a dev, start or serve task | deno task <name> |
| Make | A Makefile with a dev, start, serve or run target | make <target> |
| Python | manage.py, pyproject.toml, Pipfile, requirements.txt | python manage.py runserver, a declared script, or the entry file, through uv, poetry or pipenv when present |
| Go | go.mod and a package main | go run . or go run ./cmd/<name> |
| Rust | Cargo.toml with a [package] table | cargo run |
| Ruby | bin/rails, or a Gemfile with rails | bin/rails server or bundle exec rails server |
| Elixir | mix.exs | mix phx.server for Phoenix, otherwise mix run --no-halt |
| Docker Compose | compose.yaml / docker-compose.yml with services: | docker compose up |
When nothing matches at the repository root, Shep runs the same detectors on each immediate subfolder (one level deep, skipping node_modules, build output and dot-folders), so simple monorepos work too.
Setup commands are added where the ecosystem needs them: uv sync, poetry install, pipenv install, pip install -r requirements.txt, go mod download, mix deps.get, bundle install. They run again when the lockfile changes.
Shep sets an expected port only when it’s written down: a --port/-p flag in the command, a Compose file that publishes exactly one host port, or a framework default it can identify for certain (Rails 3000, Phoenix 4000, Django 8000). Otherwise it reads the URL from the server’s output.
Pin your own plan
When the detected command is wrong, pin one:
shep dev plan set --repo . -c "make dev" --cwd services/api --port 8080
shep dev plan set --repo . -c "pnpm dev" --setup "pnpm install" "pnpm db:migrate"
shep dev plan show --repo .
shep dev plan clear --repo . # forget it; the next start re-analyzes| Flag | Value |
|---|---|
-c, --command <command> | The command that starts the server |
--cwd <dir> | Working directory, absolute or relative to the repository root. Must stay inside the repository |
--port <port> | Expected port (1–65535), or none to clear it |
--language, --framework, --package-manager | Labels, or none to clear them |
--setup <command...> | Setup commands to run before the server starts |
--clear-setup | Remove all setup commands |
A pinned plan starts from the currently resolved one, so only what you pass changes. It’s never discarded automatically: if the repository’s config files change later, plan show and the web panel tell you it may be stale, and you decide whether to clear it.
A pinned plan is stored per path on your machine. Each feature gets a new worktree path, so for a command that should apply to every worktree and every teammate, commit a .shep/dev.json.
.shep/dev.json
A small JSON file at the repository root, written by hand and committed:
{
"command": "make dev",
"cwd": "services/api",
"expectedPort": 8080,
"language": "Go",
"framework": "Echo",
"setupCommands": ["go mod download"]
}| Field | Required | Notes |
|---|---|---|
command | yes | Non-empty. Without it the file is ignored |
cwd | no | Defaults to the repository root. Must be an existing folder inside the repository, or the file is ignored |
expectedPort | no | 1–65535; an invalid value is dropped |
language, framework, packageManager | no | Labels |
setupCommands | no | Strings run before the server starts |
Unknown keys are ignored. A broken file never stops a start: Shep logs a warning and falls through to the detectors.
While a valid .shep/dev.json is present, shep dev plan set and the web editor refuse to save a plan, because the file would override it. Edit the file instead.
Approve the commands first
Anyone with commit access can change .shep/dev.json, and its commands run on your machine. So Shep treats it as a request: it runs the file’s commands only after you approve that exact set of commands for that repository.
shep dev approve # prints the commands and their fingerprint
shep dev approve --fingerprint <hash> # approve exactly what you reviewedThe first call prints the command, working directory, setup commands and package manager, plus a fingerprint, and changes nothing. The second records your approval. If the file changed in between, the fingerprint no longer matches and nothing is approved.
Changing the command, the working directory, the setup commands or the package manager asks for approval again; editing a label or the port doesn’t. Until a file is approved, Shep ignores it and uses the detectors. Approvals are stored outside the repository, in ~/.shep/approvals/repo-dev-config.json.
What’s next
- Start an app — apps get a live preview in the web UI.
- Parallel features & worktrees — where each feature’s worktree lives.
- Worktree provisioning — prepare worktrees (for example, link
node_modules) before the dev server starts. - Feature flags — the
envDeployflag and others.