droid-patch

English | 简体中文

CLI tool to patch the droid binary with various modifications.

Installation

npm install -g droid-patch
# or use directly with npx
npx droid-patch --help

Usage

Patch and Create an Alias

# Patch with --is-custom and create an alias
npx droid-patch --is-custom droid-custom

# Patch with --skip-login to bypass login requirement
npx droid-patch --skip-login droid-nologin

# Patch with --websearch to enable local search proxy
npx droid-patch --websearch droid-search

# Combine multiple patches
npx droid-patch --is-custom --skip-login --websearch droid-full

# Specify a custom path to the droid binary
npx droid-patch --skip-login -p /path/to/droid my-droid

# Dry run - verify patches without actually applying them
npx droid-patch --skip-login --dry-run droid

# Verbose output
npx droid-patch --skip-login -v droid

Output to a Specific Directory

# Output patched binary to current directory
npx droid-patch --skip-login -o . my-droid

# Output to a specific directory
npx droid-patch --skip-login -o /path/to/dir my-droid

Available Options

Manage Aliases and Files

# List all aliases
npx droid-patch list

# Remove an alias
npx droid-patch remove <alias-name>

# Remove a patched binary file by path
npx droid-patch remove ./my-droid
npx droid-patch remove /path/to/patched-binary

# Check proxy status
npx droid-patch proxy-status

Check Version

npx droid-patch version

PATH Configuration

When creating an alias (without -o), the tool will try to install to a directory already in your PATH (like ~/.local/bin). If not available, you need to add the aliases directory to your PATH:

# Add to your shell config (~/.zshrc, ~/.bashrc, etc.)
export PATH="$HOME/.droid-patch/aliases:$PATH"

How It Works

1. Patching: The tool searches for specific byte patterns in the droid binary and replaces them with equal-length replacements
2. Alias Creation (without -o):
   • Copies the patched binary to ~/.droid-patch/bins/
   • Creates a symlink in a PATH directory or ~/.droid-patch/aliases/
   • On macOS, automatically re-signs the binary with codesign
3. Direct Output (with -o):
   • Saves the patched binary directly to the specified directory
   • On macOS, automatically re-signs the binary with codesign

Available Patches

--is-custom

Changes isCustom:!0 (true) to isCustom:!1 (false) for custom models.

Purpose: This may enable context compression (auto-summarization) for custom models, which is normally only available for official models.

Note: Side effects are unknown - test thoroughly before production use.

--skip-login

Replaces all process.env.FACTORY_API_KEY references in the binary with a hardcoded fake key "fk-droid-patch-skip-00000".

Purpose: Bypass the login/authentication requirement without needing to set the FACTORY_API_KEY environment variable.

How it works:

• The original code checks process.env.FACTORY_API_KEY to authenticate
• After patching, the code directly uses the fake key string, bypassing the env check
• This is a binary-level patch, so it works across all terminal sessions without any environment setup

--api-base <url>

Replaces the Factory API base URL (https://api.factory.ai) with a custom URL.

Purpose: Redirect API requests to a custom server (e.g., local proxy).

Limitation: URL must be 22 characters or less (same length as original URL).

Examples:

# Valid URLs (<=22 chars)
npx droid-patch --api-base "http://127.0.0.1:3000" droid-local
npx droid-patch --api-base "http://localhost:80" droid-local

# Invalid (too long)
npx droid-patch --api-base "http://my-long-domain.com:3000" droid  # Error!

--websearch

Enables WebSearch functionality through a local proxy server that intercepts /api/tools/exa/search requests.

Purpose: Enable WebSearch functionality without Factory.ai authentication.

Features:

• Multiple search providers with automatic fallback
• Auto-start: Proxy starts automatically when you run the alias
• Auto-shutdown: Proxy shuts down after 5 minutes of inactivity (configurable)
• Process detection: Stays alive as long as droid is running

Usage:

# Create alias with websearch
npx droid-patch --websearch droid-search

# Just run it - everything is automatic!
droid-search

WebSearch Configuration Guide

The --websearch feature supports multiple search providers. Configure them using environment variables in your shell config (~/.zshrc, ~/.bashrc, etc.).

Search Provider Priority

The proxy tries providers in this order and uses the first one that succeeds:

1. Smithery Exa (Recommended)

Smithery Exa provides high-quality semantic search results through the MCP protocol. Smithery acts as a free proxy to the Exa search API.

Setup Steps

1. Create a Smithery Account

   • Go to smithery.ai
   • Sign up for a free account

2. Get Your API Key

   • Navigate to your account settings
   • Copy your API key

3. Get Your Profile ID

   • Go to smithery.ai/server/exa
   • Your profile ID is shown in the connection URL or settings

4. Configure Environment Variables

   # Add to ~/.zshrc or ~/.bashrc
   export SMITHERY_API_KEY="your_api_key_here"
   export SMITHERY_PROFILE="your_profile_id"

Pricing

• Free through Smithery (Smithery proxies the Exa API at no cost)
• Note: The official Exa API (exa.ai) is paid, but Smithery provides free access

2. Google Programmable Search Engine (PSE)

Google PSE provides high-quality search results with a generous free tier.

Setup Steps

Step 1: Create a Programmable Search Engine

1. Go to Google Programmable Search Engine Console
2. Click "Add" to create a new search engine
3. Configure:
   • Sites to search: Enter * to search the entire web
   • Name: Give it a descriptive name (e.g., "Web Search")
4. Click "Create"
5. Click "Control Panel" for your new search engine
6. Copy the Search engine ID (cx) - looks like 017576662512468239146:omuauf_lfve

Step 2: Get an API Key

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Custom Search API:
   • Go to "APIs & Services" > "Library"
   • Search for "Custom Search API"
   • Click "Enable"
4. Create credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "API Key"
   • Copy the API key

Step 3: Configure Environment Variables

# Add to ~/.zshrc or ~/.bashrc
export GOOGLE_PSE_API_KEY="AIzaSy..."        # Your API key
export GOOGLE_PSE_CX="017576662512468239146:omuauf_lfve"  # Your Search engine ID

Free Tier Limits

• 10,000 queries/day free
• Max 10 results per query
• After limit: $5 per 1,000 queries

3. Serper

Serper provides Google search results through an easy-to-use API.

Setup Steps

1. Create an Account

   • Go to serper.dev
   • Sign up for a free account

2. Get Your API Key

   • After signing in, your API key is displayed on the dashboard
   • Copy the API key

3. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export SERPER_API_KEY="your_api_key_here"

Free Tier

• 2,500 free credits on signup
• 1 credit = 1 search query
• Paid plans available for more usage

4. Brave Search

Brave Search API provides privacy-focused search results.

Setup Steps

1. Create an Account

   • Go to brave.com/search/api
   • Click "Get Started"

2. Subscribe to a Plan

   • Choose the Free plan (2,000 queries/month)
   • Or a paid plan for more queries

3. Get Your API Key

   • Go to your API dashboard
   • Copy your API key

4. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export BRAVE_API_KEY="BSA..."

Free Tier

• 2,000 queries/month free
• Rate limit: 1 query/second
• Paid plans start at $5/month for 20,000 queries

5. SearXNG (Self-Hosted)

SearXNG is a free, privacy-respecting metasearch engine you can self-host.

Setup Steps

Option A: Use a Public Instance

You can use a public SearXNG instance, but availability and reliability vary.

# Example public instance (check if it's available)
export SEARXNG_URL="https://searx.be"

Find public instances at searx.space

Option B: Self-Host with Docker

1. Run SearXNG with Docker

   docker run -d \
     --name searxng \
     -p 8080:8080 \
     -e SEARXNG_BASE_URL=http://localhost:8080 \
     searxng/searxng

2. Configure Environment Variable

   # Add to ~/.zshrc or ~/.bashrc
   export SEARXNG_URL="http://localhost:8080"

Advantages

• Unlimited searches
• No API key required
• Privacy-focused
• Aggregates results from multiple search engines

Disadvantages

• Requires self-hosting for reliability
• Public instances may be slow or unavailable

6. DuckDuckGo (Default Fallback)

DuckDuckGo is used automatically as the final fallback when no other providers are configured or available.

Configuration

No configuration required! DuckDuckGo works out of the box.

Limitations

• HTML scraping (less reliable than API)
• Basic results compared to other providers
• May be rate-limited with heavy use

Quick Configuration Examples

Minimal Setup (Free, No API Keys)

Just use DuckDuckGo fallback:

npx droid-patch --websearch droid-search
droid-search  # Works immediately with DuckDuckGo

Recommended Setup (Best Quality)

# Add to ~/.zshrc or ~/.bashrc
export SMITHERY_API_KEY="your_smithery_key"
export SMITHERY_PROFILE="your_profile_id"

# Fallback: Google PSE
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

Budget-Friendly Setup (All Free)

# Add to ~/.zshrc or ~/.bashrc

# Option 1: Google PSE (10,000/day free)
export GOOGLE_PSE_API_KEY="your_google_key"
export GOOGLE_PSE_CX="your_search_engine_id"

# Option 2: Serper (2,500 free credits)
export SERPER_API_KEY="your_serper_key"

# Option 3: Brave (2,000/month free)
export BRAVE_API_KEY="your_brave_key"

# DuckDuckGo is always available as final fallback

Proxy Management

Auto-Shutdown

The proxy automatically shuts down after 5 minutes of inactivity to save resources.

# Customize timeout (in seconds)
export DROID_PROXY_IDLE_TIMEOUT=600   # 10 minutes
export DROID_PROXY_IDLE_TIMEOUT=0     # Disable auto-shutdown

Check Proxy Status

npx droid-patch proxy-status

Output shows:

• Proxy running status
• Process ID
• Droid process detection
• Idle timeout settings

Debug Mode

Enable detailed logging to troubleshoot search issues:

export DROID_SEARCH_DEBUG=1
droid-search

Examples

# Quick start: create droid with websearch
npx droid-patch --websearch droid-search
droid-search  # Just works!

# Full-featured droid
npx droid-patch --is-custom --skip-login --websearch droid-full

# Create a standalone patched binary in current directory
npx droid-patch --skip-login -o . my-droid
./my-droid --version

# Clean up
npx droid-patch remove droid-search   # remove alias and all related files
npx droid-patch remove ./my-droid     # remove file

License

MIT