No description
  • JavaScript 57.4%
  • Python 40.7%
  • CSS 0.9%
  • HTML 0.8%
  • Shell 0.2%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-18 17:31:21 +09:00
app Preview up to three schedule occurrences without saving 2026-11-18 17:08:11 +09:00
assets Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
docs Merge released noebot v1.1.0 into main 2026-11-18 17:30:00 +09:00
public Preview up to three schedule occurrences without saving 2026-11-18 17:08:11 +09:00
scripts Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
tests Merge released noebot v1.1.0 into main 2026-11-18 17:30:00 +09:00
.gitignore Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
config.example.json Match the deployed noebot runtime baseline 2026-11-18 16:57:59 +09:00
LICENSE Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
README.ja.md chore(release): prepare noebot 1.2.0 2026-11-18 17:31:21 +09:00
README.md chore(release): prepare noebot 1.2.0 2026-11-18 17:31:21 +09:00
tsconfig.browser-checks.json Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
tsconfig.noe-checks.json Snapshot current NOE 2.25.0 deployment and matching development tests 2026-11-09 14:51:56 +09:00
VERSION chore(release): prepare noebot 1.2.0 2026-11-18 17:31:21 +09:00

noebot

English | 日本語

A self-hosted personal AI assistant built on NOE's JavaScript execution, agents, and tools. Use the Web UI or Telegram to chat, delegate work to independent jobs, schedule tasks, save Markdown notes, and generate or edit images. It does not continually call a model while idle.

Each installation is designed for one trusted user and one configured workspace. It is not a shared multi-user service, and NOE is not an OS sandbox. Agents access files and run commands with the permissions of the account running the application. Do not expose it to the public internet without authentication.

Contents

Features

Feature Purpose
Conversations Create, switch, and rename Web conversations. Telegram keeps a separate conversation for each allowed user/chat pair
Independent jobs Run work independently of a conversation. Inspect status and results, add instructions (Steer), request cancellation, and delete ended job history
Schedules Start jobs once, at an interval, or with cron. Enable, disable, or delete definitions
Markdown notes Read, edit, save, and delete named .md files shared between Web and Telegram
Images Generate images or edit an original through NOE's image APIs. Save candidates and revisions under separate IDs, then display them on the Web or send them to Telegram

In a conversation, you can ask, for example, “Run this task as a job,” “Summarize this at 9 AM on weekdays,” or “Save this in ideas.md.” Registration is not task completion: check the result and the actual terminal state. Manual controls for these features are also available in the Web Workspace.

Prerequisites

You need the following to run noebot:

  • Linux
  • NOE 2.25.0 or later, with noe on PATH for both the launching process and its children
  • util-linux flock with --no-fork -n -E support
  • A filesystem supporting native file and directory fsync for the normal AsyncStore path
  • An available NOE provider/model and credentials for your account
  • An existing workspace directory and private locations where configuration and data can be stored
  • A browser for Web use. Telegram is optional and requires a bot token and allowed user/chat IDs

Node.js, npm install, and runtime npm packages are not required. Install NOE and configure its authentication separately. Refer to NOE's distribution and provider documentation, and to noe docs. API keys do not go in noebot's configuration JSON. Building a distribution tar also uses POSIX sh, GNU tar, gzip, sha256sum, and standard coreutils. Python 3, Firefox, TypeScript, and similar tools are for development and testing, not normal startup. GNU coreutils sync -f is needed only when explicitly using the legacy synchronous Store/Notes adapters with their default sync implementation (for example in legacy tests or comparisons).

Installation

Run from source

Clone the repository in an environment with access to it, and select the installation directory:

git clone https://forge.harakara.site/littleisland/noebot.git
cd noebot
export NOEBOT_HOME="$(pwd -P)"

If you already have a checkout, run only the last line in that directory. NOEBOT_HOME is a shell variable used by the commands below; it is not an environment setting that app/run.mjs automatically looks up.

Run from a distribution tar (optional)

From the source checkout, build an artifact in an unused output location. This does not publish or upload anything.

sh scripts/package.sh "$HOME/noebot-artifacts"

This creates noebot-VERSION.tar.gz and its .sha256 file using VERSION. Existing tar/checksum files are not overwritten. The artifact uses an explicit file allowlist and includes the LICENSE, English/Japanese READMEs, runtime code, Web assets, operations documentation, and sample configuration. It excludes credentials, real user data, tests, Git history, and personal instruction files.

The extraction example below uses the current VERSION=1.2.0. Adjust the filenames for other versions. Run it in the directory containing the tar and checksum received through a trusted channel.

sha256sum -c noebot-1.2.0.tar.gz.sha256
mkdir -p "$HOME/opt"
# Extract where there is no existing installation with the same name
tar -xzf noebot-1.2.0.tar.gz -C "$HOME/opt"
export NOEBOT_HOME="$HOME/opt/noebot-1.2.0"

SHA256 verifies integrity; it is not a signature from the distributor.

Prepare the configuration file

For both source and tar installations, prepare the configuration next. These first-time setup commands do not overwrite an existing configuration.

mkdir -p "$HOME/workspace"
CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/noebot"
mkdir -p "$CONFIG_DIR"
chmod 700 "$CONFIG_DIR"
if [ ! -e "$CONFIG_DIR/config.json" ]; then
  (umask 077; cp "$NOEBOT_HOME/config.example.json" "$CONFIG_DIR/config.json")
fi
chmod 600 "$CONFIG_DIR/config.json"
# Edit config.json in an editor before starting

Replace the placeholders in config.example.json with your own values. A minimal configuration has the following shape (it will not start as written):

{
  "workspace": "/absolute/path/to/workspace",
  "timezone": "Asia/Tokyo",
  "agent": {
    "provider": "openrouter",
    "model": "provider/model-id",
    "effort": "auto"
  },
  "web": {"port": 3210}
}
  • workspace: The absolute path to an existing directory to work in. Check it with pwd -P or a similar command. It need not be the installation directory; you can select any existing project.
  • timezone: An IANA timezone such as Asia/Tokyo or Etc/UTC. Also used for cron.
  • agent.provider/model/effort: A combination supported by NOE and available to your account. Do not leave the example model name unchanged. The effort must be one of auto, none, minimal, low, medium, high, xhigh, or max.

First use: provider setup and smoke check

Set up conversation-model credentials in NOE for the account that will run noebot. You can reuse existing credentials if they already work. For OpenRouter, for example, you can save the key in a protected text file and select it through NOE's credential-file variable:

CREDENTIAL_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/noe/credentials"
mkdir -p "$CREDENTIAL_DIR"
chmod 700 "$CREDENTIAL_DIR"
# Use an editor to save the key in $CREDENTIAL_DIR/openrouter-api-key
# Do not paste the key itself into command lines, the repository, configuration JSON, or conversations
chmod 600 "$CREDENTIAL_DIR/openrouter-api-key"
export NOE_OPENROUTER_API_KEY_FILE="$CREDENTIAL_DIR/openrouter-api-key"

This example is for OpenRouter. For other providers, follow that provider's NOE authentication procedure. Use absolute paths for NOE_CONFIG_FILE, credential-file variables, and external authentication configuration. The child host runs in the workspace, so relative paths may resolve differently. Raw API-key environment variables that NOE hides from JavaScript are not forwarded into the bootstrap's child environment. Do not work around this by exposing or printing hidden variables.

After startup, check the following:

  1. Open the Web UI at the printed URL, send a normal message, and wait for the answer to finish.
  2. Ask: “Create an independent job that checks only the current working directory and project name. Do not modify any files.”
  3. In Independent jobs, confirm completed and inspect the saved result. Also confirm that the cwd is the configured workspace.

A printed URL alone does not prove provider authentication succeeded. On failure, check NOE authentication, model availability, and absolute paths to external configuration. Even test conversations and jobs consume provider quota.

Paths and configuration

The installation directory, workspace, data directory, and launching shell's cwd are separate locations. The actual cwd of the host and agents is always the configured workspace. You do not need to copy noebot's code or job temporary directories into it.

Item Selection / default
Configuration file Argument to app/run.mjs. Defaults to ${XDG_CONFIG_HOME:-$HOME/.config}/noebot/config.json
workspace Required. Existing absolute directory, resolved to its real path
dataDir Explicit value, or ${XDG_DATA_HOME:-$HOME/.local/share}/noebot
notesDir Explicit value, or dataDir/notes
instructionDirs.common Explicit value, or ${XDG_CONFIG_HOME:-$HOME/.config}/noe/instructions
instructionDirs.app Explicit value, or instructions/ beside the selected configuration file
initialNotes Array of note names read as context for new conversations/jobs. Default: []
web.port Default: 3210. Range: 0–65535; 0 selects an available port
web.publicOrigin Exact HTTPS origin when using an authenticated reverse proxy. Normally omitted
  • All directory values in JSON must be absolute paths. ~, $HOME, and environment variables are not expanded. The shell notation in the table explains defaults; it is not a literal string to put in JSON.
  • HOME and nonempty XDG variables must also be absolute paths. Unset or empty XDG variables fall back to HOME. Both XDG bases are resolved even when an explicit configuration file is selected.
  • Omit options you do not need. null, unknown keys, and invalid types are rejected.
  • Data/notes directories are created as needed, but their parents must be accessible and writable. Paths to data/notes must not contain symlink components; choose real paths.
  • Instruction directories are explicitly selected in common → app order. They need not exist. The workspace's AGENTS.md and .noe/instructions/ are not read implicitly. Set instructionDirs.app to that directory if needed.
  • Configuration changes require a stop and restart. Instruction-file changes do not apply retroactively to existing AI instances.

For all settings and limits, see Configuration and credentials in Operations; for example limit values, see config.example.json. By default, at most four jobs can run concurrently (excess requests are rejected; there is no queue), and at most 1000 top-level tasks are admitted during a host's lifetime. On HOST_TASK_LIMIT, the operator must let active work finish and then restart. Resetting a conversation does not reset this counter. NOE's execution, output, and step limits apply separately.

Running, stopping, and diagnostics

After configuring credentials and settings, choose one of the following foreground startup commands. Do not run multiple hosts against the same dataDir.

noe run --no-inst "$NOEBOT_HOME/app/run.mjs"
# To select a configuration file explicitly
# noe run --no-inst "$NOEBOT_HOME/app/run.mjs" /absolute/path/config.json
# To override the Web port for this run only (without changing the configuration file)
# noe run --no-inst "$NOEBOT_HOME/app/run.mjs" --port 4321

Open exactly the http://127.0.0.1:PORT URL in the listening JSON. Substituting localhost or a different port is rejected by Host/Origin checks. The default bind address is loopback. To use it from another device, the operator must provide a secure connection path separately. Setting web.publicOrigin alone does not provide public access, TLS, or authentication. There is no application-level user login, so an HTTPS reverse proxy must authenticate access to every browser route.

To stop, send SIGTERM to the main bootstrap PID. The bootstrap forwards it to the child host and waits for it to exit. SIGINT does not guarantee the same asynchronous shutdown handling. See Operations for a systemd template and shutdown behavior. noebot itself does not automatically install a service or a conversation-requested restart mechanism.

Accepted arguments are one configuration path, --port PORT (or --port=PORT), and --record-events[=PATH]. There is no application-specific --help. app/host-run.mjs is internal; do not launch it directly. Invalid arguments exit with code 2, startup failures with 1, and dataDir lock contention with 73.

Detailed event recording is OFF by default. Enable it only for diagnostics, for example:

# Automatic filename under workspace/.noe/events/
noe run --no-inst "$NOEBOT_HOME/app/run.mjs" --record-events
# Or an explicit path (create the parent first; records are appended)
# mkdir -p "$HOME/noebot-event-logs"
# noe run --no-inst "$NOEBOT_HOME/app/run.mjs" --record-events="$HOME/noebot-event-logs/session.jsonl"

This is another alternative to normal startup. Put flags after app/run.mjs. Relative event paths are based on the workspace. Recording covers all conversations, jobs, and child agents in the child host. Reset cannot toggle recording; a stop and restart is required. Event logs may contain credentials, capability tokens, notes, code, and other sensitive data. There is no automatic deletion or rotation. Do not share raw logs. Details

Everyday use

Web

  • Conversations: Press Send or Enter to send; Shift+Enter inserts a newline. The existing Ctrl/⌘+Enter send shortcut also works. Use + New at the top to create a conversation, the selector to switch, and Rename to rename it. Ordinary messages sent while answering or running tools are accepted as additional guidance for NOE's next instruction boundary, not immediate edits to generated text. Acceptance is not application or completion. Messages arriving just after native final commit continue in the same conversation. Text and status remain in bounded conversation history; failed/uncertain guidance is not automatically replayed. On an unknown HTTP outcome, inspect history; retrying unchanged text on the same page reuses that message ID. Other conversations and independent jobs can run concurrently.
  • Workspace → Independent jobs: Request a job in a conversation or use Manual job creation. Optional Provider/Model/Effort fields select a model for only that job; leave the identifiers blank and effort auto to use the common configuration. Explicit selections require both identifiers; omitted effort in the API means auto, not the conversation effort. You can also request a model in conversation. No automatic fallback is made if unavailable. Select a job to inspect Launch model / Progress / Result / Notification delivery. Steer adds instructions; Cancel job requests cancellation. Acceptance alone does not mean instructions have taken effect or cancellation has finished. Delete job history can delete only jobs in completed/failed/cancelled/interrupted states.
  • Schedules: Specify a time and task in a conversation, or choose Once / Interval / Cron in the manual form. Once/Interval use RFC3339 times with a UTC offset; Interval uses positive integer seconds. Cron uses five numeric fields in the configured timezone (for example, 0 9 * * 1-5). To change the task or timing, delete and recreate the definition. Disabling or deleting it does not cancel jobs that have already started.
  • Markdown notes: Enter a relative name (such as ideas.md or project/plan.md) and content, then choose Save note. Delete named note deletes the specified note. Names must be safe relative .md names using ASCII alphanumeric and other permitted characters; traversal with .. and symlink access are not allowed. You can also ask to save a note in a conversation.
  • Saved images: View images and descriptions presented in the selected conversation, enlarge images, or insert an image ID. Candidates that have not been presented are not listed.
  • Settings: Choose Auto / Light / Dark for the theme. State updates automatically through SSE/polling. There is no manual Refresh or Web UI Reset button.

A normal Web reload retains the selected conversation while the same host is running, if browser state storage is available. Conversation content and drafts are not saved in browser storage. A new tab normally starts in a separate conversation. Conversation history is held in the host's bounded memory; conversation names, numbers, AI context, and history are not restored after a restart. Explicitly save anything you need in notes or files. Display is primarily plain text, without general Markdown/HTML rendering.

Telegram (optional)

During a normal reply, send ordinary messages without a special command. The acknowledgement confirms host acceptance only. NOE receives guidance at its next model-decision boundary (after an active tool returns if necessary). Reset revokes the old conversation generation. /steer ID TEXT remains an independent-job operation and is not needed for normal conversation guidance.

Add the following telegram object to the required configuration. Replace the IDs with your own values. Pass the bot token securely through the named environment variable, not through JSON.

{
  "telegram": {
    "tokenEnv": "NOEBOT_TELEGRAM_TOKEN",
    "ownerUserIds": ["123456789"],
    "ownerChatIds": ["123456789"]
  }
}

This is an additional fragment, not a complete standalone configuration. Both allowlists are required: a message is handled only when both its sender and chat match. If you do not use Telegram, omit telegram entirely.

When Telegram starts, noebot registers its implemented command names and short English descriptions with setMyCommands, so typing / can show suggestions. This is chat-scoped to ownerChatIds, with no language-specific list; arguments are not completed. Registration is best-effort and does not block normal startup or polling. Suggestions are not authorization: both allowlists still apply, even if other members of an allowed group can see the menu.

Command Action
/start, /help Show the exact syntax
Normal text Chat (history is separate from Web)
/reset Reset the Telegram conversation; does not cancel jobs
/job TEXT, /jobs Create/list jobs with common settings
/job_model PROVIDER MODEL EFFORT TEXT Create a job with its own model; use auto for default effort
/status ID, /result ID Inspect status/saved results
/steer ID TEXT, /cancel ID Add instructions/request cancellation
/notes, /note NAME.md List/read notes
/save NAME.md followed by the body on the next line Save/replace a note
/delete NAME.md Delete the named note
/schedules, /schedule JSON List/create schedules
/schedule_preview JSON Preview up to three occurrences (timing and optional enabled only)
/schedule_enable ID on or off Enable/disable a schedule
/schedule_delete ID Delete a definition (not its jobs)
/images, /image ID List images for the same user/chat; explicitly resend an image

Do not append @bot名 (a bot-name suffix) to commands; commands with a suffix are ignored. If Telegram inserts a suffix when selecting a suggestion (notably in groups), remove it and send the bare command. Client caching or an existing higher-priority/language-specific command list may affect what is displayed. Input is limited to 4096 UTF-16 units. Replies are split, but content beyond 64 chunks is truncated. Bot API acceptance is not a read receipt. A crash may cause ordinary conversation messages or replies to be duplicated.

Images

Ask, for example, “Generate an image and show it,” or “Change the colors of candidate A (image ID …).” You need authentication and access to a NOE image provider/model separately from your conversation model. For example, openai-codex-images / gpt-image-2 is a separate route from openai-chatgpt conversation authentication. A catalog entry alone does not guarantee access. Generation and editing consume the selected route's quota.

Editing an original image and regenerating from text are different operations. Revisions are saved under separate IDs without overwriting the original. Specify an image ID when more than one image could be meant. Saving, AI visual inspection, presentation, and delivery are separate stages. Web available means retrievable; Telegram sent/apiAccepted means API acceptance, not that the user has viewed it. There is no automatic retry after authentication failure or an unknown delivery state, and no unapproved switch to a different paid API. Web/Telegram image uploads and mask editing are not implemented. Image authentication, storage, and delivery details

Important limitations and precautions

  • Permissions and secrets: The workspace is not an OS isolation boundary. Use a least-privilege account and restrict requests, instructions, and files given to the agent to material you trust. Keep credential and environment files in private locations outside the installation/workspace (for example, directories with mode 0700 and files with mode 0600). Do not include them in Git, conversations, notes, or public logs.
  • Restarts and failures: Conversations are lost, and running jobs become interrupted. There is no automatic resume, rerun, or retry of failed notifications. External changes that have already occurred are not rolled back. Schedule times already past when the host starts are skipped, not caught up. A definition does not launch another job while its previous job is still running. Capacity rejection and launch failures are not retried automatically.
  • Stored data and deletion: Jobs/results, schedules, and admission records are in dataDir/state.json; images are in dataDir/images/; job work files are in dataDir/job-work/JOB_ID/. Jobs receive the absolute path to the latter and instructions to use tmp/ and TMPDIR. Their actual cwd remains the workspace. Switching or resetting conversations, completion, cancellation, and history deletion do not delete images or job work files. There is no automatic expiry or GC. Deduplication and other records remain after history deletion. A notification already being sent may arrive after history is deleted.
  • Image ownership: Saved images are tied to their original Web conversation ID or Telegram user/chat and are not automatically shared with other conversations. Image data survives a restart, but old Web conversations are not restored, and their images do not appear in a new conversation's Saved images. There is no recovery UI for old images. Do not expect automatic transfer or discovery in a new conversation.
  • Upgrade compatibility: Current image records use v2. v1 image records (which store absolute paths) are unsupported even in their original location; their presence causes startup to fail with IMAGE_STORE_INVALID. There is no automatic conversion or deletion. Before upgrading, retain the original data and the corresponding old application. Choosing an empty dataDir creates a separate new store; it is not a migration.
  • Locking and backups: flock prevents concurrent use of the same dataDir. Do not delete or rename a live .lock to bypass it. Also avoid sharing the same notesDir concurrently between different dataDirs. Back up, move, or restore only after a full stop. Preserve the entire dataDir, separately located notes, configuration, instructions, and permissions. Manage credentials under a separate private backup policy. Arbitrary absolute paths in saved text, logs, and artifacts are not rewritten automatically.
  • Capacity and guarantees: Displayed conversation history is bounded, while results, images, work files, and other on-disk data accumulate. Monitor disk space. Local test results do not guarantee every provider, real Telegram delivery, or operation on your network, storage, and OS.

The source includes tests, type-checking configuration, and implementation/review records. They are not runtime dependencies and are generally excluded from the distribution tar.

  • Operations: Configuration/APIs, notifications, storage, backups, shutdown, and a systemd template
  • Requirements: Historical initial requirements and design (distinct from current user guidance)
  • In the source: docs/implementation-report.md and docs/image-implementation.md: Implementation and test records
  • In the source: docs/typechecking.md: Prerequisites, scope, and known diagnostics for optional JS/MJS type checking. The presence of configuration does not mean the type checks pass
  • In the source: tests/distribution.py: Distribution allowlist/checksum checks, startup from an external installation, and more. It has prerequisites beyond normal startup, including NOE's thin example and Linux user/mount namespaces

Operations also includes historical environment investigations and proposals. Templates and investigation records do not mean a service has been installed, authenticated, or published in your environment. NOE's separately provided examples/noebot/ is a thin consumer that loads the real installation from an absolute NOEBOT_HOME. For normal use, app/run.mjs as described in this README is sufficient.

License

noebot is provided under the MIT License. See LICENSE for the full text. The copyright notice is Copyright (c) 2026 littleisland. Retain the MIT license text and copyright notice when copying, modifying, or redistributing the software. The software is provided without warranty.

NOE itself, external services, and models are subject to their own licenses, terms, fees, and access permissions. The MIT grant does not confer access to external services or guarantee rights to generated output in all cases.

See efficiency-staging.md for the AsyncStore persistence contract, remaining synchronous work and verification limits.

Role-specific execution budgets

Jobs use limits.executionLimits (defaults: agentStarts=16, queuedTasks=256, providerCalls=256, hookCalls=1024). Conversations use the independent limits.conversationExecutionLimits (defaults: agentStarts=16, hookCalls=1024). Omitted conversation queuedTasks/providerCalls are unlimited over the keepAlive root's lifetime; optional explicit values must be positive safe integers (not zero/null). Per-turn maxSteps, per-request maxTokens, maxHostTasks and job concurrency limits remain enforced. See docs/operations.md for details.