How to Use Nixsites: The Beginner's Guide (One Workspace, nixctl + MCP)
CodexFuse Team · 2026-11-02T14:00:35.340Z · 16 min read min read
Nixsites is the self-hosted AI workspace where notes, tasks, habits, calendars, spreadsheets, files and AI chats live in one item tree. This beginner's guide covers install, your first workspace, nixctl, the MCP server, and imports.
Learning how to use Nixsites starts with one mental shift: stop thinking of your notes, tasks, habits, calendar and AI chats as separate apps, and start thinking of them as one item tree you can look at in many different ways. Nixsites is a free, open-source, self-hosted workspace where people and their AI agents work together — notes, tasks, habits, calendars, spreadsheets, files and automations all living in one place (github.com/sianachi/nixsites, README intro). It launched on October 19, 2026 as a 7-star side project, and the reason this nixsites tutorial exists is that nobody had written a proper independent beginner walkthrough yet. This one covers the whole arc: the one-tree lesson, installing it on your own machine, your first workspace, the item-tree tour, the nixctl CLI and MCP server for AI agents, and the import/export story that keeps your data yours. You will need a machine with Docker installed — our Docker beginner guide gets you set up if you have not installed it yet.
What Is Nixsites, Exactly?
Nixsites (called "Nix" in its own branding — and no, it has nothing to do with the NixOS package manager, which is the noise filling Google results for this term) is a self-hosted workspace that keeps notes, tasks, habits, calendars, spreadsheets, files, automations and AI chats in a single item tree. Its own one-line description is: "Self-hosted tool for managing notes, tasks, calendar, habits and the rest of life in one place." The full README intro reads: "Nix (nixsites) is a free, open-source workspace where people and their AI agents work together: notes, tasks, habits, calendars, spreadsheets, files and automations in one place."
What makes it different from Notion or Obsidian is not the feature list — it is the authorization architecture. Permissions are enforced by Postgres row-level security, so the web app, the CLI and the MCP server all share one authorization path. In plain terms: when your AI agent connects over MCP, it physically cannot reach anything you could not reach yourself. The README puts it this way: "Safe by construction. Permissions are enforced by Postgres row-level security, and the web app, CLI and MCP server share one authorisation path."
How Do You Use Nixsites, Step by Step?
You use Nixsites in five arcs, and together they make it a complete self-hosted AI workspace: install the stack on your own machine, sign in and meet your first workspace, build an item tree instead of opening apps, drive everything from nixctl or an MCP-capable agent when you want automation, and move your data in and out freely. Each arc is covered in detail below.
- Install: run the one-line installer and give Docker about 8 GB of memory. The installer brings up Postgres, RabbitMQ, an object store and a Zitadel identity provider behind Caddy, which fetches TLS certificates itself.
- Sign in: open your workspace URL and sign in with the one-time admin password the installer prints. Change it immediately.
- Build the tree: create items (notes, tasks, habits, AI chats) and arrange them with containers and 16 switchable views instead of separate apps.
- Automate: issue an access token in Settings and use nixctl for scripting or connect the MCP server so your coding agent can work in the workspace with your exact permissions.
- Import and archive: bring your Markdown folders, Obsidian vault, DOCX or PDF files in; export lossless .nix archives for backups.
What Does "One Tree, Many Views" Actually Mean?
"One tree, many views" means a body (a note, a canvas or a spreadsheet) is stored once as an item in a tree, and that item's children can be displayed in any of 16 view types — list, board, calendar, timeline, gallery, spreadsheet, chart, habit tracker or finance ledger among them. The README's verbatim formulation is: "One tree, many views. A body (note, canvas or spreadsheet) is separate from how its children are shown: list, board, calendar, timeline, gallery, spreadsheet, chart, habit tracker, finance ledger."
There is no special folder type: a note can contain sub-notes, a canvas can contain tasks, and a spreadsheet can contain a reading list. The 16 documented views are List, Board, Calendar, Gallery, Timeline, Spreadsheet, Form, Interactive form, Smart list, Chart, Checklist, Matrix, Outline, Drive, Habit tracker and Finance. The key guarantee — again verbatim — is that "views never copy items; they are different ways of reading the same children." So a board grouped by status, a calendar placed by due date and a chart totalling your budget by status can all be different views of the exact same container.
This is the mental model that replaces five apps. Your morning planning can be a board; your weekly review can be a timeline; your money can be a finance ledger — all reading the same underlying items.
How Do You Install Nixsites?
You install Nixsites with a single command, and with no argument it is a try-out on your own machine. The production install command, verbatim from the docs, is:
curl -fsSL https://raw.githubusercontent.com/sianachi/nixsites/main/deploy/install.sh | bash
For a real install behind a public domain, the same script takes an origin:
curl -fsSL https://raw.githubusercontent.com/sianachi/nixsites/main/deploy/install.sh | bash -s -- https://nix.example.org
The script needs Docker with the Compose plugin, plus curl, openssl and jq. It stops if a tool is missing and warns when Docker has less than about 8 GB of memory — budget that much. Behind the scenes the installer starts PostgreSQL, RabbitMQ, the object store and the bundled Zitadel identity provider behind Caddy (which fetches TLS certificates itself), registers the web application with the identity provider, runs the database migrations and the identity bootstrap, then prints the administrator sign-in: an address like [email protected].yourhost plus a one-time password you must change at first sign-in. There is no fixed default password — this is a deliberate security choice.
A developer stack also exists (git clone, then pnpm dev on localhost:5173, with a development identity provider and mail catcher), but note a docs discrepancy at write time: the dev docs say git clone https://github.com/sianachi/Nix.git while the live repo is github.com/sianachi/nixsites — clone the latter. The try-out opens at http://nix.localhost in Chrome or Firefox; Safari users add 127.0.0.1 nix.localhost auth.nix.localhost to /etc/hosts. If you plan to host it on a server instead of your laptop, our explainer on what VPS hosting is covers the basics of getting a machine for it.
Install routes, compared
| Route | Command shape | Best for | Cost |
|---|---|---|---|
| One-line try-out | install.sh | bash (no argument) | Evaluating on your own machine at nix.localhost | Free |
| Real install | install.sh | bash -s -- https://your-domain | Self-hosted production with TLS handled by Caddy | Free (plus your server) |
| Dev stack | git clone github.com/sianachi/nixsites + pnpm dev | Contributing or extending the code | Free |
| Live demo | nixsites.com demo link (see the docs homepage) | Trying it without installing anything | Free |
What Does Your First Workspace Look Like?
Your first workspace is created for you the moment you first sign in — a personal workspace you can later multiply, share with other people and move items between. The rail down the left edge holds your destinations: Notes, Daily notes, Calendar, Graph, Bookmarks, Smart lists, Templates, Automations, Import, Trash, the Pet and Settings (yes, the Pet — the developers put a companion creature in the rail). Pressing Mod+K opens search and commands from anywhere.
The workspace tree shows your items; the item screen shows the selected item's body and, below or beside it, its views. Hitting New in the sidebar offers six things: Note, Canvas, Sheet, Upload files, Structured, or From a template. Today opens the note for the current day, filed under Year and Month folders, and a quick-capture dialog appends to it. Containers carry fields for the items inside them — flip the same container from a board grouped by Status to a calendar placed by Due to a chart totalling Budget by Status, and you have seen the whole "one tree, many views" idea in about thirty seconds. From the workspace settings you can invite people with the roles owner, editor or viewer.
If you are coming from an AI video-agent workflow, the same unified-tree idea applies to your agent's context — our OpenFilm beginner guide covers the open-source AI video agent side of an agent-centric setup.
How Does nixctl Work?
nixctl is how you drive your workspace from a terminal or a script, and its commands are deliberately mundane: list workspaces, list items, create items, read a note, set a property, query a view. It is not a standalone binary at this stage of the project — it runs from the repo checkout, and the docs recommend an alias:
alias nixctl='pnpm --dir /path/to/Nix --filter @nix/cli exec node --experimental-strip-types src/index.ts'
It needs Node 22 or later. Authenticate against your server with:
nixctl auth login --api-url https://your-domain
Tokens are created in the web app under Settings > Access tokens, with independent read, write and admin scopes and a required expiry between 1 and 365 days; profiles live in ~/.config/nixctl/config.json. Then the useful everyday commands, verbatim from the nixctl basics page:
nixctl ws list nixctl item ls --workspace <workspace-id> nixctl item create --workspace <workspace-id> --title "Reading list" --parent <item-id> nixctl props set <item-id> status=Active budget=1200 nixctl note read <item-id> --raw > note.md nixctl import ./notes --workspace <workspace-id> --dry-run nixctl export <item-id> --format nix --scope subtree -o backup.nix nixctl remind set <item-id> +2h
There are more — item get, schema get, views get, query, history list and automations list — but those eight will carry a beginner through the first week. The project is two weeks old at write time, so verify the install path and flag set against the current repo before memorizing them.
How Do You Connect an AI Agent via MCP?
You connect an AI agent by running nixctl mcp, which starts a Model Context Protocol server over stdio so any agent tool that speaks MCP can work in your workspace. The docs are explicit about the security story: it runs as you, with your profile's token, and can never reach further than you can — that is the row-level-security authorization path doing its job. Point your MCP client at nixctl:
{ "mcpServers": { "nix": { "command": "nixctl", "args": ["--profile", "default", "mcp"] } } }
This is where Nixsites' "workspace for people and their AI agents" tagline becomes concrete: instead of your agent reading and writing files that drift out of sync with your notes, it reads and writes the same item tree you click through in the browser. If your agent workflow also involves long coding sessions, our Kompressor beginner guide shows how to keep context-window costs down with deterministic prompt compression for coding agents.
One honest caveat from the docs: every peer-message mechanism has a trust boundary, and here the boundary is you — the agent inherits exactly your permissions, nothing more and nothing less. Plan your token scopes (read vs write vs admin) the way you would plan file permissions.
How Do You Import Your Old Notes — and Get Them Out Again?
You import with nixctl or from the Import destination in the rail, and the anti-lock-in story is one of Nixsites' best features. The documented import table, verbatim:
| Source | What arrives |
|---|---|
| Markdown files and folders | Editable notes; folders keep their hierarchy |
| An Obsidian vault | Notes, folders and attachments, imported once |
| Word documents (DOCX) | Editable notes, with the original file kept as a child |
| Editable notes from the text, with the original kept as a child | |
| UTF-8 text | Editable notes |
| Nix archives (.nix) | The archived items, bodies, properties and views |
| Bank statements (CSV) | Imported from the finance view |
A .nix archive is the lossless escape hatch: "A lossless archive of items, bodies, properties, views and files that Nix can import again." The docs add the honest qualifier that a .nix archive "is a portable copy of your content, not a database backup" — for disaster recovery you back up ~/nix/nix.env together with the Docker volumes (nix-*), because the env file holds every secret and cannot be regenerated. Use nixctl import ./notes --dry-run first to preview what an import will do.
Nixsites vs AppFlowy: Which Should You Pick?
Nixsites is not AppFlowy, and the difference is the axis they are built on: AppFlowy is an open-source Notion clone, while Nixsites is an AI-native unified workspace. AppFlowy's own tagline is "The Open Source Alternative To Notion" and its mission statement reads: "To individuals, we would like to offer Notion's functionality, data security, and cross-platform native experience." It is block-based pages and databases, built with Flutter and Rust, positioning itself against Notion's look and feel. Note that AppFlowy is not mentioned in Nixsites' own comparison table (which covers Notion, Obsidian, Anytype and AFFiNE), so this row is built from each project's self-description — the fair basis.
| Nixsites | AppFlowy | |
|---|---|---|
| Core idea | One item tree; notes, tasks, habits, calendars, spreadsheets, files and AI chats as items with 16 interchangeable views | Block-based pages and databases modeled on Notion |
| AI story | First-class: AI companion, nixctl CLI, MCP server, Postgres row-level security shared by web/CLI/MCP | AI workspace positioning ("achieve more without losing control of your data") |
| Stack | ASP.NET Core 10, Postgres 16 (pgvector, RLS), React 19, Node 22 collab (CRDT over WebSocket), Go workers | Flutter, Rust |
| License | AGPL-3.0-only from v0.5 (MIT up to v0.4.x); commercial licence available | Open-source (per its README) |
| Self-hosting | Fully self-hostable via the one-line installer | Self-hosted server has moved to an open-core model — free self-hosting now covers one user seat (reported 2026-10-27) |
| Data portability | Lossless .nix archives (items, bodies, properties, views, files) + standard exports | Standard exports |
Pick Nixsites if you want one authorization path covering a web app, a CLI and your AI agent. Pick AppFlowy if you want a Notion-shaped workspace with native Flutter/Rust apps. Our AppFlowy beginner guide walks through that side in the same format as this article.
What Are the 7 Mistakes Every Nixsites Beginner Makes?
These seven come from the docs' own warnings and sharp edges, not from invention.
| Mistake | What happens | Do this instead |
|---|---|---|
| Searching "nixsites" on Google and expecting relevant results | You get the NixOS package manager, a menstrual-disc brand and a lice treatment | Bookmark the docs at nix.nixsites.com and the repo github.com/sianachi/nixsites; use exact-phrase search with quotes |
| Skipping the Docker memory check | The installer stops or the stack runs badly | Give Docker about 8 GB before running install.sh — the script warns you |
| Losing the one-time admin password | There is no fixed default to fall back on | Copy it when the installer prints it and change it at first sign-in |
| Backing up only the database | You lose the secrets in ~/nix/nix.env, which cannot be regenerated | Back up nix.env together with the Docker volumes (nix-*) |
| Using the stale clone URL from the dev docs | You clone a URL that does not match the live repo | Clone github.com/sianachi/nixsites, not sianachi/Nix |
| Giving the agent an admin token when read is enough | Your agent inherits exactly your token's scope — full write everywhere | Issue read-only tokens for agents that only need to read; scope per use |
| Confusing Nixsites with AppFlowy | You evaluate it as a Notion clone and miss the point | Evaluate the item-tree + MCP authorization story, not the page editor |
Is Nixsites Production-Ready in November 2026?
Nixsites is two weeks past its launch editorial and is moving fast — treat it as a promising self-hostable project, not a finished product. The changelog "November 2026" (published 2026-11-01) ships v0.5.1: tenant admins can no longer open workspaces they are not members of, Settings > About lists the exact release per service, the Compose stack gained NIX_WEB_LANDING and NIX_WEB_DEMO flags, and the Kubernetes seed-job recreation is documented. The stack is vendor/editorial-reported (ASP.NET Core 10, Postgres 16, React 19, pgvector, Yjs over WebSockets) and was current at the live repo at write time on 2026-11-02 — the project had 7 stars, 1 fork, 900 commits and 6 releases then, all of which will move. The AGPL-3.0-only license (from v0.5, with additional permissions for plugins, your content and programs that use Nix; releases up to v0.4.x stay MIT) means using it — including at work — asks nothing of you, with a commercial licence available if you need one. Try the live demo at nixsites.com before committing a server to it, and expect the docs' install path and flags to keep changing while the project is this young.
Sources
- Nixsites GitHub repository (github.com/sianachi/nixsites) — README: self-description, "One tree, many views" section, stack section, row-level-security paragraph, license section; repo metadata (7 stars, 1 fork, 900 commits, 6 releases, created 2026-07-27) read 2026-11-02.
- Nixsites docs (nix.nixsites.com) — "Install Nix" (one-line installer, real-install form, prerequisites, first-run URLs, installer internals, one-time admin password), "Your first workspace" (personal workspace, rail destinations, Mod+K, New options, Today note, container fields, views, roles), "nixctl basics" (alias, auth, token scopes in Settings > Access tokens, all documented commands), "MCP server" (stdio server, client config JSON), "Import and export" (import format table, .nix archive definition, backup instructions), "Architecture" (service list: ASP.NET Core 8080, pgvector/pg16, Node 8100 Yjs, RabbitMQ, versity object store, Zitadel), "Changelog November 2026" (v0.5.1 release notes) — all fetched 2026-11-02.
- Clawdbytes launch editorial (2026-10-19): "Self-Hosted Workspace Where Notes, Tasks and AI Chats Are All Items" — architecture summary, repo link, launch coverage.
- AppFlowy README (raw.githubusercontent.com/AppFlowy-IO/AppFlowy/main/README.md) — title, tagline, "Built With: Flutter, Rust", mission statement — fetched 2026-11-02 for the comparison table.
- Femaleswitch.com roundup (2026-10-27) — AppFlowy open-core/self-hosting seat note, used for the comparison row.
Frequently Asked Questions
Is Nixsites the same as NixOS or the Nix package manager?
No. Nixsites is a self-hosted workspace app; Nix and NixOS are a package manager and a Linux distribution. The name collision floods Google results with unrelated NixOS noise, so use exact-phrase search with "nixsites" in quotes.
Is Nixsites free?
Yes — it is open source, AGPL-3.0-only from v0.5 (MIT up to v0.4.x), and the one-line installer is free. Your only cost is the machine you run it on. A commercial licence is also available from the project.
How is Nixsites different from AppFlowy or Notion?
AppFlowy is an open-source Notion clone (block-based pages, Flutter/Rust). Nixsites is an AI-native unified workspace: everything is one item tree with 16 interchangeable views, and the web app, nixctl CLI and MCP server share one Postgres row-level-security authorization path.
Can I use Nixsites with my coding agent?
Yes — run nixctl mcp to start a Model Context Protocol server over stdio, then point your agent's MCP client at it. It runs as you, with your token's scopes, and can never reach further than you can.
How do I back up Nixsites?
Back up ~/nix/nix.env together with the Docker volumes (nix-*) — the env file holds every secret and cannot be regenerated. For portable content archives, use nixctl export to create lossless .nix archives of any item subtree.
