Connect a task project

This page shows how to connect a site's code repository to the shared Tasks board, so people and agents working in that checkout read and update the tasks you see. Use it for a new project, or for an existing project whose checkout has moved.

A task project is one site's list of tasks. Every project is stored in the installation's one task database, which runs in the dolt container of the stack, and every task id starts with its project's short prefix, such as ex-a1b2. The site's checkout is the copy of its code repository on your machine, where you and your agents work. Connecting the two means anyone working in that checkout sees and changes the same tasks that the Tasks page shows. The task model comes from Beads, and bd is its command-line tool.

Before you begin

NoticeOS keeps one shared task database for the whole installation. Every project you connect gets its own list inside it, identified by a short prefix. Status, owners, blockers and approvals are stored in one place.

A new installation already includes a NoticeOS task project, so Tasks works before you add a website. See Tasks for the board itself.

You need:

• The site added in NoticeOS. See Add your first site. Its site id, its task prefix and its task database are three different names; the examples below use example.com, ex and ex_tasks.
• A clean checkout of the project's code repository, on the machine that holds the task database, with no .beads/ folder yet.
• The task tool bd, the native version named in Install from source. An agent's Docker bd wrapper cannot initialize a project.
• The task database running: Settings > Task projects shows Available.

On a hosted installation the section shows a Read-only here chip and the list cannot be edited, because the commands have to run on the machine that holds the task database.

Add the project in Settings

1. Open Settings and select Task projects.
2. Read the Task database line. It should show Available with a project count. Unavailable or Stale means the task database is not responding; fix that first.
3. In the Projects table, select Add and fill in three cells:
   • Site: the site from the list. Only sites with no project yet are offered.
   • Prefix: two to eight lowercase letters, such as ex. Every task id in the project starts with it. It must be unused.
   • Database: a name starting with a lowercase letter, using lowercase letters, digits or underscores, such as ex_tasks. It must be unused.
4. Save the row. It is saved at once, with Undo, and a checklist opens under the table, headed example.com is mapped with the number of steps left.

Saving the row only records the mapping. The database does not exist yet, the code repository is not connected to it, and no agent has access. The checklist lists the steps that remain.

Run the checklist steps

Each step has a title and a block to copy, labelled with where it goes.

1. Initialize a new task database: select Copy, then run the command in a terminal inside the project's checkout.
2. Keep it on the shared database: copy the two lines, shown as a diff, into .beads/config.yaml in the checkout. They stop the checkout from pushing its tasks anywhere else or importing stale copies. This step only appears when the first command does not already do it.
3. Prepare project instructions: select Copy, then run the command in a terminal inside the checkout.
4. Link the checkout here: copy the JSON entry into the installation's task-host.json under repositories, replacing /path/to/checkout with the real path.
5. Select Done to close the checklist.

What initializing does

On a source installation the command runs the installation's own helper, scripts/dolt-project.mjs. It creates only the new database and connects the checkout to it. It keeps the repository's hooks and agent instructions, turns off automatic imports and Git operations, and stops without changing anything if the database already exists, the checkout has uncommitted or untracked files, or a .beads/ folder exists.

If it fails or you are unsure whether it finished, keep its files and the database as they are and recover deliberately. Do not retry with bd init. On an installation you did not just create, agree the exact new database with its owner before you run it.

What the project instructions step does

Prepare project instructions writes a marked NoticeOS section into the project's AGENTS.md, and into CLAUDE.md when that file already exists. The section contains the task rules an agent working in that repository follows, and links back to your NoticeOS checkout. It keeps the project's existing instructions, excludes .beads/ and .beads.gate.lock from Git, and creates the private lock file. It stops without changing anything if the files already hold conflicting task instructions, or if task connection files are already tracked in Git; resolve either by hand.

It contacts no provider and no database. To see the proposed changes first, run it from the NoticeOS checkout with --check:

pnpm project:prepare -- --repo /absolute/project-checkout --check

Review the diff, then add the project's own goal, architecture, verification commands, protected operations and dated state, following the site context mapping. Commit the instructions under the project's own Git policy. Never commit .beads/ or any credential.

If the NoticeOS checkout moves later, the link in the marked section points to the old location. The preparation command stops when the marked section has been changed, so fix the link by hand.

Where the checkout link goes

On a source installation the file is <installation-folder>/installation/task-host.json, shaped { "version": 1, "repositories": [...] }. Keep the existing entries and use exactly the three names you saved:

{
  "asset": "example.com",
  "prefix": "ex",
  "database": "ex_tasks",
  "repo": "/absolute/project-checkout"
}

On the prepared container, repo is the container path, such as /spokes/example: the installation's task-repository folder (NOTICEOS_SPOKES_DIR in installation.env) is mounted at /spokes, so the checkout must be inside that folder. To mount another folder, change that line and run pnpm os:apply; that is a host-administrator step. The host-link contract and the container guide have the details.

This link is what lets the product read the checkout's tasks, run local task actions in it and keep them backed up.

Work from the checkout

Agents on this machine reach the project's tasks through the installation's MCP server, with no task tool of their own; see Connect an agent. A person without bd installed runs it inside the app with pnpm os:bd -- <command>.

People and agents can also use bd in the project checkout. On a source installation, point it at the installation's credential file first:

export BEADS_CREDENTIALS_FILE=/absolute/noticeos-installation/dolt/credentials
export BEADS_DOLT_AUTO_START=0
bd ready
bd list

Keep the credential file private. Never paste its contents into source or a command.

An agent that runs bd through the Docker adapter needs the exact host checkout allowed in the adapter's spokes list; see the bundled client declaration. Keep its image, network, credentials and other project paths as they are.

Connecting a project gives people and agents a shared list. It grants no agent any right to deploy or change the site. In this release, agent work remains manual.

A project that already has tasks

Do not run Initialize a new task database and do not run bd init. Find the project's original service, database, prefix and project identity, and save the row with those exact names. Restore only the connection settings into a new private .beads/ folder and its config.yaml; never import an old JSONL export or copy a local task database into it. The steps are in Moving a maintainer checkout.

Moving a project from one task database server to another is a migration, which this page does not cover. Keep the project on the old server until that migration has its own evidence and approval.

Verify

• From the project checkout, bd ready and bd list run without error. A new project correctly returns no tasks; an existing one returns its known tasks with their original prefix.
• On Tasks, the Project filter lists the site, and its rows show the prefix.
• On Settings > Task projects, the Found column stays blank for the row.
• In the project repository, the instructions are committed and .beads/ is untracked.

To check an installation you did not just create, ask its owner first, and never file a test task in a live board to prove the setup.

If it didn't work

• The Task database line shows Unavailable or Stale: the task database is not responding. Start it, then come back.
• The Found column shows a warning dot, with example.com is not being backed up under the table: no database by that name exists. Select Edit name to fix the cell, or copy the Keep command to create it.
• The Initialize a new task database command stops with an error: the database already exists, the checkout has uncommitted or untracked files, or it already has .beads/. Commit or stash, or follow A project that already has tasks.
• Tasks shows 1 project could not be read and the site's name: point at the name to see the reason, then check the task-host.json entry and, on the container, its mount.
• bd fails in the checkout: check the credential file, or the Docker adapter's spokes list.

Never start a second task database server, use br, or run bd dolt push or bd dolt pull as a repair. Follow the installation's task database recovery. More symptoms are in Troubleshooting.

Next steps

• Connect an agent
• Connect data sources
• Tasks
• Tasks and agents