Running ObitCC Headless

What is ObitCC Headless?

ObitCC Headless is a command-line tool that lets you contribute computing power to the ObitCC distributed computing network without needing to keep a browser window open. It runs Chromium in headless mode (no visible window) and automatically connects to the network, processes workloads, and contributes to distributed AI/ML tasks.

Perfect for:

• Dedicated compute servers

• Home servers or spare machines

• 24/7 automated contribution

• Docker containers

Quick Start

Prerequisites

Before you start, you'll need:

1. A valid API key - Get one from your ObitCC dashboard with "API > Show my key"

2. The ObitCC server URL - https://cc.obitmc.com unless you've received a custom URL from Obit staff

3. Chromium or Google Chrome - The headless browser needs to be installed on your system

Installation

Installing and Running

Download the appropriate binary for your system from the GitHub releases page, then run it with the appropriate args:

Linux (Intel/AMD):

chmod +x cc-headless-linux-amd64
./cc-headless-linux-amd64 -k YOUR_API_KEY -u https://cc.obitmc.com

Linux (ARM64 - Raspberry Pi 4+, ARM servers):

chmod +x cc-headless-linux-arm64
./cc-headless-linux-arm64 -k YOUR_API_KEY -u https://cc.obitmc.com

macOS (Apple Silicon):

chmod +x cc-headless-macos-arm64
./cc-headless-macos-arm64 -k YOUR_API_KEY -u https://cc.obitmc.com

macOS (Intel):

chmod +x cc-headless-macos-amd64
./cc-headless-macos-amd64 -k YOUR_API_KEY -u https://cc.obitmc.com

Windows:

cc-headless-windows-amd64.exe -k YOUR_API_KEY -u https://cc.obitmc.com

Using Environment Variables

Instead of using the -k and -u arguments, you may also use a .env file.

Create a .env file in the same directory:

APIKEY=your_api_key_here
URL=https://cc.obitmc.com

Then simply run (replace this binary with the appropriate one for your system architecture):

./cc-headless-linux-amd64

The application will automatically load the credentials from the .env file.

Basic Usage

Command-Line Options

cc-headless [options]

Options:
  -k, --apikey <key>     Your ObitCC API key (required)
  -u, --url <url>        Server URL to connect to (required)
  -v, --verbose          Enable verbose logging (see all browser console output)
  -h, --help             Show help message

Examples:
  cc-headless -k abc123 -u http://localhost:3000
  cc-headless -k abc123 -u https://production.example.com -v
  cc-headless --help

How it Works

This is the high-level overview of what the application does:

1. Environment Check - Verifies your API key and URL are valid

2. GPU Detection - Tests if your system supports WebGPU hardware acceleration

3. Browser Launch - Starts Chromium in headless mode with WebGPU enabled

4. Authentication - Automatically logs in using your API key

5. Connection - Connects to the ObitCC network and starts processing workloads

6. Continuous Operation - Runs indefinitely, processing jobs as they arrive

Verbose Mode

Use the -v flag to see detailed browser console output, including:

• WebGPU backend selection (useful to see what backend is being used, e.g webgpu/webgl/wasm/cpu - non-webgpu backends will perform worse and you won't make as much)

• Model loading progress

• Training metrics (loss, accuracy, batch progress)

• Network communication logs

./cc-headless-linux-amd64 -k YOUR_API_KEY -u https://cc.obitmc.com -v

This is useful for debugging or monitoring exactly what your node is processing.

Other use-cases

Check out the Running as a Service and Running in Docker pages if you wish to run cc-headless 24/7

Getting Help

If you encounter issues:

1. Check logs - Run with -v for verbose output

2. Test GPU support - Ensure WebGPU is working on your system

3. Verify credentials - Double-check API key and server URL

4. Documentation - See the Troubleshooting page

5. Support - Contact us at [email protected] or through our Discord and we'll try our best to resolve the issue.

Next Steps

Once your headless worker is running:

• Monitor performance in your ObitCC dashboard. Credits will be accumulated in the account that you are currently using. You will not be able to use the same account from two computers at once; create an API account via the "API" link in the header if you wish to use two workers at once and receive credit on one account.

• Track contributions and rewards

• Scale up by adding more workers

• Join our community to share tips or troubleshoot

Happy computing!