Centina binary setup and self-hosting playbook

Pick the pattern you need

Install the binary

Supported platforms: macOS on Apple silicon (darwin-arm64) and Linux on x86_64 or aarch64 with glibc (linux-x64, linux-arm64). musl systems (Alpine), Intel macOS, and Windows are not supported yet — the installer refuses them up front rather than half-installing.

One-liner — the same command on every supported platform. It detects the OS and architecture, downloads the matching latest release, verifies its SHA-256 checksum, and installs it to ~/.local/bin/centina (override the destination with CENTINA_INSTALL_DIR):

1curl -fsSL https://get.centina.build/install.sh | bash

Manually: <https://get.centina.build/latest> names the newest version. Download the artifact for your platform and its checksum, verify, and put the binary on PATH (shown for darwin-arm64 — substitute linux-x64 or linux-arm64, and sha256sum -c for shasum -a 256 -c on Linux):

1VERSION=$(curl -fsSL https://get.centina.build/latest)
2curl -fLO "https://get.centina.build/centina-v${VERSION}-darwin-arm64"
3curl -fLO "https://get.centina.build/centina-v${VERSION}-darwin-arm64.sha256"
4shasum -a 256 -c "centina-v${VERSION}-darwin-arm64.sha256"
5install -m 755 "centina-v${VERSION}-darwin-arm64" "$HOME/.local/bin/centina"
6centina --version

If $HOME/.local/bin is not already on PATH, either add it or invoke Centina by its absolute path.

The alpha binary is not signed or notarized

Verify the checksum — that is the integrity check for an unsigned download. On macOS, files that arrive via a browser or AirDrop carry the quarantine attribute, and Gatekeeper will refuse to run the binary ("cannot be opened because the developer cannot be verified"). The remedy, only after the checksum verifies:

1xattr -d com.apple.quarantine ~/.local/bin/centina

curl downloads (including the one-liner) don't set the attribute, so the steps above run as-is. If a checksum does not match, discard the file — do not run it, and do not disable operating-system security globally.

Command reference

centina serve [--host] [--port <port>] [--no-open]
centina mcp
centina --help
centina --version
centina --license

• serve starts the browser application and collaboration bridge.
• --host allows other machines on the local network to connect.
• --port changes the web port; the bridge follows at web port plus 701.
• --no-open starts the services without opening a browser automatically.
• mcp runs the newline-delimited stdio MCP server. An MCP client launches this command; people normally do not run it interactively.
• --license prints the Free Binary License the binary is distributed under — the text travels inside the executable, so every copy carries its own license. The running application shows the same text from the Home screen's footer.

Pattern 1: one person, local editor

Run:

1centina serve

Centina prints its URL and opens it in the default browser. If automatic opening is disabled or unavailable, open the printed URL manually. The default is:

http://localhost:3000

Keep the terminal process running while Centina is open. Stop it with Ctrl-C.

Data and backups

Centina autosaves canvases in the browser's IndexedDB. Browser storage is tied to the complete origin, including its port:

http://localhost:3000  !=  http://localhost:4500

Changing the port therefore looks like a new Centina library; it does not move or delete canvases stored at the old origin. Before changing ports, browsers, or machines, use Canvas actions → Export canvas. Import the resulting .centina.json file into the new library.

Use the same browser profile for normal sessions. Private/incognito windows may discard their IndexedDB data when closed.

Pattern 2: local editor with MCP

The MCP client launches centina mcp; the already-running centina serve process owns the local bridge and the browser tab owns the live canvas:

MCP client ⇄ centina mcp ⇄ local bridge ⇄ open browser tab

First start the editor:

1centina serve

Then register the MCP command. Claude Code, for example:

1claude mcp add centina -- centina mcp

If centina is not on PATH, use its absolute path:

1claude mcp add centina -- /absolute/path/to/centina mcp

For a client that accepts JSON configuration, use the equivalent shape:

1{
2  "mcpServers": {
3    "centina": {
4      "command": "/absolute/path/to/centina",
5      "args": ["mcp"]
6    }
7  }
8}

Ask the agent to call ping or get_canvas_info to verify the connection.

Important operating rules:

• The server process and browser tab must both remain open. A running server without a tab has no live canvas for MCP to read or edit.
• If several Centina tabs use the same origin, the newest tab becomes the MCP target and the older one disconnects from the bridge.
• Several MCP sessions may connect concurrently. They all edit that one active tab.
• Every MCP write is an undoable editor operation.
• Screenshot tools may require a compatible browser debugging connection; follow the actionable message returned by the tool when it is unavailable.

The complete tool and operating reference lives in the MCP guide.

Pattern 3: share a canvas on a trusted LAN

Start Centina on all network interfaces:

1centina serve --host

The terminal prints a local URL and, when an external IPv4 address is found, a LAN URL such as:

http://192.168.1.42:3000

On the host:

1. Open the local URL in a browser.
2. Open the canvas to share.
3. Click Share.
4. Choose whether guests can edit or only view.
5. Click Start sharing.
6. Send the generated join link to people on the same network.

Guests only need a browser; they do not need the Centina binary. Opening the join link gives them the host's current canvas snapshot followed by live edits, presence, and cursor updates.

The host must keep all three of these alive:

• The centina serve --host process.
• The host's browser tab.
• The shared canvas mounted in that tab.

Stopping sharing or leaving the shared canvas ends the room. A page reload has a short grace period so an ordinary refresh does not immediately eject guests.

Ports and firewalls

The default ports are:

The bridge is always the web port plus 701. To choose another base port:

1centina serve --host --port 4500

Allow inbound TCP traffic to both ports in the host firewall. Do not expose any browser debugging port. If guests cannot connect even though the firewall is open, check whether the Wi-Fi access point enables client/AP isolation; guest networks commonly prevent devices from reaching one another.

LAN security boundary

LAN hosting is intentionally a trusted-network feature:

• The web app and collaboration /sync socket are reachable from the LAN.
• MCP agent and editor-control sockets remain loopback-only; remote attempts receive HTTP 403.
• Rooms have no accounts, passwords, authentication tokens, or transport encryption.
• Do not port-forward these ports or expose them directly to the internet.

Use a private home, studio, or office network whose participants you trust. Internet self-hosting needs TLS, authenticated share tokens, and a hardened deployment mode that Centina does not currently provide.

Browser limitations for LAN guests

The host uses localhost, which browsers treat as a potentially trustworthy origin. A guest normally uses a plain private-IP URL such as http://192.168.1.42:3000, which is not a secure context. Core canvas editing and collaboration work, but browsers may withhold powerful APIs such as advanced clipboard access and local-font enumeration. Export/import and ordinary browser fallbacks remain the recovery path.

Pattern 4: LAN collaboration with host-side agents

Register MCP once:

1claude mcp add centina -- centina mcp

Start each hosting session with:

1centina serve --host

The host may connect several MCP sessions. Their work propagates to every guest through the collaboration room, including the Crafting presence indicator. All host-side agent writes use the host's collaboration identity; they do not appear as separate remote guests.

Remote guests cannot attach MCP to their LAN-loaded tab and cannot control the host's tab through the exposed bridge.

Multiple users with their own MCP

This pattern is not supported by the current binary protocol. Safe support requires each person to run Centina locally:

guest's MCP client
        ⇅ loopback
guest's local Centina process
        ⇅ collaboration only
host's LAN relay

The app must first separate its local browser origin from its collaboration relay address. Merely exposing the host's /agent socket to the LAN would grant control of the host's tab and is not an acceptable workaround.

Until relay separation ships, use host-side MCP sessions and ordinary browser guest collaboration.

What is included in a release

The executable is self-contained. A release publishes, side by side at get.centina.build:

• One centina binary per supported platform (darwin-arm64, linux-x64, linux-arm64), named centina-v<version>-<platform>.
• A SHA-256 checksum beside every binary.
• The installer script (install.sh) and a latest version manifest.

This playbook and the project license are published on the documentation site. Nothing else is needed — not the source repository, not Bun or Node.js, not node_modules, not a build toolchain.

Troubleshooting

centina: command not found

Put the binary on PATH or invoke it by absolute path. On macOS/Linux, also confirm it is executable:

1chmod u+x /absolute/path/to/centina
2/absolute/path/to/centina --version

The operating system blocks the binary

The alpha binary is unsigned; macOS Gatekeeper blocks copies that carry the browser/AirDrop quarantine attribute. Verify the download's checksum against the published .sha256, then remove the attribute (xattr -d com.apple.quarantine <path>) — see the install section. If the checksum does not match, discard the file. Do not disable operating-system security globally.

Centina ... isn't running

Start centina serve for the same origin the MCP reference names, then open that URL in a browser. Remember that localhost:3000 and localhost:4500 are different instances.

No editor tab is open

The server and bridge are running, but no browser tab has connected. Open or reload the printed Centina URL and retry after a few seconds.

A port is already in use

Another Centina process or application owns the web or bridge port. Stop the older process or choose another base port:

1centina serve --port 4500

For LAN hosting, remember to allow both 4500 and 5201 through the host firewall.

Guests can load the app but cannot join

Confirm that:

• The host used --host, not the loopback-only default.
• The host clicked Start sharing for the open canvas.
• Both TCP ports are allowed through the firewall.
• The guest used the generated link, including its ?join=... value.
• Both machines are on a LAN that permits device-to-device traffic.

A guest's clipboard or installed fonts are unavailable

This is usually the browser's secure-context policy for a plain HTTP private IP, not a collaboration failure. Use browser fallbacks or canvas export/import; do not disable browser security globally.

Canvases appear to be missing after changing ports

Return to the original origin and export them:

http://localhost:<old-port>

Then import the .centina.json files at the new origin.