Codumentor logo Codumentor Enterprise

Per-Repo Dev Servers

Codumentor can launch, track, and stop long-running dev servers for the
repos it knows about — your Django/Node/etc. project, or Codumentor
itself during dogfooding. One declarative config, one CLI verb
(codumentor dev), one shared registry that codumentor dev status
lists.

This page is for users editing their Codumentor config and developers
wiring .codumentor/ into their repo. The launcher is single-host and
single-user; multi-host scheduling is explicitly out of scope.

When to use this

If your dev server is short-lived (one command, one terminal, you
Ctrl-C when done), you don't need this — just keep using your existing
workflow.

Configuration

Add a dev_server block under the existing per-repo project_setup
entry (or the top-level project_setup if you only have one repo):

project_setup:
  setup_script: .codumentor/setup.sh   # optional; already supported
  watch:                                # optional; already supported
    - requirements.txt
  dev_server:
    command: "python -m myapp serve --port ${PORT}"
    health_path: "/health"             # optional; GET expected to 2xx
    open_url: "http://127.0.0.1:${PORT}/"
    ready_timeout_seconds: 30          # optional; default 30
    env:                                # optional extra env for the child
      MYAPP_CONFIG: dev.yaml

Field reference

FieldRequiredMeaning
commandyesShell-style command line. ${PORT} and any other ${VAR} references are substituted at spawn time. The child inherits the parent env plus PORT and the entries under env:.
health_pathnoIf set, the launcher polls GET http://127.0.0.1:${PORT}<health_path> until it returns 2xx (or the timeout elapses). Without it, TCP-accept is the only ready signal.
open_urlnoThe URL printed after a successful launch and shown by codumentor dev status. Defaults to http://127.0.0.1:${PORT}/. Templated the same way as command.
ready_timeout_secondsnoHow long to wait for the server to become healthy before treating the launch as failed (default 30).
envnoExtra environment variables passed to the child process. Values are templated.

${VAR} templating

The launcher uses Codumentor's regular ${VAR} substitution. It runs
twice:

  1. Load time: real env vars like ${HOME} are resolved when the config file is read. ${PORT} is left literal because it isn't set in the parent environment yet.
  2. Spawn time: a second pass over the dev_server block with PORT=<allocated> injected. command, open_url, and the values under env: are templated then.

So you can freely mix ${HOME}, ${VIRTUAL_ENV}, and ${PORT} in any
of those fields and they'll Just Work.

Port allocation

The launcher binds to :0, reads back the kernel-assigned port, and
closes before spawning. Cheap, no range exhaustion. Ports are not
stable across restarts — every launch gets a fresh port and a fresh
instance id.

CLI: codumentor dev

Four verbs. All of them respect the same --repo NAME semantics as
codumentor setup. If --repo is omitted, the launcher infers the repo
from your current working directory.

codumentor dev [--repo NAME] [--no-wait]
    Allocate a port, ensure project_setup is current, spawn
    dev_server.command, register the instance, wait for the
    healthcheck. --no-wait skips the wait but still registers.

codumentor dev status [--json]
    List running instances. Reconciles dead PIDs out first.
    --json prints a machine-parseable payload that includes
    orphan processes.

codumentor dev stop [--repo NAME | --id ID | --all]
    SIGTERM the matched instances, wait, SIGKILL on timeout,
    drop the registry entries. One of the three selectors is
    required — there is no implicit default.

codumentor dev logs [--repo NAME | --id ID] [-f/--follow] [-n N]
    Print or tail the log file an instance writes to. With -f,
    streams new lines until interrupted or the server exits. -n
    sets how many trailing lines to seed; -n 0 dumps the whole
    file.

Logs and where they live

Stdout and stderr from the spawned server go to
~/.codumentor/dev-logs/<instance-id>.log. The file is append-only;
the launcher never rotates or truncates it. Each launch gets a fresh
id (and so a fresh file), so the on-disk footprint grows by one file
per launch.

codumentor dev logs -f is the usual way to look at output:

$ codumentor dev logs -f
==> /home/me/.codumentor/dev-logs/codumentor-main-58231-a1b2c3.log  [id=codumentor-main-58231-a1b2c3, repo=Codumentor, pid=12345, port=58231]  (following — Ctrl-C to stop)
INFO:     Started server process [12345]
INFO:     Uvicorn running on http://127.0.0.1:58231 (Press CTRL+C to quit)
…

The follow loop exits cleanly when the server's PID disappears — so a
logs -f against a crashed server returns instead of hanging.

Selecting an instance

When you only have one preview running, the CLI uses it. When you have
more than one, pick with either --repo NAME (any unique repo) or
--id ID (use dev status to list ids). The error message lists the
valid options.

Orphan processes

codumentor dev status lists, in a separate section, live processes
that carry the launcher's internal marker but are missing from the
registry. You see these if the registry file was deleted while servers
were still running. Each comes with a manual kill <pid> hint;
Codumentor deliberately never kills them automatically.

Limits, soft caps, and resource pressure

Each preview is a full server process — venv, sqlite, whatever else
your app pulls in. The launcher emits a soft warning to stderr if you
go above 3 running instances. There's no hard limit; CI and scripted
callers are never blocked, just reminded.

Selfdev (Codumentor's own dev_server)

codumentor-localdev.yaml (the repository's local development config for
working on Codumentor from a checkout; it is not shipped with Codumentor)
carries a working dev_server block so you can dogfood the launcher on
Codumentor itself:

project_setup:
  dev_server:
    command: "${VIRTUAL_ENV}/bin/codumentor -c codumentor-localdev.yaml api --port ${PORT}"
    health_path: "/health"
    open_url: "http://127.0.0.1:${PORT}/"

scripts/setup-worktree.sh --dev builds a worktree (its own venv + UI
build) and execs codumentor dev against it. codumentor dev status
then shows one row per worktree with its URL, and
codumentor dev stop --all stops them all when you're done.

Dev servers and the sandbox

codumentor dev runs on the host, outside workspace isolation. It starts
the configured checkout (or the worktree you run it from), not a
conversation's sandbox, so it does not show an agent's uncommitted sandbox
changes.

In an isolated conversation the same dev_server block can run **inside the
conversation's sandbox** and open in Preview. This needs the preview's own
sandbox origin (api.app_preview.sandbox_origin, the preview's app tier)
and background processes.

How the block is used there:

FieldIn the sandbox
commandRuns from the repository's directory, as a background process without network access. PORT is 5173 (each process has a network namespace of its own, so the port is always free). CODUMENTOR_PREVIEW_BASE is the URL path the preview serves it under; set the server's base path to it (vite --port ${PORT} --base ${CODUMENTOR_PREVIEW_BASE}, Astro base, Next basePath).
envAdded to the process's environment.
health_pathProbed through the preview's forwarder, under the base path first and then below it. Without it, any HTTP answer counts as up.
ready_timeout_secondsHow long the start waits for the health check (default 30). A server that is not healthy by then keeps running; it is pinned and opened all the same, so its health badge and log are in front of you, and the agent is told its status and log path.
open_urlNot used: the preview has its own URL.

The spawn-time ${VAR} pass sees only PORT and CODUMENTOR_PREVIEW_BASE.
Host variables such as ${HOME} were already resolved when the config was
loaded, and any reference left over is expanded by the sandbox's shell. The
server runs with the longest runtime the server allows
(background_processes.default_max_runtime_seconds) and does not survive a
Codumentor restart. A pinned preview whose server is no longer running says
Dev server not running and offers Start dev server again. When nothing
here can start it — a server the agent started with a preview port of its
own, or a deployment without a dev_server block — it says so: ask the agent
to start it again.

Health badge and log

The preview's toolbar shows how the server is doing, next to ■ Stop:

BadgeMeaning
RunningThe process runs and passes its health check (health_path; any HTTP answer without one).
Starting…The process runs but does not answer yet, and is younger than ready_timeout_seconds.
UnhealthyThe process runs but has not answered for longer than that. The tooltip names the failing check.
Exited (code N)The process has ended.

The badge is refreshed every few seconds while the preview is open (more
often while the server is not healthy), and at once when the process ends.

≡ Log opens the last 200 lines of the server's output in a panel over the
preview, refreshed while it is open. It is the same output the background
process card shows, readable only by you.

Troubleshooting

SymptomLikely cause
No repo … has a dev_server.commandThe config in use has no dev_server block, or you passed --repo for a repo that doesn't have one.
Health check fails after 30sIncrease ready_timeout_seconds, or check codumentor dev logs — the process may be failing to bind.
dev status shows a dead instanceA reconcile pass on the next CLI invocation drops it; you can force one with codumentor dev status itself.
Orphan process in dev statusA registry was deleted (or moved by changing CODUMENTOR_DEV_REGISTRY) while a child kept running. Kill the listed PID by hand — Codumentor won't.
No Start dev server in the Preview menuNo repository has a dev_server.command, the preview has no sandbox origin, or background processes are turned off.
Start dev server reports a timeoutThe server did not answer health_path with a 2xx in time. The preview opens anyway with an Unhealthy badge: open ≡ Log. A server that ignores CODUMENTOR_PREVIEW_BASE is still found below the base.
The badge says ExitedThe server crashed or was stopped. ≡ Log shows its last output; Start dev server (or the agent) starts a new one.

See also