Skip to content

Run a community

Local broker

Use Bash for these snippets. Windows PowerShell users should follow Windows contributors.

git clone https://github.com/sqe/open-compute.git
cd open-compute
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
export OPEN_COMPUTE_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export OPEN_COMPUTE_JOIN_KEY="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
printf 'Enrollment key: %s\nAdministrator token: %s\n' \
  "$OPEN_COMPUTE_JOIN_KEY" "$OPEN_COMPUTE_ADMIN_TOKEN"
open-compute serve

Open http://127.0.0.1:8099. The secrets must be distinct and at least 24 characters. Keep them outside Git. The broker binds to localhost by default; OPEN_COMPUTE_DB selects its SQLite file. Back up that file consistently while the service is stopped. Tokens are hashed, but prompts/results are plaintext.

First task: use the browser

Keep the broker terminal running. In the browser at http://127.0.0.1:8099:

  1. Enter a worker name and the enrollment key printed in your terminal.
  2. Accept the consent text and click Start contributing.
  3. In Coordinate, enter the administrator token, select CPU proof demonstration, and click Queue task.
  4. Wait for completion and verified proof credit, then click Stop now.

No separate worker process or submission terminal is needed for this demo. Keep the page visible while it works. Press Ctrl+C in the broker terminal to stop the server. The generated keys are private; do not publish terminal output. Contributors receive only the enrollment key, not the administrator token.

Optional CLI worker

For a headless or remote device, use the Python worker instead of a browser. In an activated terminal on that device, set its community's enrollment key:

# Worker terminal: enrollment key only.
read -s OPEN_COMPUTE_JOIN_KEY
export OPEN_COMPUTE_JOIN_KEY
open-compute worker --name my-laptop

Use --broker https://YOUR-BROKER-HOST for another machine. The local default is http://127.0.0.1:8099. You can still queue tasks in the coordinator's browser UI. For scripts, the optional submission command uses administrator credentials:

# In an activated coordinator shell, not on an untrusted worker.
read -s OPEN_COMPUTE_ADMIN_TOKEN
export OPEN_COMPUTE_ADMIN_TOKEN
open-compute submit --payload '{"zero_bits":12,"attempts":100000}'

The worker persists its individual credential in a mode-0600 JSON file. Use a separate credential file for each broker or worker role. A role change updates advertised capabilities on reconnect. Never commit credential files.

Browser and phone participation

Enter a worker name and enrollment key, read the consent text, and press Start contributing. Work runs in a Web Worker; the page stays responsive. Stop now terminates the worker. An unfinished task becomes available after its lease expires. Browser credentials are stored in local storage; use your own browser profile and clear site storage to forget them.

For real phones, put the broker behind an HTTPS reverse proxy reachable from the device. Bind an explicitly chosen interface with --host; configure TLS, firewall policy, request-size limits and rate limits before exposing it. Do not publish the development server directly to the Internet. GitHub Pages serves documentation only; it does not host the broker or store credentials.

iOS and Android browser/GPU availability vary. No native background app is included. Charging is recommended; a low-battery check is best effort because many browsers do not expose battery state. There is no reliable cross-browser thermal sensor, and cooling or battery safety is not guaranteed by software.

QR onboarding

Set OPEN_COMPUTE_PUBLIC_URL=https://YOUR-BROKER-HOST before starting the broker. It must be the reachable HTTPS origin, with no credentials, path, query or fragment. Configure TLS/reverse proxy separately; this setting does not create it. In the coordinator UI, enter the administrator token and press Show enrollment QR. The code contains only that public page URL, never the enrollment key, administrator token or individual device credential. Send the enrollment key through a separate secure channel. Scanning opens a page; it does not install an app, enroll a device, start computing or pair/synchronize accounts.

Saved local credentials let the same browser reconnect. Cross-device credential sync, native application installation and automatic cluster access are not implemented. QR codes are links, not authentication or proof of a trusted site.