orbit

Orbit is a lightweight, self-hosted personal knowledge and planning tool.

It is built for people who like the idea of a personal knowledge system but do not want to maintain a complex collection of databases, properties, plugins, and separate apps. Orbit keeps the loop intentionally small: write something down, turn it into a task or event when needed, and file it with PARA when it becomes useful.

Notes, tasks, and calendar events live in the same Markdown vault. The core works without an AI provider, and the next major layer is optional AI that helps you find and organize your own information without silently rewriting it.

What works today

Not implemented yet: built-in AI, AI-assisted organization, a review screen for AI changes, calendar sync, automatic backups, multi-user collaboration, or a remote HTTP MCP endpoint.

Related MCP server: Knowledge Base MCP Server

The workflow

Capture -> Today / Tasks / Calendar -> PARA when useful -> Archive
                  |
              Markdown files
                  |
             Web UI and MCP

PARA is a filing policy, not a structure you must maintain before you can write. Inbox holds unprocessed notes and links. Confirming an item as a task or event removes it from Inbox; manage it in Tasks or Calendar. Tasks do not require a project or date. When an item gains a clear context, move it into a Project, Area, or Resource. The organize tray and task location picker share folder search, expandable folders, and recent destinations. Clicking a folder only browses; use the explicit move button after checking the path, or drop an item on its destination. Holding a dragged item over a folder expands it; list edges scroll automatically. Undo item creation, deletion, archiving, moves, completion, type conversion, date changes, and color changes from their notifications or with Cmd+Z / Ctrl+Z outside text editors. The current session retains up to 200 item actions; undo restores only values changed by that action. Text editing uses the editor’s own undo history.

Quick start

Requirements: Node.js 22 or later and pnpm 10 or later.

git clone https://github.com/kmelon55/orbit.git
cd orbit
pnpm install
cp .env.example .env
pnpm dev

By default, Orbit stores private data in ./vault, which is excluded from Git and Docker build context. For real use, point Orbit to a directory outside the source repository:

ORBIT_VAULT_DIR=/absolute/path/to/orbit-vault
ORBIT_AUTH_USERNAME=orbit
ORBIT_AUTH_PASSWORD=replace-with-a-long-random-password

ORBIT_DATA_DIR remains available for backward compatibility. Authentication may be omitted during local development. Production fails closed unless both authentication variables are configured. ORBIT_AUTH_SESSION_DAYS can change the default 180-day session lifetime to a value from 1 to 365.

Your data

Markdown and YAML frontmatter are the source of truth:

ORBIT_VAULT_DIR/
├── inbox/
├── projects/
├── areas/
├── resources/
├── events/
├── whiteboards/
└── archive/

Tasks are not stored in a separate task database. A Markdown item with type: task can live in Inbox, a Project, or an Area, and Orbit projects it into Today, Tasks, and Calendar. Unknown frontmatter is preserved when Orbit rewrites a note.

See the architecture for the file contract and the vault guide for deployment and backup boundaries.

MCP

Orbit includes a local stdio MCP server. It is a real adapter over the same vault as the web application; it is not a hosted endpoint and does not use the web login session.

ORBIT_VAULT_DIR=/absolute/path/to/orbit-vault pnpm mcp

Example client configuration:

{
  "mcpServers": {
    "orbit": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/orbit", "mcp"],
      "env": {
        "ORBIT_VAULT_DIR": "/absolute/path/to/orbit-vault"
      }
    }
  }
}

Available tools:

• orbit_capture

• orbit_today

• orbit_inbox

• orbit_list

• orbit_read

• orbit_file

• orbit_create_folder

• orbit_calendar

• orbit_search

The MCP process has direct read/write access to the configured vault. Run it only from a client and machine you trust.

Docker

docker build -t orbit .
docker run --rm -p 3000:3000 \
  -e ORBIT_VAULT_DIR=/vault \
  -e ORBIT_AUTH_USERNAME=orbit \
  -e ORBIT_AUTH_PASSWORD='replace-with-a-long-random-password' \
  -v orbit-vault:/vault \
  orbit

The application directory is disposable; /vault is the persistent data boundary. Put TLS in front of the container for any network deployment.

Roadmap

The next milestone is not more workspace machinery. It is a small, reviewable AI layer on top of the working personal system:

1. Add bring-your-own-key AI provider settings.

2. Search, summarize, and ask questions across notes, tasks, and events.

3. Suggest titles, tags, dates, and PARA destinations.

4. Show every proposed file change before it is applied.

5. Add dependable file watching, snapshots, and restore flows.

6. Add calendar import/export and sync only after the local calendar contract is stable.

See the detailed roadmap.

Orbit is deliberately not trying to become a team wiki, a database builder, a plugin marketplace, or an autonomous agent that continuously reorganizes your files.

Development

pnpm test       # Biome, TypeScript, and unit tests
pnpm build      # production build
pnpm mcp        # local stdio MCP server

See CONTRIBUTING.md before opening a change.

Principles

• The files are the product data, not merely an export format.

• Notes, tasks, and time belong in one small personal loop.

• Capture should require less effort than organizing.

• AI is optional and proposes changes for review.

• Self-hosting should remain understandable: one app, one vault, no required database.

License

MIT