Titian

Connect your local workspaces to remote MCP clients through one authenticated gateway. Titian runs Desktop Commander on your Mac and gives each project its own URL, OAuth credentials and folder configuration.

For example, connect a mobile app and a backend as two separate MCP connections, or give one connection access to both folders. Clients can read project metadata to identify the configured project and roots. One project uses the same installation as many.

Titian means a narrow footbridge in Indonesian.

Desktop Commander can read files and run commands with your account's permissions. Project folders are not an OS sandbox. Read SECURITY.md before exposing the gateway.

Documentation

Guide	What it covers
Permissions and approvals	Presets, task templates, custom rules, owner approval and migration.
Operations	Installation, service lifecycle, runtime updates and validation.
Troubleshooting	Connection failures, blocked operations and approval errors.
Architecture	Gateway, authentication, policy enforcement and execution.
Security	Host-execution risks and the limits of permission controls.

Before you start

You need:

• macOS, Python 3.10+, Node.js 22+, npm and Git. The service manager uses macOS launchd; Linux is currently covered for protocol tests, not service management.
• An MCP client that supports remote Streamable HTTP and OAuth dynamic registration.
• A public HTTPS hostname forwarding to this Mac. You can publish it with Tailscale Funnel, Cloudflare Tunnel, or another HTTPS reverse proxy. See Network providers for setup and switching instructions.
• An existing project folder. Titian configures access to it; it does not create or clone your application.

Keep the Mac awake and online while connecting remotely.

1. Choose your HTTPS origin

Find your machine's Tailscale DNS hostname:

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

The result looks like https://my-mac.my-tailnet.ts.net. Copy your actual result; do not use this example hostname.

Your origin is the HTTPS scheme and hostname, without /mcp or a project path. With another reverse proxy, use the HTTPS origin you control. Configure it to preserve request paths and forward to 127.0.0.1:8300.

2. Install and prepare Titian

git clone https://github.com/imansprn/titian.git
cd titian
npm ci

Replace the hostname below with the origin from step 1:

./bin/titian init --origin https://my-mac.my-tailnet.ts.net
./bin/titian runtime install

init creates private local settings in .titian/. runtime install builds the pinned Desktop Commander runtime. Neither command exposes the Mac publicly.

3. Start the gateway and add your first project

Run init again with --start-gateway to install and start the macOS gateway service. Repeating init preserves your state:

./bin/titian init --origin https://my-mac.my-tailnet.ts.net --start-gateway

Replace /absolute/path/to/project with an existing directory:

./bin/titian add "My app" /absolute/path/to/project --slug my-app

This starts the project's local bridge and OAuth proxy with read-only permissions by default. The command prints its connection URL and PIN file path. The URL will have this shape:

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

For the Tailscale setup, publish the gateway:

tailscale funnel --bg 8300
titian network configure tailscale --hostname my-mac.my-tailnet.ts.net

Follow any Funnel authorization instructions it prints. The hostname must resolve to this Mac inside the tailnet and be enabled for Funnel for public access.

For Cloudflare Tunnel, first create a remotely managed Tunnel and configure its public hostname and DNS record to forward to http://127.0.0.1:8300. Then configure Titian with the Tunnel ID and a local token file:

titian network configure cloudflare \
  --hostname mcp.example.com \
  --tunnel-id YOUR-TUNNEL-UUID \
  --token-file /path/to/tunnel-token
titian network doctor

Titian manages the local cloudflared process. DNS and the Tunnel route are configured in Cloudflare first. See Cloudflare networking for prerequisites and migration details.

Titian publishes one canonical hostname in project URLs and OAuth metadata. Use the URL printed by titian list in MCP clients, then reconnect after changing providers or hostnames so the client refreshes OAuth discovery.

4. Connect your MCP client

Use these settings in a client that supports remote MCP with OAuth:

Setting	Value
Server URL	The full /projects/my-app/mcp URL printed by add
Authentication	OAuth, with dynamic client registration
Client ID / secret	Not supplied manually; the client registers itself
Consent	Enter this project's PIN in the authorization page

Read the PIN locally, from the Titian repository root:

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

The PIN is not a bearer token or client secret. Enter it only in the consent page for the connection you initiated. After approval, the client receives and refreshes its own tokens. Menu names differ between clients; use their remote MCP connection settings.

5. Check that it worked

./bin/titian list
./bin/titian doctor

Example output (your paths and hostname differ):

my-app — My app (active)
  https://my-mac.my-tailnet.ts.net/projects/my-app/mcp
  /absolute/path/to/project

my-app: auth=OK, bridge=OK, oauth-routing=OK, mcp=OK

doctor checks local services and MCP routing. For a separate public endpoint check, run ./bin/titian doctor --public.

In your connected client, ask it to call titian_project_info. It should return the project name and roots you configured. Tool and resource availability depends on the client's MCP support.

Use titian from any directory

The walkthrough uses ./bin/titian, which does not require PATH changes. To use the shorter command, run these from the Titian root:

mkdir -p "$HOME/.local/bin"
ln -s "$(pwd)/bin/titian" "$HOME/.local/bin/titian"
export PATH="$HOME/.local/bin:$PATH"
titian list

Add the export PATH line to your shell configuration, such as ~/.zshrc, to keep it across terminals. If the symlink already exists, inspect its target before replacing it.

Multiple projects and metadata

Each add creates a separate URL and credentials. To give one project two roots and descriptive labels:

titian add "Web and mobile" /path/to/backend /path/to/mobile \
  --slug example --capabilities mobile backend git test build

After authentication, clients can read the MCP resource titian://project/metadata or call the read-only tool titian_project_info:

{
  "project": "example",
  "roots": ["/path/to/backend", "/path/to/mobile"],
  "capabilities": ["mobile", "backend", "git", "test", "build"]
}

Capabilities are labels you configure, not permissions, detected frameworks, or guarantees that a build command exists. They default to []. Local paths are returned through the authenticated MCP connection, not public OAuth discovery metadata.

Permissions and owner approvals

New workspaces default to readonly. Presets control operations, not command-name prefixes:

Preset	Use it for	Key behavior
readonly	Browsing and searching selected files.	No file changes or shell execution, including git status or pwd.
editor	Creating and editing selected files.	Moves/renames ask; shell execution, URL retrieval and rich rendering remain denied.
custom	Explicit operation rules.	Each operation is allow, ask or deny; unspecified rules deny.
unrestricted	Explicitly trusted host workflows.	Reviewed operations run without routine Titian approval; authentication, file scope and backend restrictions still apply.

No preset is an OS sandbox. editor allows overwriting existing files; it is not a create-only preset. DOCX/PDF generation additionally requires document.render and is not included in editor.

Task templates are separate from permission levels. documents selects editor; developer and data-analysis select custom rules and ask before starting a process or sending interactive input. The developer template also asks before system inspection. Templates do not guess whether npm test or another command is harmless. See the complete preset matrix.

titian update example --permissions editor
titian update example --template developer
titian update example --permissions custom --allow files.read --ask process.start
titian permissions example

titian permissions shows configured and verified effective policy separately. An offline or older runtime is reported as unverified, not protected. Changing source code alone does not activate a new runtime.

When a tool returns approval_required, review it on the Mac in an interactive owner terminal:

titian approvals example list
titian approvals example show REQUEST_ID
titian approvals example approve REQUEST_ID
# Or: titian approvals example reject REQUEST_ID

Titian executes an allow request, queues an ask request without executing it, and rejects a deny request without an approve-once shortcut. There is no MCP tool for approving requests or changing the policy; those decisions belong in the local owner interface.

Approving does not execute the operation. After local approval, the same authenticated client explicitly calls the MCP tool titian_resume with these arguments (replace the placeholder with the returned request ID):

{ "requestId": "REQUEST_ID" }

The request expires five minutes after it was created, even if approved later. Approval is single-use and bound to the stored request and client; it never enables that command globally. A backend blockedCommands rejection remains a rejection. This release uses a local CLI, not a browser approval dialog or MCP elicitation. See blocked commands and approval errors.

For an existing installation, migrate explicitly before changing policy. Full operation definitions and limitations: permissions.

titian update example --capabilities mobile backend git test build
titian update example /path/to/new-root
titian restart example
titian disable example
titian enable example
titian remove example

Removing a project archives its OAuth state and stops its services. It never deletes the project's source folders. See operations for updates, recovery and runtime maintenance.

Troubleshooting

Symptom	What to check
titian: command not found	Use ./bin/titian from the repository root, or check the symlink and PATH above.
Gateway is not running	Run ./bin/titian status; start it with init --origin YOUR_ORIGIN --start-gateway.
Local doctor passes but the client cannot connect	Check your HTTPS hostname, tailscale funnel status, and that the Mac is awake. Run doctor --public; if only one public IP fails, see troubleshooting.
OAuth approval fails	Use the PIN for that project's slug and retry the connection from the client.
Runtime is missing	Run npm ci, then ./bin/titian runtime install.

Service logs are in .titian/logs/. Keep the repository at its installed path while services run; see migration before moving it.

Architecture and development

MCP client → HTTPS → gateway :8300
                       ├── project A → OAuth proxy → MCP bridge → Desktop Commander
                       └── project B → OAuth proxy → MCP bridge → Desktop Commander

Source is in src/, the CLI in bin/, and machine state in ignored .titian/. There is one root dependency graph and one project management flow.

npm ci
npm test
npm run test:manager
npm run test:dependencies
npm audit

CI checks Linux Node 22/24/26 and macOS Node 24, including runtime construction. Live integration tests are opt-in: operations. More detail: architecture, migration, troubleshooting, and security.

License

MIT. Dependencies retain their own licenses.