- JavaScript 57.4%
- Python 40.7%
- CSS 0.9%
- HTML 0.8%
- Shell 0.2%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| app | ||
| assets | ||
| docs | ||
| public | ||
| scripts | ||
| tests | ||
| .gitignore | ||
| config.example.json | ||
| LICENSE | ||
| README.ja.md | ||
| README.md | ||
| tsconfig.browser-checks.json | ||
| tsconfig.noe-checks.json | ||
| VERSION | ||
noebot
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.
- Repository: littleisland/noebot
- License: MIT
- Detailed configuration, APIs, storage, and administration: Operations (English)
Contents
- Features
- Prerequisites
- Installation
- First use: provider setup and smoke check
- Paths and configuration
- Running, stopping, and diagnostics
- Everyday use
- Important limitations and precautions
- Development and related documentation
- License
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
noeon PATH for both the launching process and its children - util-linux
flockwith--no-fork -n -Esupport - A filesystem supporting native file and directory
fsyncfor 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 withpwd -Por a similar command. It need not be the installation directory; you can select any existing project.timezone: An IANA timezone such asAsia/TokyoorEtc/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 ofauto,none,minimal,low,medium,high,xhigh, ormax.
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:
- Open the Web UI at the printed URL, send a normal message, and wait for the answer to finish.
- Ask: “Create an independent job that checks only the current working directory and project name. Do not modify any files.”
- In Independent jobs, confirm
completedand 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.mdand.noe/instructions/are not read implicitly. SetinstructionDirs.appto 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
Enterto send;Shift+Enterinserts a newline. The existingCtrl/⌘+Entersend 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/interruptedstates. - 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.mdorproject/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 indataDir/images/; job work files are indataDir/job-work/JOB_ID/. Jobs receive the absolute path to the latter and instructions to usetmp/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
.lockto 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.
Development and related documentation
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.mdanddocs/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.