Getting Started

Getting Started

Requirements

• macOS, Python 3.10+, Node.js 22+, npm, and Git.
• An existing application directory.
• A remote MCP client supporting Streamable HTTP and OAuth dynamic registration.
• A public HTTPS hostname forwarding to the Mac. For this guide, install and sign in to Tailscale and enable Funnel for your device.

Keep the Mac awake and connected while using remote tools. Linux protocol tests do not imply Linux service-management support.

1. Find your HTTPS origin

tailscale status --json | python3 -c 'import json,sys; print("https://" + json.load(sys.stdin)["Self"]["DNSName"].rstrip("."))'

Use the resulting origin, such as https://my-mac.my-tailnet.ts.net, without /mcp or a project path. The example hostname is not a working endpoint.

2. Install

git clone https://github.com/imansprn/titian.git
cd titian
npm ci
./bin/titian init --origin https://my-mac.my-tailnet.ts.net
./bin/titian runtime install

Replace the origin first. Initialization creates private state under .titian/; runtime installation prepares Desktop Commander. These steps do not publish the service.

3. Start and publish

./bin/titian init --origin https://my-mac.my-tailnet.ts.net --start-gateway
./bin/titian add "My app" /absolute/path/to/project --slug my-app
tailscale funnel --bg 8300

The project folder must already exist. Follow any Funnel authorization instructions. The CLI prints a URL shaped like:

https://my-mac.my-tailnet.ts.net/projects/my-app/mcp

For an existing running installation, use restart gateway when a gateway restart is needed. Do not rerun first-install commands to repair every error.

With another reverse proxy, preserve request paths and forward HTTPS traffic to 127.0.0.1:8300. Publish the gateway, not a project's bridge port.

4. Connect

Client setting	Value
Server URL	Full URL printed by add, including /projects/my-app/mcp
Authentication	OAuth with dynamic client registration
Client ID and secret	Registered by the client; do not enter the consent PIN here
Consent	Enter the project's PIN on the authorization page

Read the PIN privately from the Titian root:

cat .titian/instances/my-app/.oauth-consent-pin

Only approve a connection you initiated. If using a custom data directory, read the file there instead. Client menu names vary; select its remote MCP connection flow.

5. Verify

./bin/titian list
./bin/titian doctor my-app
./bin/titian doctor my-app --public

Then ask your client to call titian_project_info. Confirm the returned slug and roots match your project. Local checks and public checks test different network paths; run both when diagnosing a remote failure.

All wiki commands use ./bin/titian from the repository root. See the README to install a PATH symlink.