---
url: https://docs.notice.cx/guides/keep-tasks-in-ntasks.md
description: >-
  Connect the Ntasks task hub that holds an installation's tasks, so the Tasks
  pages and the runner read and change them there, and connect agents to Ntasks
  directly.
---

# Keep tasks in Ntasks

[Ntasks](https://github.com/notice-cx/Ntasks) is a task hub that runs as a Cloudflare Worker. An installation's tasks live in the Ntasks it is connected to, and the installation reads and changes them there:

* the **Tasks** pages;
* the runner's task snapshot, which the Home and the TV dashboard show, and the reviews and comments the runner files.

Agents read and change the tasks through Ntasks's own MCP endpoint ([below](#agents)). Ntasks is connected on standalone installations only.

## Before Ntasks is connected

A new installation from `pnpm os:setup` has no task service; setup takes no Ntasks address or credential. Until one is connected:

* each **Tasks** page shows **Connect Ntasks**, and **Go to Task projects →** opens **Settings** > **Task projects**;
* the runner files no task snapshot, no panel review and no outcome review;
* NoticeOS's MCP server lists no task tools, and its instructions and its `get_task_guide` name **Settings** > **Task projects**;
* the nightly backup holds no tasks.

## Before you begin

* Ntasks has a project for each site whose tasks this installation shows, with the site's task prefix.
* From Ntasks, a **service credential** made after the tasks are loaded, with access to each project this installation uses. Ntasks fixes the credential's project access when it is made. A site added later needs a credential that also reaches its project.
* For a local customer profile with backups configured, the Ntasks workspace ID and a second credential with only the backup choice (`"backup": true`). A standalone installation can continue using one credential with project access and the backup choice.
* The address Ntasks answers at. HTTPS is required, except for a local address such as `http://host.docker.internal:8787`.

## Connect

1. In **Settings** > **Task projects**, choose **Connect** beside **Ntasks**.
2. Enter the **Ntasks address** and the **Service credential**. With a separate backup credential, also enter the **Ntasks workspace ID** and the **Backup credential**. Choose **Connect**. The panel shows how many projects the service credential reaches.
3. In **Projects**, each row's **Ntasks project** column shows the Ntasks project that holds that site's tasks. A site maps to the Ntasks project with the same task prefix. **No project with this prefix** means the credential reaches no project with that prefix: make a new credential in Ntasks that also reaches that project and replace the old one with **Manage**, or correct the row's **Task prefix**.

The credentials are kept encrypted in the installation's store, like every other connection on **Integrations**. The app opens each credential for the operation it authorizes. **Manage** replaces or disconnects the connection. The **Tasks** pages show **Connect Ntasks** when the service is disconnected.

## Agents

While Ntasks holds the tasks, NoticeOS's MCP server (`pnpm os:mcp` and the Tower's `/api/mcp`) lists no task tools. Agents connect to Ntasks's MCP endpoint, the Ntasks address followed by `/api/mcp`, and use its task tools and its `get_task_guide`. For Claude Code:

```sh
claude mcp add --scope user --transport http ntasks https://ntasks.example.com/api/mcp
```

On first use, a person must allow the agent in Ntasks. NoticeOS's server keeps its asset report, panel and journey tools; its instructions and its `get_task_guide` name the Ntasks endpoint, and a task tool an agent listed before the switch is refused with the same address.

## Who Ntasks records

The Tower and the runner make their changes through the installation's one credential. Each request names who it is for, and Ntasks records the change as `service:<credential name>/<name>`: a change made on the Tower's pages is recorded as `service:noticeos/tower`. The Tower's task boards, task pages and Wall show such a change under the name after the credential's, `tower`, and the task's history in Ntasks keeps the full name. An agent connected to Ntasks is recorded under its own Ntasks sign-in, such as `agent:Claude Code (ntasks)`. The Tower and the Wall show every spelling of one agent under one name, such as Claude Code or Codex, and every spelling of one model under one name, such as Claude Opus 5.5 for `claude-opus-5-5`, by the naming rule Ntasks applies; each task keeps the actor and model as recorded.

## Decisions and approvals

Ntasks takes an answer, a choice, a dismissal, an approval or a dispute only from a person signed in to Ntasks, never from the installation's credential. The Tower registers itself in Ntasks as a [connected app](https://github.com/notice-cx/Ntasks/blob/main/docs/sign-in.md#connected-apps), and each person signs in to Ntasks from the **Tasks** page once in each browser. The **Tasks** page is the Ntasks web app ([Tasks](/tower/tasks)), and every read and decision on it is sent from their browser to Ntasks with their own sign-in, and Ntasks records each one under their name and the Tower's client ID. The Tower's server never holds a person's sign-in.

### Register the Tower in Ntasks

The first **Sign in to Ntasks** on an installation registers the Tower in Ntasks as a connected app, with the installation's service credential, and saves the Tower's client ID with the connection. **Sign in** on the **Tasks** page and **Sign in to Ntasks** on the **Ntasks** row of **Settings** > **Task projects** both do it. Registering the Tower needs Ntasks with service registration of connected apps ([Ntasks sign-in](https://github.com/notice-cx/Ntasks/blob/main/docs/sign-in.md#registering-an-app-from-a-service)). The Tower registers the address the browser is on, followed by `/tasks/signed-in`, as its redirect address, so each address the Tower is opened at, such as `http://localhost:5173` and `http://tower.local:5173`, is its own app in Ntasks, and each browser keeps the one for its address. That address uses `https`; `http` works on `localhost`, `127.0.0.1` and `[::1]`, and on a home network: a `.local` name or a private IP address. Ntasks holds a home-network `http` address until a workspace owner allows it: the owner presses **Sign in to Ntasks** at that address and chooses **Allow** on the Ntasks page that opens ([Ntasks: an app on a home network](https://github.com/notice-cx/Ntasks/blob/main/docs/sign-in.md#an-app-on-a-home-network)). Until then the **Tasks** page and **Settings** > **Task projects** show where the owner allows it under **Sign in to Ntasks**. When Ntasks answers the registration with an error, the Tower shows a sentence naming the cause and saves nothing.

For an Ntasks that cannot register the Tower, **Register the Tower by hand** on the **Ntasks** row shows the redirect address to copy:

1. In Ntasks, as an owner of the workspace the service credential belongs to, open **Settings** > **Connected apps**, choose **Register app**, name the app, paste the redirect address and register it. Copy its **client ID**.
2. Back in **Settings** > **Task projects**, choose **Manage** beside **Ntasks**, then **Replace connection**, and enter the **Ntasks address**, the **Service credential** and the **Tower client ID**, then **Connect**.

### Sign in and decide

* A browser not signed in sees **Sign in to see your tasks** on the **Tasks** page. **Sign in** there, or **Sign in to Ntasks** in **Settings** > **Task projects**, opens Ntasks's page that names the Tower and what it may do; after **Allow**, the browser returns to the page it started from. Sign-in needs Ntasks with HTTP API version 2 or later, including after the Tower registers itself.
* The sign-in lasts in that browser across reloads. The **Ntasks** row of **Settings** > **Task projects** shows the person's Ntasks name and **Sign out of Ntasks**, which removes the sign-in from that browser. Revoking the Tower's access for everyone stays on Ntasks's **Connected apps** page.
* When Ntasks no longer accepts the sign-in, such as after **Revoke**, the **Tasks** page asks to sign in again.
* Ntasks stops a decision sent through the Tower's own task routes with the installation's credential, and the Tower shows Ntasks's refusal.

## While Ntasks does not answer

* The **Tasks** pages show the copy Ntasks last gave, with **Ntasks is not answering** and the time it was read. They offer no actions until it answers.
* A comment or a close that could not be sent keeps its text in its box. When Ntasks did not answer, the refusal ends with **Nothing was saved.** When Ntasks did not answer in time, it ends with **The change may have landed; reload before sending it again.** instead, because the change may have been saved.
* A change Ntasks answers but does not offer yet is refused with **Ntasks does not accept this change yet, so nothing was saved.**
* While the installation's ingest has not said where its tasks live, a change is refused and the runner files no task snapshot.
* The runner files no new task snapshot, so Home keeps the last one with the time it was taken.

The copies are kept under `.local/task-cache` in the installation's home folder.

## The nightly backup

While Ntasks is connected, the nightly backup and `pnpm os:backup` export the connected Ntasks workspace and keep it in the backup set as `ntasks/backup.json`. The set's `RESTORE.md` and the backup report list the rows of each table.

The backup is incomplete, with its **Task hub** part failed, when:

* Ntasks does not answer;
* the credential was not made with the backup choice;
* Ntasks was written to during each of three reads of the store. Run `pnpm os:backup` again when agents are quiet.

The backup's line in the runner's log, and its record on the Tower, name the reason.

To restore, use an Ntasks checkout of the version the backup was taken from: `node tools/migrate/src/cli.ts restore --from ntasks/backup.json --store restored.sqlite` loads the file into a new store copy and compares the two.

## How the snapshot stays current

Once a minute the runner reads Ntasks's change feed from where it last stopped, at most 1,000 changes per minute. It rereads the boards of each project the feed names, and of any project whose boards are more than 15 minutes old, together with every task of that project carrying a handoff or panel-review label, closed at any time. The task snapshot is built from those reads, so a finding card shows its task and a site shows its panel triage. Where Ntasks does not answer the label read, the card shows the task as not asked.

While Ntasks is connected, the runner files panel reviews and outcome reviews in Ntasks and posts each outcome's result as a comment there, recorded as `service:<credential name>/os-up-panel-filer`, `/outcome-review-filer` and `/outcome-task-updates`. A panel review filed there carries its due date, so the connected Ntasks must take `dueAt` on a new task; one that does not refuses the filing, and the runner logs the refusal. While the installation's ingest has not said where its tasks live, the runner files nothing and results stay queued.
