Server#

Prerequisites#

• A Linux host (Blockyard runs as a container or native binary)
• One of:
  • Docker backend: Docker or Podman with a Docker-compatible socket, or
  • Process backend: bubblewrap (bwrap) and R installed on the host. Linux only.

See Backend Security for the trade-offs between the two backends and guidance on which to pick.

Image variants#

Three pre-built images are published to ghcr.io/cynkra/:

:latest tracks the most recent release on each variant.

Running with Docker (Docker backend)#

The easiest way to run the Docker-backend variant is as a container with access to the host’s Docker socket:

docker run -d \
  --name blockyard \
  -p 8080:8080 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v blockyard-data:/data \
  -e BLOCKYARD_DOCKER_IMAGE=ghcr.io/cynkra/blockyard-worker:4.4.3 \
  ghcr.io/cynkra/blockyard-docker:latest

This gives Blockyard access to Docker for spawning worker containers, and persists application data (bundles, database) in a named volume.

Running with the process backend#

The process backend avoids the Docker socket mount entirely by sandboxing workers with bubblewrap instead. It has two deployment modes:

• Process Backend (Native) — run blockyard directly on a Linux host with bwrap and R installed.
• Process Backend (Containerized) — run the blockyard-process image with a custom seccomp profile. No Docker socket, no CAP_SYS_ADMIN.

The containerized variant is the recommended choice for deployments that cannot bind-mount the Docker socket.

API authentication requires OIDC configuration and Personal Access Tokens. See the Authorization guide for details.

Running from source#

git clone https://github.com/cynkra/blockyard.git
cd blockyard
go build -o blockyard ./cmd/blockyard

Copy and edit the example configuration:

cp blockyard.toml my-config.toml
# Edit my-config.toml — at minimum, set docker.image

Run the server:

./blockyard -config my-config.toml

Verifying the installation#

curl http://localhost:8080/healthz
# => 200 OK

CLI#

The by command-line client lets you deploy and manage apps from your terminal. See the CLI Reference for the full command list.

Quick install (Linux, macOS)#

One-liner that downloads the matching release binary, marks it executable, and drops it into /usr/local/bin:

curl -fsSL https://cynkra.github.io/blockyard/install.sh | sh

Install a specific version or a custom directory:

curl -fsSL https://cynkra.github.io/blockyard/install.sh | sh -s -- \
  --version v0.1.0 --install-dir "$HOME/.local/bin"

Switch to the rolling main channel (rebuilt on every push to main):

curl -fsSL https://cynkra.github.io/blockyard/install.sh | sh -s -- --channel main

--channel stable (default) tracks the latest tagged release. --channel main and --version are mutually exclusive — use one or the other.

The same script installs the blockyard server binary when invoked with --server (Linux only — for other platforms run the container image):

curl -fsSL https://cynkra.github.io/blockyard/install.sh | sh -s -- --server

The main channel only publishes the by CLI; the rolling server is distributed as the ghcr.io/cynkra/blockyard:main container image, so --channel main --server is refused.

Environment variables BLOCKYARD_CHANNEL, BLOCKYARD_VERSION, BLOCKYARD_INSTALL_DIR, and BLOCKYARD_BINARY seed the defaults; passing the matching flag still wins. Piping to sh is optional — download the script first to inspect it if you prefer.

Download a release binary#

Pick the asset that matches your platform:

Download it and place it on your PATH. The -f flag makes curl exit with an error on HTTP failures (e.g. 404) instead of saving the error page as your binary:

# Replace <asset> with the filename from the table above
curl -fLo by https://github.com/cynkra/blockyard/releases/latest/download/<asset>
chmod +x by
sudo mv by /usr/local/bin/

You can also grab the binary directly from the releases page.

Build from source#

If you have Go 1.25+ installed:

go install github.com/cynkra/blockyard/cmd/by@main

@main tracks the current main branch — the most recent release tag predates the by CLI, so @latest will not yet resolve a working version.

Or clone and build:

git clone https://github.com/cynkra/blockyard.git
cd blockyard
go build -o by ./cmd/by
sudo mv by /usr/local/bin/

Verify#

by --help

Log in#

After installing, authenticate against your Blockyard server:

by login --server https://blockyard.example.com

This opens your browser to create a Personal Access Token and stores the credentials in ~/.config/by/config.json. See Quick Start for a full walkthrough.