Control Nocturnal from an agent

Everything the dashboard can do, a model can do. There is no second-class path: the Nocturnal UI, the phone app, the noc CLI, the MCP server and a plain HTTP request all send the same thing — a command to the engine on your machine.

That means you can hand this page to ChatGPT, Claude, or anything else that can call a tool or make a web request, and it can run your workspace: start an agent on a project, reply to it, set up a loop, run a script, restart a server, commit and push, open an issue, cut a release.

There are three ways in. Pick by where the model lives.

MCP

Every command is an MCP tool, named with an underscore instead of the dot: agent.new is the tool agent_new, proc.restart is proc_restart. Each one carries its own parameters and description, so a model picks the right tool without being told about Nocturnal first.

Add https://nocturnal.sh/mcp to your client and sign in with your Nocturnal account (MCP). It reaches every computer on your account; pass device to say which.

CLI

noc has short verbs for the things people type daily, and a generic one for everything else.

noc commands                  # every command, grouped, with its parameters
noc commands agent            # just the ones matching "agent"
noc commands --markdown       # the full reference, as markdown to paste into a prompt

noc cmd agent.new projectId=my-app prompt="fix the header spacing"
noc cmd proc.restart id=my-app-web
noc cmd settings.set key=agentDefaultModel value=claude-opus-5

noc cmd <command> key=value … reaches every command, including ones added after this page was written. Values are converted using the command's own types — times=3 is a number, weekdays=yes is a boolean, labels=bug,ui is a list — and a missing required parameter is caught before anything is sent.

Read state with noc topics:

noc topics                    # everything the dashboard renders
noc topics projects
noc topics agentsIndex

Full verb list: CLI.

HTTP

The engine listens on 127.0.0.1:17410. Two endpoints do everything:

GET  /api/topics              # all state — projects, sessions, processes, git, CI, issues
POST /cmd/<command>           # run a command, payload as the JSON body

curl -s http://127.0.0.1:17410/api/topics/projects

curl -s http://127.0.0.1:17410/cmd/agent.new \
  -H 'Content-Type: application/json' \
  -d '{"projectId":"my-app","prompt":"fix the header spacing"}'

Every command replies with the same envelope: { "ok": true, "data": … } or { "ok": false, "error": "…" }.

GET /api/commands returns the whole catalog as JSON — type, group, summary, parameters, and whether the command is read-only. A model that starts there needs no other documentation.

Give it to a custom GPT

The engine publishes its own OpenAPI document at /api-docs/openapi.json, with one operation per command. Import that into a GPT Action, an SDK generator, or Swagger UI at /api-docs.

Assistant builders cap how many operations they will import, so you can ask for a slice:

http://127.0.0.1:17410/api-docs/openapi.json?group=Agents,Projects,Processes

Groups are Agents, Plans, Projects, Processes, Scripts, Ports, Git, GitHub, Issues, Versions, Settings, System.

Reaching it from outside this machine

127.0.0.1 is deliberate: the engine binds to loopback and has no password, because anything that can reach it can run commands on your computer. A hosted assistant is not on your machine, so it cannot call that URL directly. To drive Nocturnal from somewhere else, sign in and use the dashboard, the phone app, or the MCP server, which all relay commands through your account. If you want a hosted model to reach the engine, put it behind a tunnel you authenticate — do not expose port 17410 to a network.

What to tell the model

Three sentences are usually enough:

Nocturnal runs my projects. Read state from GET /api/topics and change things with POST /cmd/<command> on http://127.0.0.1:17410. Call GET /api/commands first to see what exists.

Two habits worth adding: commands marked read-only in the catalog are safe to call while exploring, and Nocturnal never commits or branches on its own — if you want a commit, the model has to ask for git.commit.

Every command

Commands marked read-only change nothing. * marks a required parameter.

Agents

Plans

Projects

Processes

Scripts

Ports

Git

GitHub

Issues

Versions

Deploy

Settings

System