Skip to Content
GuidesDev Servers

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 app

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

CommandWhat it does
shep dev startStart the dev server and stream it until it’s ready
shep dev stopStop 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 clearDrop 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 localhost link.
  • 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:

OrderSourceNotes
1.shep/dev.json committed in the repositoryRe-read on every start. Runs only after you approve it (see below)
2The cached plan for this pathReused until the repository’s config files change. A plan you pinned is reused even then
3Built-in detectorsNo agent call, no tokens
4Your agentOnly 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:

EcosystemLooks forRuns
Nodepackage.json with a dev, start or serve script<pm> run <script> (npm, bun) or <pm> <script> (pnpm, yarn), chosen by lockfile
Denodeno.json / deno.jsonc with a dev, start or serve taskdeno task <name>
MakeA Makefile with a dev, start, serve or run targetmake <target>
Pythonmanage.py, pyproject.toml, Pipfile, requirements.txtpython manage.py runserver, a declared script, or the entry file, through uv, poetry or pipenv when present
Gogo.mod and a package maingo run . or go run ./cmd/<name>
RustCargo.toml with a [package] tablecargo run
Rubybin/rails, or a Gemfile with railsbin/rails server or bundle exec rails server
Elixirmix.exsmix phx.server for Phoenix, otherwise mix run --no-halt
Docker Composecompose.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
FlagValue
-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-managerLabels, or none to clear them
--setup <command...>Setup commands to run before the server starts
--clear-setupRemove 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"] }
FieldRequiredNotes
commandyesNon-empty. Without it the file is ignored
cwdnoDefaults to the repository root. Must be an existing folder inside the repository, or the file is ignored
expectedPortno1–65535; an invalid value is dropped
language, framework, packageManagernoLabels
setupCommandsnoStrings 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 reviewed

The 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