AIClient-2-API/src/droid/README.md

Droid (Factory.ai) Provider

This adapter enables you to use Factory.ai's Droid CLI as an OpenAI-compatible API through AIClient2API.

Features

• ✅ Uses your existing Droid CLI installation
• ✅ No need for API keys or token management
• ✅ Full Claude API compatibility
• ✅ Supports streaming and non-streaming responses
• ✅ Works with any OpenAI-compatible client

Prerequisites

1. Install Droid CLI

   # Install Droid CLI from Factory.ai
   # Visit: https://factory.ai/product/cli
   

2. Authenticate with Droid

   droid
   # Follow the prompts to login
   

Configuration

Using Command Line Arguments

node src/api-server.js \
  --model-provider droid-factory-oauth \
  --port 3000 \
  --api-key your-api-key

Using config.json

Add to your config.json:

{
  "MODEL_PROVIDER": "droid-factory-oauth",
  "PORT": 3000,
  "API_KEY": "your-api-key"
}

Using Environment Variables

export MODEL_PROVIDER=droid-factory-oauth
export PORT=3000
export API_KEY=your-api-key
node src/api-server.js

Usage

With OpenAI-Compatible Clients

Point your OpenAI-compatible client to the proxy:

import openai

client = openai.OpenAI(
    base_url="http://localhost:3000/v1",
    api_key="your-api-key"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-5-20250929",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

With Claude SDK

import anthropic

client = anthropic.Anthropic(
    base_url="http://localhost:3000",
    api_key="your-api-key"  # Your proxy API key, not Anthropic's
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Hello, Claude!"}
    ]
)

With curl

# Claude API format
curl http://localhost:3000/v1/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

# OpenAI API format
curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "claude-sonnet-4-5-20250929",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Supported Models

The Droid provider supports all Claude models available through Factory.ai:

• claude-sonnet-4-5-20250929 (default)
• claude-3-7-sonnet-20250219
• claude-3-5-sonnet-20241022
• claude-3-opus-20240229

How It Works

The proxy converts OpenAI/Claude API requests into droid exec commands and streams the results back:

1. Your app sends a request to the proxy (OpenAI or Claude format)
2. The proxy converts messages to a prompt
3. Executes droid exec "your prompt"
4. Streams the response back in the requested format

Troubleshooting

"Droid CLI is not installed or not in PATH"

Problem: The droid command is not available

Solution:

1. Install Droid CLI from https://factory.ai/product/cli
2. Make sure droid is in your system PATH
3. Test with: droid --version

"Droid command failed"

Problem: Droid CLI returned an error

Solution:

1. Make sure you are authenticated: droid
2. Test droid directly: droid exec "hello"
3. Check for any error messages from the droid CLI

Authentication Issues

Problem: Droid needs authentication

Solution:

1. Run droid to start an interactive session and authenticate
2. Follow the browser authentication flow
3. After authentication, the proxy will work automatically

Architecture

Your App → AIClient2API Proxy → droid exec command → Factory.ai
         (Port 3000)            (CLI process)

The Droid provider:

1. Receives API requests (OpenAI or Claude format)
2. Converts messages to prompt text
3. Spawns droid exec "prompt" process
4. Streams output back to client
5. Converts response to requested API format

Advanced Configuration

Custom Droid Command

If your droid CLI is installed with a different name or path:

{
  "MODEL_PROVIDER": "droid-factory-oauth",
  "DROID_COMMAND": "/custom/path/to/droid"
}

Security Considerations

1. API key protection: Use strong API keys for the proxy itself
2. Local execution: Droid CLI runs locally with your credentials
3. Use HTTPS in production: Don't expose the proxy over HTTP in production
4. Access control: Limit who can access your proxy server

Limitations

• Requires Droid CLI to be installed and authenticated
• Each request spawns a new droid exec process
• Streaming support depends on droid CLI output behavior
• Authentication is managed by Droid CLI (not the proxy)

Contributing

When contributing Droid-related changes:

1. Test with actual Droid CLI installation
2. Ensure both streaming and non-streaming work
3. Update this README with any new features
4. Follow the existing code patterns in the project

License

This provider follows the same license as the main AIClient2API project (GPLv3).