Processes

A process is a long-running command — npm run dev, an emulator, a watcher. Nocturnal starts it detached and keeps a registry, a status, and a log.

Declare a process

Sync project info writes a processes array into .nocturnal/project.json. When the repo already has .vscode/tasks.json, ecosystem.config.*, or a Procfile, those are imported first (a PM2 “Start Dev Environment” task becomes a group of the ecosystem apps, not pm2 start):

{
  "id": "web",
  "name": "Web",
  "command": "npm run dev",
  "cwd": "."
}

The registry id is {projectId}-{id}. Ad-hoc starts (a command you run once from the CLI) get a generated id.

A definition is only the recipe. Nothing starts until you press Start — or boot resurrection does.

Scripts in project.json are one-shot (deploy, seed, migrate). Processes are the ones that stay up. Groups are WebStorm-style compounds of processes — never scripts.

What you see

The Processes tab is two columns: groups then the process list on the left, the selected process's live log on the right. Each process row has Start / Stop / Restart. A group row starts or stops every member. New group names a set of existing defs. Click a row to follow its log. ⌘-click or middle-click opens Terminal.app on tail -f of the same file.

Right-click a project in the rail for Start process (groups and defs), Start script, View scripts, and Stop all (processes + attributed ports; never 17410/17411).

The Dashboard middle column shows the same rows in compact form, next to the ports those processes usually bind.

Statuses

starting · online · stopping · stopped · crashed · errored

A definition with no registry row is idle until first start. Stopped rows stay until you delete them. Crashed means it exited when it was supposed to stay up.

Logs

• Process: ~/.nocturnal/logs/proc-<id>.log (rolls to .1 at ~5MB)
• Last lines: noc logs <id> -n 80
• Same via MCP proc_logs or POST /cmd { "type": "proc.logs", "payload": { "id": "<id>", "lines": 80 } }

If something is down, read the log before you kill a port.

After a reboot

noc save snapshots which processes should be running. Settings → Restart processes on boot (processAutostart) resurrects that set when Nocturnal starts, and installs a macOS login item so Nocturnal itself comes back.

Without that setting, a restart leaves everything stopped. The definitions stay in project.json.

Commands

noc is the short CLI. Process verbs sit at the top — you do not need proc. nocturnal proc … is the same commands.

noc ls
noc start -p <projectId> -c "npm run dev" --cwd /path
noc stop <id>
noc restart <id>
noc delete <id>
noc logs <id>
noc save
noc resurrect
noc start-group -p <projectId> -g <groupId>
noc stop-group -p <projectId> -g <groupId>
noc stop-all -p <projectId>
noc script -p <projectId> -s <scriptId>