Run an AI agent on a machine you control

What this website is

nocturnh.com is the product page and documentation for Nocturn. It is a static site. No agent runs here, no account exists here, and nothing you type on this site is sent to a server. The home page shows what Nocturn does, with a scripted demo that calls no model and no tool, and this page explains how to use it.

So, if you came here wondering what the site does: it tells you about Nocturn and gives you the install command. The real work happens after you run that command on your own computer or server.

Overview and architecture

Everything is one Node process called the gateway, plus a thin CLI that talks to it over HTTP. There is no database and no cloud account. State is JSON files in one folder.

The parts

How a message flows

1. You send textFrom nocturn chat, the dashboard, a Telegram message, or a cron job. It lands on POST /api/sessions/:id/messages.
2. The agent calls the modelAnthropic by default, with adaptive thinking, or any OpenAI-compatible endpoint such as Ollama. Text streams out as events while it is generated.
3. The model asks for toolsEach tool call is validated, then checked against its policy. auto runs now, ask waits for you, deny is refused.
4. You approve or denyIn the terminal, with nocturn approvals, in the dashboard, or by replying /approve in the chat that started the run. A question times out after 10 minutes.
5. Results go back to the modelUp to 40 steps per turn. When the model stops asking for tools, the final text is the reply, and the whole conversation is saved to disk.

The data folder

Everything lives in ~/.nocturn (or wherever NOCTURN_HOME points). Keys are stored in plain text. Never commit or share this folder.

~/.nocturn/
├── config.json      provider, model, keys, persona, policies, channels
├── token            the bearer token for the API and the dashboard link
├── memory.json      saved memories, one entry per line of the system prompt
├── jobs.json        cron jobs with their last run and status
├── partners.json    the Trusted by list shown on the home page
├── wallet.json      the signed wallet proof, if you linked one
├── miner.json       miner name, pool address, pool token
├── pool.json        accounts and balances, only if you host a pool
├── gateway.pid      pid of the background gateway
├── gateway.log      its log, read with nocturn gateway logs
├── browser/         the headless browser profile
├── sessions/        one JSON file per conversation
└── workspace/       the only folder the file tools can touch
    └── skills/      one folder per skill, each with SKILL.md

Install

Nocturn needs Node 22 or newer and a model: a Claude API key, or any OpenAI-compatible endpoint. Install it once from npm, then run the guided setup.

Linux and macOS

$ npm install -g @morpheapp/nocturn
$ nocturn onboard

Windows

PowerShell blocks the .ps1 shims that npm installs, so call the .cmd versions.

$ npm.cmd install -g @morpheapp/nocturn
$ nocturn.cmd onboard

If you would rather use the short names, allow local scripts once for your account and open a new terminal:

$ Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

What onboard does

1. Picks a provideranthropic or an OpenAI-compatible endpoint. For Anthropic it asks for the key and a model name; for OpenAI it asks for the base URL, model name, and an optional key.
2. Optionally connects TelegramPaste a bot token from BotFather. You can add Discord and Slack later with nocturn channels add.
3. Starts the gatewayIn the background, and offers to install it as a login service so it survives reboots.

Check that everything is healthy with nocturn doctor, then talk to it with nocturn chat.

Desktop and mobile apps

You do not have to live in the terminal. The Download section of the home page has installers for each platform.

Command line

Every command calls the gateway's API with the token from ~/.nocturn/token. If the gateway is not running, most commands tell you so. Add --json to any listing command for machine-readable output, and --version prints the version.

Setup

Gateway

Talking to the agent

Channels and pairing

Automation and knowledge

Mining and website

Environment

NOCTURN_PORT changes the gateway port (default 18790). NOCTURN_HOME moves the state folder. Both must be set for the CLI and the gateway alike, because the CLI finds the gateway through them.

Chat channels

Connect a bot and Nocturn answers from your phone. Each chat becomes its own session, named telegram:<chat>, discord:<channel>, or slack:<channel>, with its own history.

Telegram

1. Create a bot with @BotFather and copy its token.
2. Run nocturn channels add telegram and paste it.
3. Send your bot any message. It replies with a pairing code.
4. Run nocturn pairing approve <code>. From now on that account can talk to Nocturn.

The adapter long-polls getUpdates and only accepts private chats. Replies are split at 4,000 characters.

Discord

1. Create an application in the Discord developer portal, add a bot, and enable the Message Content intent.
2. Invite it to your server with permission to read and send messages.
3. Run nocturn channels add discord with the bot token.
4. DM the bot, or mention it in a channel. Approve the pairing code.

The adapter connects to the Discord gateway over WebSocket with the guild messages, direct messages, and message content intents. In servers it only reacts when mentioned. Replies are split at 1,900 characters and never ping anyone.

Slack

1. Create a Slack app with Socket Mode on. Add the app_mentions:read, chat:write, im:history, and im:read scopes, and subscribe to app_mention and message.im events.
2. Install it to the workspace. Copy the bot token (xoxb-) and an app-level token (xapp-) with connections:write.
3. Run nocturn channels add slack and paste both.
4. DM the app or mention it in a channel. Approve the pairing code.

Pairing

Unknown senders never reach the agent. The first message from a new sender gets a 6-digit code and a note saying this Nocturn is private. The request shows up in nocturn pairing list, nocturn status, and the dashboard. At most 20 requests wait at once; after that new strangers are ignored until you clear some. Approving writes the sender id to channels.<name>.allow in the config.

Approvals from chat

When a run that started in a chat needs permission, the question is sent to that same chat, with the first 300 characters of the tool input:

Allow shell?
{"command":"systemctl restart app"}

Reply /approve or /deny

Reply /approve or /deny. If nothing is waiting, the bot says so. The dashboard and nocturn approvals can answer the same question.

Tools and permissions

The model gets twelve tools. Each has a policy in config.policies: auto runs without asking, ask waits for your answer, deny refuses and tells the model the tool is disabled.

Change a policy with nocturn config set policies.shell auto, or in the dashboard. Valid values are auto, ask, and deny.

The approval flow

1. Validation firstTool inputs stream in eagerly and are not validated by the API, so Nocturn checks required fields, types, and enums itself before anything runs. A bad input is reported to the model without running.
2. Then the policyAn ask tool emits an approval event with the tool name and full input. The run pauses.
3. You answer anywhereTerminal prompt, nocturn approvals approve <id>, the dashboard, or /approve in the chat. A denied or expired request (10 minutes) tells the model the owner did not approve, and the model is instructed not to work around it.

Safety model

• The gateway listens on 127.0.0.1 only, requires the bearer token for every API call, and rejects requests whose Host or Origin is not local. That blocks DNS rebinding and cross-site requests.
• File tools resolve symlinks and refuse any path that leaves ~/.nocturn/workspace.
• Web and browser tools resolve the hostname first and refuse private, loopback, link-local, and multicast addresses, including IPv4-mapped IPv6. The agent cannot reach your gateway, your LAN, or cloud metadata endpoints.
• The system prompt tells the model that web pages, files, tool output, and relayed chat messages are data, not instructions from you.
• Secrets are never returned by the API. The config endpoint redacts them, and a blank value in an update keeps the stored secret.

Skills, memory, and schedules

Skills

A skill is a folder in ~/.nocturn/workspace/skills/ with a SKILL.md inside. The name must be lowercase letters, digits, and dashes. Its description is listed in every system prompt; the body is loaded only when the model calls load_skill, so you can keep long instructions without paying for them on every turn.

---
name: weekly-update
description: How to write the Monday update for the team
---

Read notes/week.md, group the items by project, and write
briefs/update.md with three sections: shipped, in progress, blocked.
Keep each line under 15 words.

Create skills by hand, with POST /api/skills, or in the dashboard. Remove one with nocturn skills rm weekly-update.

Memory

Memories are short facts, one per entry, stored in memory.json and injected into every system prompt under “Saved memories”. The model can save them with memory_save and search them with memory_search; you can manage them with nocturn memory.

$ nocturn memory add "I prefer short answers"
$ nocturn memory list
$ nocturn memory rm <id>

Cron jobs

A job runs a prompt on a 5-field cron schedule, in the server's local time. Each run is its own session named cron:<job id>, so a job keeps its history across runs. If the job has a deliver target, the reply is sent there.

$ nocturn cron add --name brief --cron "0 8 * * 1-5" -m "plan my day" --deliver telegram:42

Lists, ranges, and steps are supported; names like MON are not. The scheduler checks once a minute and only fires enabled jobs. nocturn cron run <id> fires one immediately, which is the easiest way to test a prompt.

HTTP API

The CLI and the dashboard use this API, and so can your own scripts. Base URL http://127.0.0.1:18790/api. Every call needs Authorization: Bearer <token> with the token from ~/.nocturn/token. Bodies and responses are JSON. Bodies are limited to 1 MB.

$ TOKEN=$(cat ~/.nocturn/token)
$ curl -s http://127.0.0.1:18790/api/state -H "Authorization: Bearer $TOKEN"

State and events

Sessions and approvals

Channels, jobs, skills, memory

Wallet and partners

Event types

Everything on /api/events carries a sessionId where it applies.

Mining

nocturn mine hashes SHA-256 on your CPU and reports shares to a pool. Balances are in NOCT, a number kept by the pool server. NOCT is not a coin on a blockchain, cannot be withdrawn, and has no guaranteed value. Only mine on a machine you own or have permission to use.

Start mining

$ nocturn mine
$ nocturn mine --threads 4
$ nocturn mine balance

1. Pick a name3 to 20 characters: letters, digits, dash, underscore. The pool returns a token that is saved in miner.json. The default pool comes from the package, or pass --pool https://..., or set NOCTURN_POOL.
2. Answer the checkA small addition, asked once when mining starts. Three wrong answers end the session.
3. HashBy default all cores but one. The screen shows hashrate, job and round progress, estimated share of the round reward, last payout, balance, hardware, temperature, and what auto-tune is doing.

Press Ctrl+C to stop. Mining only runs while that terminal is open; on a server use tmux so it survives disconnects. The check lasts as long as the miner keeps talking to the pool. If contact is lost for over 30 minutes, mining pauses and the check is asked again.

Auto-tune

Every 15 seconds the miner reads CPU temperature (Linux hwmon, or Windows ACPI thermal zones), GPU temperature through nvidia-smi when available, and free memory. At 85°C or above it idles one thread. Under 8% free memory it idles one thread. Once it is 75°C or cooler for a minute, it brings one back, up to the number you asked for. Virtual servers often expose no sensors, and then it simply keeps your thread count.

Hosting a pool

$ nocturn pool run --host 0.0.0.0 --port 18800 --trust-proxy

Put it behind an HTTPS reverse proxy, then set nocturn.pool in package.json to its address. --trust-proxy reads X-Forwarded-For so the limit of 5 sign-ups per address per hour works behind the proxy. The pool keeps accounts in pool.json, or the file you pass with --file.

Each round lasts 60 seconds and pays 100.00 NOCT, split by work: a share at difficulty d counts as 2^d. Difficulty is per miner, starting at 20 bits, raised by one when shares arrive faster than every 2.5 seconds, lowered by one after 20 seconds without a share, between 8 and 44. Duplicate and stale shares are rejected, and a miner is limited to 20 shares per second.

Linking a wallet

On your own dashboard, Connect wallet asks MetaMask (or any wallet that injects window.ethereum) to switch to Robinhood Chain (chain id 4663), then to sign this message with personal_sign:

Nocturn wallet link
Wallet: 0xYourAddress
Issued: 2026-11-03T12:00:00.000Z

The gateway recovers the signer from the signature and refuses anything that does not match the address. No private key is ever sent. The proof is stored in wallet.json and sent to the pool the next time you run nocturn mine, so the pool can show the wallet on your account. On the public site the button only switches networks and signs nothing.

Configuration and servers

config.json

Read with nocturn config get, change with nocturn config set, the dashboard, or PUT /api/config. Unknown keys are dropped and types must match the defaults.

Environment variables

On a server

$ nocturn onboard
$ nocturn gateway install
$ loginctl enable-linger $USER

On Linux this writes a systemd --user unit named nocturn-gateway with Restart=on-failure, and enable-linger keeps user services running after you log out. On Windows it creates a scheduled task that starts at login.

The gateway still listens on 127.0.0.1 only. To open the dashboard from your own computer, tunnel to it, then open the link from nocturn dashboard:

$ ssh -L 18790:127.0.0.1:18790 user@your-server

The same tunnel is what the mobile apps and the installable web app use: they talk to 127.0.0.1:18790 on the phone, which the tunnel forwards to the server.

Website deployment

The landing page in public/ is both the dashboard your gateway serves and the public site. nocturn site build copies it into a folder a static host can serve, writes partners.json with your Trusted by list, and adds a _headers file with the same Content-Security-Policy the gateway sends.

$ nocturn site build --out site
$ npx wrangler deploy

On Windows PowerShell use npx.cmd wrangler deploy, since PowerShell blocks npx.ps1 by default. wrangler.jsonc serves site/ as a Cloudflare Worker with static assets on nocturnh.com and www.nocturnh.com. Any other static host works: upload the folder and keep the headers.

The public site has no gateway, so the Connect wallet button only connects, the Trusted by section comes from the file written at build time, and the numbers in the “Remembers how you like things” tile stay at zero. The token contract and the official X account are published from the admin page at /admin, which needs the admin password set on the Worker.

FAQ and troubleshooting

Start with nocturn doctor. It checks Node, dependencies, the state folder, the gateway, the model key, and each enabled channel, and prints the fix for anything that fails.