cydeai-client 0.1.4

CLI client for Cysic decentralized AI providers

cydeai-client Wheel Release Usage Notes

Use this document as the user-facing usage note when publishing a new cydeai-client wheel.

Package

Install package:

python -m pip install cydeai-client==0.1.4

Installed CLI command:

cydeai

Check installation:

cydeai --help

What This Client Does

cydeai runs on a provider GPU machine. It:

• checks local NVIDIA GPU and vLLM readiness
• verifies vLLM is actually using GPU memory
• connects to cydeai-server through WebSocket
• registers the worker with model and endpoint metadata
• forwards gateway traffic to the local vLLM OpenAI-compatible endpoint

The client does not install or start vLLM, install models, configure systemd, perform chain transactions, or manage system packages.

Requirements

Run on a Linux GPU provider machine with:

• Python 3.11+
• NVIDIA driver and nvidia-smi
• vLLM already running
• local vLLM OpenAI-compatible API, usually http://127.0.0.1:8000/v1
• a server-issued provider API key
• a server URL, for example https://<server-host>/<base-path>

macOS can be used for basic CLI smoke tests, but cydeai check is expected to fail there if nvidia-smi is unavailable.

Basic Setup

Create a virtual environment:

python3 -m venv ~/cydeai-client-env
. ~/cydeai-client-env/bin/activate
python -m pip install -U pip
python -m pip install cydeai-client==0.1.4

Confirm the local vLLM model name:

curl -sS http://127.0.0.1:8000/v1/models | python3 -m json.tool

Create the default config file:

mkdir -p ~/.config/cydeai
cat > ~/.config/cydeai/config.toml <<EOF
server_url = "https://<server-host>/<base-path>"
api_key = "<provider_api_key>"
worker_name = "<worker-display-name>"
model_name = "<served-model-name-from-vllm>"
model_port = 8000
EOF
chmod 600 ~/.config/cydeai/config.toml

For released-wheel usage, prefer config-file based setup. The CLI still applies this precedence internally:

CLI args > environment variables > config file > defaults

Local Readiness Check

Before connecting to the server, run:

cydeai check --json

The check passes only when:

• at least one NVIDIA GPU is detected
• at least one GPU has memory usage greater than 10%
• at least one vLLM process exists
• at least one vLLM PID appears in the nvidia-smi GPU process list

If this fails, fix the local vLLM/GPU state first.

Dry Run

Dry run does not connect to the server. It prints the WebSocket URL, masked headers, local check result, and register payload:

cydeai connect --dry-run

If api_key in config is set, the output should include a masked header:

{
  "headers": {
    "PROVIDER_SIGN": "********"
  }
}

The worker id is generated automatically from the machine MAC address unless --worker-id is provided explicitly for integration testing:

{
  "register_control": {
    "payload": {
      "worker_id": "w-..."
    }
  }
}

One-Shot Register Test

Use this to validate WebSocket handshake and worker registration without keeping the worker online:

cydeai connect --exit-after-register

Expected success:

{
  "registered": true,
  "status": "available"
}

Common failures:

• http_401: API key is missing, stale, or invalid
• http_403: provider or key is rejected by server policy
• model not allowed: server does not allow this model name
• local check failure: vLLM/GPU readiness gate failed before network connect

In long-running cydeai connect mode, http_401 and http_403 are retried with exponential backoff and jitter instead of stopping the process. They still usually indicate a key or server-side provider/worker state problem that should be checked by the operator.

Start Long-Running Worker

Run the worker in the foreground:

PYTHONUNBUFFERED=1 cydeai connect

Successful startup prints JSON events similar to:

{"event":"connect_attempt","attempt":1}
{"event":"registered","worker_id":"w-...","result":{"registered":true,"status":"available"}}

Keep this process running.

Notes For Release Announcements

When announcing a wheel release, include:

• package name: cydeai-client
• CLI command: cydeai
• version: 0.1.4
• install command: python -m pip install cydeai-client==0.1.4
• required Python version: Python 3.11+
• reminder that vLLM must already be running locally
• reminder that api_key should be set in ~/.config/cydeai/config.toml
• reminder that cydeai connect emits JSON by default