TikMatrix Desktop

TikMatrix is a desktop application designed to automate TikTok and Instagram on connected Android phones. It supports multi-account management, bulk posting, follower and DM automation, and task scheduling across device farms.

While the desktop application itself is closed source, this repository provides the SDKs and interfaces required to build custom automation scripts that drive the connected devices.

This repository contains the developer-facing components for building on top of TikMatrix:

• sdk/python/: The Python client and usage examples for the custom-script API.
• scripts/: Operational helper scripts.
• .github/workflows/: Build pipelines for the desktop app, script binaries, and APKs.

Note: The desktop application itself is proprietary and not covered by the MIT license used for the SDK and workflows.

When registering a managed script, you can specify a platform mode to control how the device is prepared:

• generic: The device is handed over untouched. No apps are started or stopped, and no account switching occurs. Use this for non-TikTok/Instagram automation.
• tiktok / instagram: The app is automatically opened and the account is switched before your script starts. The app is closed after your script finishes.

Use the TIKMATRIX_PACKAGE environment variable to identify which package was resolved for the selected platform.

A device lease ensures that only one process drives a phone at a time.

• Concurrency: A lease consumes one device slot from your plan. A Pro plan with 20 devices allows 20 concurrent sessions (tasks, scripts, or a mix).
• Lifecycle: Leases expire after a default of 120 seconds. The SDK automatically renews them on a background thread. Using a with block ensures the lease is released immediately when the block exits.
• Safety: If a script crashes, the lease expires and the device is freed within seconds.

In Standalone mode, you run the program yourself and use the SDK to manually discover and lease devices. This is useful for local development or custom orchestration.

Use the TikMatrix() client to list available devices and the client.device() context manager to lease a specific device by its serial number.

from tikmatrix import TikMatrix

client = TikMatrix()

for device in client.devices():
    if device["busy"]:
        continue
    with client.device(device["serial"], label="my crawler") as d:
        d.press("home")
        print(d.info())

In Managed mode, you register your script in the TikMatrix dashboard (Devices → Custom Scripts → Add Script). TikMatrix handles queueing, concurrency, retries, and scheduling.

When running as a managed task, the device is already leased, and you should use TikMatrix.from_env() to access the device via environment variables provided by the TikMatrix agent.

from tikmatrix import TikMatrix

# The device is already leased; its id arrives in the environment.
with TikMatrix.from_env() as d:
    d.click(text="Log in")
    print("done")     # stdout lands in the task log

The TikMatrix Python SDK is a single-file client (tikmatrix.py) that requires the requests library. It is recommended to place tikmatrix.py in the same directory as your script rather than installing it as a package.

Run the following commands to set up your environment:

pip install requests
curl -O https://raw.githubusercontent.com/tikmatrix/tikmatrix-desktop/main/sdk/python/tikmatrix.py

The API returns errors in the format {"code": N, "message": "..."}. Common status codes include:

• 403: Plan is below Pro, no active lease, lease has expired, or ADB is disabled in Settings.
• 409: Device is already leased, or your plan has no available device slots.

The TikMatrix device object (d) provides several methods for interacting with the device via UIAutomator2 and ADB:

| Method | Description | |---|---|d.info()| Get device info | | d.window_size()| Returns (width, height) | | d.screenshot("path.png")| Saves screen as PNG | | d.find(text="...")| Matches nodes with bounds + center | | d.exists(resource_id="...")| Checks if element exists | | d.wait_for(text="...", timeout=N)| Blocks until element appears | | d.click(text="...")| Waits, then taps the center | | d.click_xy(x, y)| Taps specific coordinates | | d.swipe(x1, y1, x2, y2)| Performs a swipe | | d.press("...")| Presses keys like back, home, recent, enter | | d.input_text("...")| Types text via bundled IME | | d.jsonrpc("method")| Call any UIAutomator2 method | | d.adb("shell", ...)| Run ADB commands (requires enabling in Settings) |

The TikMatrix local API is a plain JSON-over-HTTP service. It is unauthenticated but requires an x-session-id header for device calls. Note that it does not send CORS headers, so it should be called from a program, not a browser.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/api/v1/rpc/devices` | List online devices |
| `POST` | `/api/v1/rpc/session` | Lease a device → `session_id` |
| `POST` | `/api/v1/rpc/session/{id}/heartbeat` | Extend the lease |
| `DELETE` | `/api/v1/rpc/session/{id}` | Release |
| `GET` | `/api/v1/rpc/session` | List live leases |
| `POST` | `/api/v1/rpc/jsonrpc` | Call a UIAutomator2 method |
| `POST` | `/api/v1/rpc/adb` | Run an ADB command |
| `GET` | `/api/v1/rpc/hierarchy?serial=` | UI tree as XML |
| `GET` | `/api/v1/rpc/screenshot?serial=` | Screen as PNG |

When a managed script is dispatched to a device, the following environment variables are available:

| Variable | Meaning |
|---|---|
| `TIKMATRIX_API_BASE` | Server URL, default `http://127.0.0.1:50809` |
| `TIKMATRIX_SESSION_ID` | Lease id (managed scripts only) |
| `TIKMATRIX_SERIAL` | Device this task was dispatched to |
| `TIKMATRIX_PACKAGE` | Resolved app package |
| `TIKMATRIX_PLATFORM` | `tiktok`, `instagram`, or `generic` |