library_name: coven license_name: MPL-2.0 + Commons Clause 1.0 language: en compatibility:

• macos
• linux
• windows

⌜ ᐸ ᐊ ᐯ Ⲷ Ⲡ ⌟
_{distributed research platform}#

COVEN is software for cooperative computation. It reduces the hardware demands of research by relying on encrypted peer-to-peer (p2p) coordination between everyday computers, pooling their capabilities to accelerate work for deep learning inference, training, and dataset storage.

Share scientific workloads up to the sum force of your COVEN's computers. Host translation, text-to speech, text-to-image, or audio services. Run language models too big for any one computer using llama.cpp. Train or fine-tune machine learning weights and adapters at exponentially faster speeds than a lone PC. Glaze every work of art on the planet together. Grow resilient, efficient networks instead of funding new datacenters.

DARKSHAPES #

Minimum Requirements#

Experience#

• Familiarity with using Terminals/Command Line Interfaces (CLI).

Hardware#

• Any of:
  • Apple Mac with M-series Unified Chip
  • GNU/Linux system with CPU, NVIDIA 20xx+ graphics, AMD graphics, or any Vulkan-compatible chipset.
  • Windows PC with Windows Subsystem for Linux

Software#

• zsh shell
• just to build library
• brew package manager (only required for MacOS)

Optional#

• pnpm to build UI. Auto-installs otherwise.
• node to build sandboxes or mesh-llm. Auto-installs otherwise.
• GNU/Linux systems require:
  • zsh.
  • nvcc (NVIDIA CUDA Toolkit), HIP/ROCm libraries (AMD ROCm), or glslc (Vulkan) for GPU support
• Windows can be used, but support is unstable. It allows client-node only, and is NOT sandboxed. Requires git

Setup#

1. Open a Terminal window and clone this repo:

git clone https://tangled.org/did:plc:okz7ln6fsh4edhazevnrwsyi coven
cd coven

2. Install covn

just build

If pnpm, cargo, nvcc require installation, reopen and rerun the build command.

3. Run covn

covn -h

Usage#

Toggle framework options

covn serve switch # Cycle model serving options
covn group switch # Cycle system clustering options

Serving models

covn serve --join 1337e57 # join an existing mesh
covn serve --name coven --model ibm-granite/granite-4.1-3b-GGUF:Q4_K_M # launch a mesh and wait for peers

Training models

covn train --join # sets up the node on the device
covn train --peers 1337e57, b14b14b14 --repo https://github.com/<someones>/<repo> # form the mesh, check the repo clone at ~/.local/share/covn/<repo>, then begin training

Grouping nearby computers together into a shared endpoint

covn group --join

Stop running daemons

covn serve stop # stop only serving daemon
covn stop # stop all daemons

View status of launched processes

covn serve status # Cycle model serving framework options

Architecture:#

COVEN is a thin wrapper meant to coordinate other packages towards a single goal. Individual commands become detached processes through the main covn command and launched as local daemons with unified arguments. Components run independently and can be swapped in and out as necessary. We use a deck of lightweight software, including a custom asynchronous training system variant of drift package.

Structure#

cli                        package                    purpose
---------------------------------------------------------------------------------------
                    .---> tahoe-lafs              p2p distributed storage
                   /
                  /  .---> cake / exo             mdns local clustering
                 /  /
                /  /  .---> mesh-llm / parallax   p2p distributed/sharded inference
     nocturne  /  /  /
covn-------:--:--:--:
            \     \  \
             \     \  `----> trackio              python experiment tracking
              \     \
               \     `----> drift                 p2p distributed heterogenous training
                \
                 `---> fence / sandbox-runtime    policy network/command isolation[optional]

Included Libraries#

• H4 Tolerance (see CONTRIBUTING.md)
• Distributed
• Optional Auth Layer
• Open Source
• Maintained

Commands Reference#

COVEN Distributed Research Platform

Usage: covn [SANDBOX] [COMMAND]

Commands:
  group  Create or join devices as a single inference server.
  serve  Start server to handle inference requests.
  train  Standby for or start model training with distributed peers.
  store  Start the distributed file storage service.
  stop   Stop all running processes (group, serve, train, store).
  help   Print this message or the help of the given subcommand(s)

Arguments:
  [SANDBOX]

Options:
  -h, --help  Print help (see more with '--help')

just command options

Available recipes:
    [ main ]
    build                 # Install COVEN and `covn` command with default distributed options(mesh/drift).
    info                  # Show detected system information and locations for installation.

    [device cluster]
    build-cake            # Install Cake. Cluster local network devices into a single multimodal Candle inference server.
    build-exo             # Install EXO. Cluster MacOS devices over local network/RDMA into a single MLX inference server.

    [inference]
    build-mesh-llm        # Install Mesh-LLM. Inference over distributed network. Can split tensor/experts using llama.cpp.
    build-parallax        # Install Gradient Parallax, a pipeline-parallel model serving framework built on SGLang and MLX.

    [nocturne]
    build-covn            # Install `covn` CLI, Python environment, essential packages (Tahoe-LAFS, Trackio, PyTorch)

    [sandboxes]
    build-fence           # Install Fence sandbox. Enables sandbox prefix to limit access rights.  e.g. `covn sandbox train <args>`
    build-srt             # Install Sandbox-Runtime. Enables sandbox prefix to limit access rights.  e.g. `covn sandbox train <args>`
    config-fence          # Set Fence config. `coven/srt-settings.json` edits migrate to `~/.config/srt-settings.json`.
    config-srt            # Set Sandbox-Runtime config. `coven/srt-settings.json` edits migrate to `~/.config/srt-settings.json`.

    [tools]
    base-tools            # Instal packaging and download tools (uv, cargo, git-xet).
    build-tools           # Instal build tools (cmake, ninja, sccache, lld, node).
    check-package-manager
    check-ready           # Show installed processes.
    cleanup_build         # Destroy project tempprary build directories.
    cleanup_cache         # Manually destroy cached downloads.
    is-old-cuda           # Determine whether CUDA device belongs to legacy hardware.
    target                # Detect GPU backend using native just if/command syntax.

    [training]
    build-drift           # Install Drift, a distributed ml training system that works over Iroh network.
    build-drift-upstream  # Install upstream Drift. Needs fast/local device connection for shared memory and synchronization.

• On MacOS, building drift may require firewall permission for integration, stress, and training packages in addition to mesh-llm/drift
• Building may rest config files. Be sure to back up any changes to ~/.mesh-llm/config.toml and ~/.srt-settings.json

See nocturne/README.md,mesh/README.md, drift/README.md for individual package info.

Ref: https://arxiv.org/abs/2604.14561 https://arxiv.org/abs/2602.02192 https://arxiv.org/abs/2602.08387 https://arxiv.org/abs/2601.06857 https://arxiv.org/abs/2509.26182 https://arxiv.org/abs/2505.15306 https://arxiv.org/abs/2504.17096 https://arxiv.org/abs/2501.05450