Controlling TokForge From Your Computer: API Walkthrough

A complete guide to the TokForge developer API. Start chats, manage models, read conversations, and check live status, all from your computer or another application.

What is the TokForge API?

TokForge includes a built-in local HTTP server, the developer API, with 270+ endpoints on Android for remote control and monitoring. Whether you want to start conversations, load models, read live status, or automate tasks on your phone from a desktop script, the TokForge API makes it possible.

The API is:

• Local: A small HTTP server that runs inside the app on your phone
• Bearer token authenticated: Every request needs an authorization header, except a few status probes such as /health and /version
• Local network friendly: Designed for LAN access or ADB forwarding
• Simple HTTP: GET to read, POST to change things, DELETE to remove things
• JSON-based: Request/response bodies in JSON format

The developer API listens on port 8088 by default and stays off until you turn it on in the app settings.

Enabling the API on Your Phone

Before you can connect from your computer, you'll need to enable the API server in TokForge settings.

Step-by-Step Setup

1. Open TokForge on your Android device
2. Navigate to Settings (gear icon) and open Connections, then set Settings Mode at the top to Advanced
3. Open "Developer tools (Advanced)". This section only appears in Advanced mode.
4. Turn on "Developer API server (Advanced)"
5. Set the "Access token": type your own secret or tap "Generate a new token". Every protected request must send it. The examples below use mytoken123 as a stand-in; use a strong token of your own.
6. Choose "Who can connect":
   • This phone only (127.0.0.1): reachable only from the phone itself or via ADB port forwarding (adb forward tcp:8088 tcp:8088). Use this for development and testing, or when your Wi-Fi blocks device-to-device traffic.
   • Any device on my network (0.0.0.0): reachable from any device on your LAN (e.g. http://192.168.1.100:8088/health). Use this for remote control from another computer, AI agents, or Home Assistant. Use only on trusted networks.
7. Copy the "API URL" shown in the same section. With "Any device on my network" it includes your phone's Wi-Fi address, so you do not need to look up the IP yourself.

The Play Store build honors your "Who can connect" choice. If you pick Any device on my network, the server listens on 0.0.0.0 and is reachable over your LAN on the normal Google Play build. You do not need a debug build or ADB to connect from another device. The default is This phone only (127.0.0.1) for safety, and the access token is required either way.

In short: Settings → Connections → Settings Mode: Advanced → Developer tools (Advanced) → Developer API server (Advanced).

Default port is 8088. You can change it under "Port number" if it clashes with something.

Connecting From Your Computer

Once the API is enabled, you have two options to connect: direct LAN access or ADB tunneling.

Option A: Direct LAN Access

If you bound the API to "All Interfaces" and your phone and computer are on the same network:

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/health

Replace 192.168.1.100 with your phone's actual IP address. A quick browser test works too: open http://192.168.1.100:8088/health in any browser on the same network. If you see a small block of JSON starting with {, the connection works (/health needs no token). For protected endpoints, send your token as an Authorization: Bearer <token> header.

If /health times out even though both devices are on the same Wi-Fi: some home/guest networks (and "AP isolation" / "client isolation" settings on the router) block devices from talking to each other. That's almost always the router, not TokForge. In that case, fall back to ADB Port Forwarding (Option B below), which connects over a USB/ADB cable instead of the network.

Option B: ADB Forwarding

If you bound the API to localhost only, use ADB to forward the port:

adb forward tcp:8088 tcp:8088

Then connect via localhost:

curl -H "Authorization: Bearer mytoken123" http://localhost:8088/health

Test Your Connection

Hit the health endpoint to verify your connection is working:

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/health

Expected response (shortened):

{
  "status": "ok",
  "mnn_loaded": true,
  "gguf_loaded": false,
  "any_model_loaded": true,
  ...
}

Essential Endpoints Walkthrough

Here's a detailed tour of the most commonly used endpoints. All examples assume your token is mytoken123 and your phone is at 192.168.1.100:8088.

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/health

{
  "status": "ok",
  "auto_tune_running": false,
  "device": {
    "model": "Pixel 9",
    ...
  },
  "mnn_loaded": true,
  "gguf_loaded": false,
  "any_model_loaded": true,
  "runtime_mb": <number>,
  "free_mb": <number>,
  "control_plane": {
    "uptime_ms": <number>,
    "request_count": <number>,
    "request_error_count": <number>
  }
}

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/models/downloaded

[
  {
    "id": 3,
    "name": "Qwen3.5 2B",
    "size_bytes": <number>,
    "model_type": "mnn",
    "context_length": <number>,
    "is_default": true,
    "model_section": "chat",
    "can_load_as_chat": true,
    ...
  },
  {
    "id": 5,
    "name": "Llama 3.2 3B",
    "size_bytes": <number>,
    "model_type": "mnn",
    "context_length": <number>,
    "is_default": false,
    "model_section": "chat",
    "can_load_as_chat": true,
    ...
  }
]

curl -X POST -H "Authorization: Bearer mytoken123" \
  http://192.168.1.100:8088/models/3/load

{
  "status": "ok",
  "model_id": 3,
  "model_name": "Qwen3.5 2B",
  "model_type": "mnn",
  "effective_context_length": <number>,
  ...
}

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/models/recommended

[
  {
    "id": "qwen3.5-2b-mnn",
    "name": "Qwen3.5 2B",
    "parameter_size": "2B",
    "model_type": "mnn",
    "size_gb": <number>,
    "min_ram_gb": 6,
    "hf_repo": "taobao-mnn/Qwen3.5-2B-MNN",
    "category": "general",
    "requires_auth": false,
    ...
  },
  ...
]

curl -X POST -H "Authorization: Bearer mytoken123" \
  -H "Content-Type: application/json" \
  -d '{"character_id": 2}' \
  http://192.168.1.100:8088/conversations/new

{
  "status": "ok",
  "conversation_id": 12,
  "character_name": "Aria",
  "backend_type": "mnn",
  "navigated": true,
  ...
}

The app navigates to chat when you create a conversation via API

curl -X POST -H "Authorization: Bearer mytoken123" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is machine learning?"}' \
  http://192.168.1.100:8088/conversations/12/send

{
  "status": "ok",
  "conversation_id": 12,
  "user_message_id": 341,
  "assistant_message_id": 342,
  "response": "Machine learning is a branch of artificial intelligence where systems learn patterns from data instead of being explicitly programmed...",
  "token_count": <number>,
  "backend": "mnn",
  "done": true,
  "finish_reason": "stop",
  ...
}

curl -H "Authorization: Bearer mytoken123" http://192.168.1.100:8088/characters

[
  {
    "id": 1,
    "name": "Assistant",
    "description": "A plain, no-persona AI assistant. No character voice, no roleplay framing...",
    "creator": "TokForge",
    "is_favorite": false,
    "has_first_message": false,
    ...
  },
  {
    "id": 2,
    "name": "Aria",
    "description": "Aria is a warm, articulate AI assistant who genuinely enjoys helping people work through problems...",
    "personality": "Warm, patient, intellectually curious, honest about limitations...",
    "creator": "TokForge",
    "is_favorite": false,
    ...
  }
]

curl -H "Authorization: Bearer mytoken123" \
  "http://192.168.1.100:8088/memory/facts?character_id=2"

[
  {
    "id": 17,
    "character_id": 2,
    "category": "...",
    "content": "User's name is Alex",
    "importance": <number>,
    "is_pinned": false,
    ...
  },
  {
    "id": 18,
    "character_id": 2,
    "category": "...",
    "content": "User prefers dark mode",
    "importance": <number>,
    "is_pinned": false,
    ...
  }
]

curl -H "Authorization: Bearer mytoken123" \
  "http://192.168.1.100:8088/memory/stats?character_id=2"

{
  "character_id": 2,
  "facts": <number>,
  "edges": <number>,
  "documents": <number>
}

curl -X POST -H "Authorization: Bearer mytoken123" \
  http://192.168.1.100:8088/control/open-model-browser

{"status": "ok", "screen": "models"}

curl -X POST -H "Authorization: Bearer mytoken123" \
  http://192.168.1.100:8088/control/open-forge-lab

{"status": "ok", "screen": "forge"}

curl -H "Authorization: Bearer mytoken123" \
  http://192.168.1.100:8088/control/generation-status

{
  "mnn_loaded": true,
  "gguf_loaded": false,
  "live_generation": {
    "active": true,
    "status": "...",
    "conversation_id": 12,
    "backend": "mnn",
    ...
  },
  ...
}

curl -H "Authorization: Bearer mytoken123" \
  http://192.168.1.100:8088/settings

{
  "user_name": "...",
  "metrics_server_enabled": true,
  "metrics_server_port": 8088,
  "metrics_server_bind_host": "0.0.0.0",
  "metrics_auth_token_set": true,
  "theme_mode": "DARK",
  ...
}

curl -X POST -H "Authorization: Bearer mytoken123" \
  -H "Content-Type: application/json" \
  -d '{"value": "LIGHT"}' \
  http://192.168.1.100:8088/settings/theme_mode

{"status": "ok", ..., "saved": {"theme_mode": "LIGHT", ...}}

curl -H "Authorization: Bearer mytoken123" \
  "http://192.168.1.100:8088/debug/logcat?lines=200"

Build a Simple Python Script

Let's create a practical Python script that connects to TokForge, lists models, starts a conversation, and sends messages.

Requirements:

• Python 3.7+
• requests library: pip install requests

Complete working example:

import requests
import json
import time

# Configuration
API_BASE = "http://192.168.1.100:8088"
TOKEN = "mytoken123"

def get_headers():
    """Return headers with bearer token"""
    return {
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json"
    }

def check_health():
    """Check API health"""
    response = requests.get(f"{API_BASE}/health", headers=get_headers())
    return response.json()

def list_models():
    """List downloaded models"""
    response = requests.get(f"{API_BASE}/models/downloaded", headers=get_headers())
    return response.json()

def find_character(name):
    """Look up a character's id by name"""
    response = requests.get(f"{API_BASE}/characters", headers=get_headers())
    for character in response.json():
        if character["name"] == name:
            return character["id"]
    raise ValueError(f"No character named {name}")

def start_conversation(character_id):
    """Start a new conversation"""
    data = {"character_id": character_id}
    response = requests.post(
        f"{API_BASE}/conversations/new",
        headers=get_headers(),
        json=data
    )
    return response.json()

def send_message(conversation_id, message):
    """Send a message in a conversation"""
    data = {"message": message}
    response = requests.post(
        f"{API_BASE}/conversations/{conversation_id}/send",
        headers=get_headers(),
        json=data
    )
    return response.json()

# Main execution
if __name__ == "__main__":
    print("Checking API health...")
    health = check_health()
    print(f"Status: {health.get('status')}")
    print(f"Model loaded: {health.get('any_model_loaded')}")
    print()

    print("Listing downloaded models...")
    models = list_models()
    for model in models:
        print(f"  - {model['name']} ({model['model_type']})")
    print()

    print("Starting conversation with Aria...")
    conv = start_conversation(find_character("Aria"))
    conv_id = conv["conversation_id"]
    print(f"Conversation started: {conv_id}")
    print()

    print("Sending message...")
    result = send_message(conv_id, "What is Python?")
    print(f"AI: {result['response'][:100]}...")
    print(f"Finished: {result.get('finish_reason')}")

Save this as tokforge_client.py and run:

python tokforge_client.py

Expected output:

Checking API health...
Status: ok
Model loaded: True

Listing downloaded models...
  - Qwen3.5 2B (mnn)
  - Llama 3.2 3B (mnn)

Starting conversation with Aria...
Conversation started: 12

Sending message...
AI: Python is a high-level, interpreted programming language known for its simplicity...
Finished: stop

Security Considerations

The TokForge API is designed for local network use. Follow these best practices:

Bearer Token Authentication

Always use a strong, randomly generated token. Avoid simple tokens like 123456 or password. The easiest way is to tap "Generate a new token" in the app and copy the result. Example strong token:

akfj9s8df-jklsd9-fjsdklf-sdfj9sdkfj

Network Binding

• This phone only (127.0.0.1): Most secure, only reachable from the device itself or via ADB port forwarding. The default. Good for development, or when your network blocks device-to-device traffic.
• Any device on my network (0.0.0.0): Reachable from any device on your LAN. The Play Store build honors this setting and listens on 0.0.0.0. The access token is still required. Use only on trusted networks (home WiFi, corporate VPN). Never on public WiFi.

No HTTPS

The API runs over HTTP without encryption. This is safe for local networks only. Never expose the API to the public internet.

Token Storage

If using the API in scripts, store the token in environment variables, not hardcoded:

import os
TOKEN = os.getenv("TOKFORGE_TOKEN")

Next Steps

You now have all the tools to build powerful automations and integrations with TokForge. Here's what to explore next:

Useful Resources

• Full API Reference: Endpoint documentation for the 270+ endpoints on Android
• AI Agent Guide: Build complex automation workflows using the API
• Developer Docs: Architecture, authentication, best practices
• Community: Share your scripts and integrations with other TokForge developers

Have a cool use case? Share your API integration with the TokForge community and help others build amazing things.