Self-hosted collaboration for local-first teams

Self-hosted collaboration means the people using a workspace choose and operate the server that connects live editors. It can be a useful fit for a small technical team that wants local-first work and is prepared to own the relay. It is not a synonym for cloud sync, a managed collaboration plan, or a substitute for the team’s agreed system of record.

Start with the operating model, not the protocol

Before choosing a shared editor, name the job it must do. A managed service is often the practical choice when a team needs vendor-operated identity, permissions, audit records, always-on availability, mobile sync, and someone else on call. A self-hosted relay fits a different situation: the team wants to control the connection path and has an operator who can maintain it.

Mind Marshal is local-first whether or not a relay is configured. A person can write, search, plan, use databases, and work offline without a product cloud account. Shared editing is an optional connection to a y-websocket relay the team runs itself. Mind Marshal does not run a hosted relay, provide managed cloud sync, or sell team seats.

What a collaboration relay does, and does not do

A relay helps active editors exchange document updates. In Mind Marshal, that gives collaborators multi-cursor editing and conflict-free merging when people reconnect after working offline. It does not create a complete project-management operating system around the team.

• It can help with: live co-editing, reconnecting after a temporary offline period, and keeping a small group aligned on a page.
• It does not automatically provide: managed hosting, guaranteed availability, enterprise permissions, SSO, audit logs, a company-wide assignment system, or a vendor-run backup service.
• It should not replace: the tool where your organization has agreed to publish decisions, owners, dates, and status for everyone to see.

This distinction matters. A private workspace can hold useful context and working drafts. A shared relay can support focused co-editing. Neither should make formal commitments harder for the rest of the team to find.

When a self-hosted model is a good fit

Use this decision test before investing time in a server:

1. Do you already have an operator? Someone must own updates, access, availability, and incident response for the relay.
2. Is the group small and technically comfortable? A self-run service trades convenience for control. It is rarely the right first choice for a large group that needs hands-off administration.
3. Can the work stay useful offline? Local-first collaboration is strongest when each person can continue working locally rather than treating the relay as the only copy that matters.
4. Have you named the public source of truth? If a decision changes an external commitment, record it where the affected team expects to find it.
5. Can you test the exact network path? Test it with a real page, the actual devices, and the actual access boundary before depending on it for a deadline.

Start safely on one machine

Mind Marshal includes a small y-websocket relay for a local setup. The default command binds to 127.0.0.1, which means it listens only on the same machine rather than silently becoming a network service. From a checkout of the project, start it with:

cd collab-server
npm install
npm start
# default: ws://localhost:1234

Then open Settings → Collaboration in Mind Marshal and enter ws://localhost:1234. Leaving the server field empty returns the app to local-only mode. This loopback setup is a useful way to understand the feature and test the workflow without exposing a relay to a network.

Plan the security boundary before changing the default

Opening a collaboration service beyond one computer is an operational decision, not a checkbox. The bundled relay supports an optional authentication mode, but the local default is intentionally simple and anonymous. Do not publish an unauthenticated development relay to a LAN or the internet.

For any shared deployment, the team operating it should decide and document at least the following:

• which people and devices may connect;
• how users are provisioned and removed;
• how traffic is protected in transit and where connection logs are retained;
• which host, network, and reverse-proxy settings are appropriate for the organization;
• who applies updates and responds when the relay is unavailable; and
• what backup and recovery practice protects the local workspaces themselves.

Authentication, transport security, access control, and host hardening are deployment-specific. A team without the ability to operate those controls should choose a managed service designed for that responsibility instead. Clear limits are safer than an implied security promise.

Use a simple shared-editing protocol

Technology does not resolve ambiguous ownership. Agree on a lightweight routine around shared pages:

1. Name the page owner. Decide who consolidates the result after a working session.
2. Keep one purpose per page. A draft, decision record, or working plan is easier to review than a catch-all room.
3. Publish the outcome where the team works. Copy final decisions, owners, and deadlines into the agreed project tool or channel.
4. Use conflict-free merging thoughtfully. It helps preserve edits after reconnection, but it cannot determine which of two incompatible choices the team intends to make.
5. Close the loop. End a session with a short statement of what changed, who owns the next action, and where it is now visible.

This same boundary helps an individual use team messages as personal follow-through context without turning a private planning system into a hidden shadow tracker.

Choose deliberately

Self-hosting is valuable when control and offline resilience matter enough to justify operations. It is not automatically more private, more secure, or more collaborative simply because a team runs it. The useful question is whether your team can own the responsibilities that come with the connection.

Test the real workflow

Try shared editing after local work already feels solid.

Mind Marshal keeps ordinary notes, planning, search, and databases local. Connect a relay only when the team is ready to operate that choice.

Review collaboration detailsRead the privacy boundary