Blockyard

CLI Reference

Mon, 01 Jan 0001 00:00:00 +0000

by is the command-line client for Blockyard. It handles authentication, deployment, app management, and administration from your terminal.

Global flags#

Flag	Description
`--json`	Output machine-readable JSON (all commands)

When --json is set, all output (including errors) is printed as pretty-printed JSON. Errors use the shape {"error": "...", "message": "..."}.

Authentication#

`by login`#

Store credentials interactively. Opens a browser to create a Personal Access Token, then verifies it against the server.

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

Flag	Description
`--server <url>`	Server URL (prompts interactively if omitted)

Credentials are saved to ~/.config/by/config.json (respects $XDG_CONFIG_HOME) with file mode 0600.

Deploying an App

Mon, 01 Jan 0001 00:00:00 +0000

Bundle structure#

A bundle is a .tar.gz archive containing your Shiny app source. At minimum it needs:

app.R (or ui.R + server.R) — the Shiny application code

Optionally include dependency metadata in one of these formats (highest priority first): manifest.json, renv.lock, or DESCRIPTION. If none is present, Blockyard scans your scripts to discover dependencies automatically.

Any additional files (data, assets, R scripts sourced by the app) are included automatically when you tar the directory.

What is Blockyard?

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard is a self-hosted platform for running blockr applications in production. blockr apps evaluate user-supplied R expressions inside every session, which is a security model no general-purpose Shiny host was designed for. Blockyard provides hardened container-per-session isolation, per-user credential management via OpenBao, server-side dependency resolution, and built-in board storage — the full blockr stack as a single binary.

How it works#

You deploy a bundle — run by deploy ./my-board or upload a .tar.gz archive via the REST API. Bundles can include dependency metadata (renv.lock, DESCRIPTION, or manifest.json), or none at all — the server discovers what’s needed.
Blockyard resolves dependencies server-side — it spins up a build container and uses pak to install packages. Unpinned bundles can be refreshed in place later without a redeploy.
Users visit the app — when a request hits /app/<name>/, Blockyard spawns a worker container on demand and reverse-proxies HTTP and WebSocket traffic to it. Each session gets its own container.

Workers are isolated from each other via per-container bridge networks. Containers run with a read-only filesystem, all Linux capabilities dropped, no-new-privileges set, and cloud metadata endpoint access blocked (169.254.169.254). For high-security deployments, workers can run under the Kata runtime, which gives each session its own lightweight VM. See Deploying an App for the full list of security settings.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard is configured via a TOML file. By default, it looks for blockyard.toml in the current directory. Override the path with the --config CLI argument:

blockyard --config /etc/blockyard/config.toml

Every config field can also be overridden via environment variables using the pattern BLOCKYARD_<SECTION>_<FIELD> (uppercased). For example:

BLOCKYARD_SERVER_BIND=0.0.0.0:9090
BLOCKYARD_DOCKER_IMAGE=ghcr.io/rocker-org/r-ver:4.4.0

Sections#

`[server]`#

Field	Default	Description
`bind`	`127.0.0.1:8080`	Address and port the server listens on
`shutdown_timeout`	`30s`	Time to drain in-flight requests on shutdown
`log_level`	`info`	Log verbosity: `trace`, `debug`, `info`, `warn`, `error`
`management_bind`	—	Separate listener for `/healthz`, `/readyz`, `/metrics`. See Observability.
`session_secret`	—	Secret for signing session cookies. Required when `[oidc]` is set without `[openbao]`; auto-generated and stored in vault when `[openbao]` is configured.
`external_url`	—	Public-facing URL of the server (used for OIDC redirect URIs)
`trusted_proxies`	—	CIDRs whose `X-Forwarded-For` to trust (e.g. `["10.0.0.0/8"]`)

`[docker]`#

Field	Default	Description
`socket`	`/var/run/docker.sock`	Path to the Docker (or Podman) socket
`image`	(required)	Base container image for workers and builds
`shiny_port`	`3838`	Port Shiny listens on inside the container
`pak_version`	`stable`	pak release channel (`stable`, `rc`, or `devel`)
`service_network`	—	Docker network whose containers are reachable from workers
`store_retention`	`0`	Package store eviction duration (`0` = disabled)
`default_memory_limit`	—	Fallback memory limit for workers (e.g. `"2g"`). Applies when no per-app limit is set.
`default_cpu_limit`	—	Fallback CPU limit for workers (e.g. `4.0`). Applies when no per-app limit is set.

`[storage]`#

Field	Default	Description
`bundle_server_path`	`/data/bundles`	Directory for uploaded bundles
`bundle_worker_path`	`/app`	Mount point inside worker containers
`bundle_retention`	`50`	Max bundles to keep per app before cleanup
`max_bundle_size`	`104857600`	Maximum upload size in bytes (default 100 MB)
`soft_delete_retention`	`0`	How long to keep soft-deleted apps (e.g. `720h` for 30 days). `0` means immediate hard delete.

`[database]`#

Field	Default	Description
`driver`	`sqlite`	Database driver: `sqlite` or `postgres`
`path`	`/data/db/blockyard.db`	Path to the SQLite database file (when `driver = "sqlite"`)
`url`	—	PostgreSQL connection string (when `driver = "postgres"`)

`[proxy]`#

Field	Default	Description
`ws_cache_ttl`	`60s`	How long to keep a backend WebSocket open after client disconnect. Enables transparent reconnection on network blips — see Reconnection on network interruptions.
`health_interval`	`15s`	Interval between worker health checks
`worker_start_timeout`	`60s`	Max time to wait for a worker to become healthy
`max_workers`	`100`	Maximum number of concurrent worker containers
`log_retention`	`1h`	How long to keep worker log entries before cleanup
`session_idle_ttl`	`0`	Idle timeout for sessions and WebSocket connections. When non-zero, idle WebSocket connections are closed and stale sessions are swept. `0` = disabled.
`idle_worker_timeout`	`5m`	Time before an idle worker container is stopped
`http_forward_timeout`	`5m`	Timeout for forwarding HTTP requests to workers
`max_cpu_limit`	`16.0`	Max CPU limit settable per app
`transfer_timeout`	`60s`	Timeout for bundle transfers to workers
`session_max_lifetime`	`0`	Hard cap on session duration. `0` (default) means unlimited — sessions only end via idle timeout or worker shutdown.

`[oidc]` (optional)#

Enable OIDC authentication. When configured, server.session_secret is required unless [openbao] is also configured (in which case it can be auto-generated).

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Server#

Prerequisites#

Docker (or Podman with a Docker-compatible socket)
A Linux host (Blockyard runs as a container or native binary)

Running with Docker (recommended)#

The easiest way to run Blockyard is as a Docker 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/rocker-org/r-ver:4.4.3 \
 ghcr.io/cynkra/blockyard:latest

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

REST API

Mon, 01 Jan 0001 00:00:00 +0000

All endpoints are under /api/v1/ and require authentication (except /healthz, /readyz, and /metrics).

Authenticate with a Personal Access Token (Authorization: Bearer by_...) or an OIDC session cookie (browser).

curl -H "Authorization: Bearer $TOKEN" ...

Health#

`GET /healthz`#

Returns 200 OK with body ok. No authentication required.

`GET /readyz`#

Readiness probe that checks backend dependencies (database, Docker socket, and optionally IdP and OpenBao). No authentication required, but the response detail varies based on the caller.

Authorization

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard separates authentication from authorization. Your identity provider (IdP) handles authentication — proving who you are via OIDC. Blockyard handles authorization — deciding what you can do. IdP groups play no role in blockyard’s permission model.

System Roles#

Every user has one system-wide role, assigned by a blockyard admin. New users get viewer by default when they first log in via OIDC.

Role	What you can do
admin	Full control: manage all apps, all users, all settings. Implicit owner access to everything.
publisher	Create and deploy apps. Full control over your own apps. No access to other publishers’ apps unless explicitly granted.
viewer	Access apps you’ve been granted access to, or apps with `logged_in`/`public` visibility. Cannot create or deploy apps.

First Admin Setup#

The first admin is configured via the initial_admin field in the [oidc] config section. Set this to the OIDC sub of the user who should become the first admin:

Configuration File

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard reads its configuration from a TOML file. The default path is blockyard.toml in the working directory. Override it with the --config CLI argument:

blockyard --config /etc/blockyard/config.toml

Environment variable overrides#

Every configuration field can be set via an environment variable. The naming convention is:

BLOCKYARD_<SECTION>_<FIELD>

All uppercased. For example, [server] bind becomes BLOCKYARD_SERVER_BIND.

Environment variables take precedence over values in the TOML file.

`[server]`#

[server]
bind = "127.0.0.1:8080"
shutdown_timeout = "30s"
# management_bind = "127.0.0.1:9100"
# log_level = "info"
# session_secret = "random-secret" # required when [oidc] is configured
# external_url = "https://blockyard.example.com"
# trusted_proxies = ["10.0.0.0/8"]

Field	Type	Default	Required	Description
`bind`	`string`	`127.0.0.1:8080`	No	Socket address to listen on
`management_bind`	`string`	—	No	Separate listener for `/healthz`, `/readyz`, `/metrics`. See Management listener.
`shutdown_timeout`	`duration`	`30s`	No	Grace period for draining requests on shutdown
`log_level`	`string`	`info`	No	Log verbosity. One of `trace`, `debug`, `info`, `warn` (or `warning`), `error`.
`session_secret`	`string`	—	When `[oidc]` is set without `[openbao]`	Secret for signing session cookies. Supports vault references. Auto-generated and stored in vault when `[openbao]` is configured.
`external_url`	`string`	—	No	Public-facing URL of the server (used for OIDC redirect URIs)
`trusted_proxies`	`string[]`	—	No	CIDRs whose `X-Forwarded-For` headers to trust (e.g. `["10.0.0.0/8"]`). Each entry must be a valid CIDR. Set via env as comma-separated: `BLOCKYARD_SERVER_TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12`.
`bootstrap_token`	`string`	—	No	One-time token that can be exchanged for a real PAT via `POST /api/v1/bootstrap`. Requires `oidc.initial_admin` to be set. Intended for dev/CI bootstrapping — do not use in production. See Bootstrap tokens.

API authentication uses Personal Access Tokens (for CLI/CI access) or OIDC session cookies (for browser access). The v0 static bearer token (server.token) has been removed.

Quick Start

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks through deploying a Shiny app using the by CLI. It assumes Blockyard is already running (see Installation).

1. Install the CLI#

Download the by binary for your platform from the releases page and place it on your PATH. See Installation for details.

2. Log in#

by login --server http://localhost:8080

This opens your browser to create a Personal Access Token, then asks you to paste it back into the terminal.

3. Create your app#

Your app directory should look something like:

Credential Management

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard integrates with OpenBao (a Vault-compatible secrets manager) to deliver per-user credentials to Shiny apps at runtime. This allows each user to register API keys for external services (AI providers, databases, object storage, etc.) that are securely injected into their sessions.

Prerequisites#

OIDC authentication must be configured (see Configuration)
An OpenBao (or HashiCorp Vault) instance, initialized and unsealed

How it works#

An operator configures OpenBao and defines which services users can enroll credentials for
Users store their API keys via the web UI or the REST API
When a user visits a Shiny app, Blockyard injects a scoped OpenBao token into the request so the app can read that user’s credentials

No single compromised component can exfiltrate all user credentials. The server’s OpenBao token is write-scoped — it cannot read user secrets. Only a valid IdP access token (from an active user session) can produce a read-scoped token.

Observability

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard provides four observability mechanisms: structured logging, Prometheus metrics, OpenTelemetry tracing, and an append-only audit log.

Logging#

Blockyard writes structured JSON logs to stderr. Control verbosity with the log_level setting:

[server]
log_level = "info" # trace, debug, info, warn, error

Or via environment variable:

BLOCKYARD_SERVER_LOG_LEVEL=debug

Log levels#

Level	Use case
`trace`	Fine-grained diagnostics (WebSocket frames, load-balancer decisions). Noisy.
`debug`	Subsystem internals (health checks, session lifecycle, container operations)
`info`	Normal operations (startup, requests, deploys). Default.
`warn`	Degraded conditions (failed health checks, capacity limits)
`error`	Failures requiring attention (container crashes, build failures)

HTTP request logging#

All HTTP requests are logged automatically:

Backend Security

Mon, 01 Jan 0001 00:00:00 +0000

Blockyard supports two worker backends: Docker (the default) and process (bubblewrap-based, single-host). Both run untrusted R code with PID, mount, user-namespace, and capability isolation. They differ on three axes — network isolation between workers, per-worker resource limits, and syscall filtering — and on how much privilege the server process itself needs. This page helps you decide which backend fits your deployment and, if you pick the process backend, how to close the gaps with operator-configured controls.

Blockyard

CLI Reference

Global flags#

Authentication#

by login#

Deploying an App

Bundle structure#

What is Blockyard?

How it works#

Configuration

Sections#

[server]#

[docker]#

[storage]#

[database]#

[proxy]#

[oidc] (optional)#

Installation

Server#

Prerequisites#

Running with Docker (recommended)#

REST API

Health#

GET /healthz#

GET /readyz#

Authorization

System Roles#

First Admin Setup#

Configuration File

Environment variable overrides#

[server]#

Quick Start

1. Install the CLI#

2. Log in#

3. Create your app#

Credential Management

Prerequisites#

How it works#

Observability

Logging#

Log levels#

HTTP request logging#

Backend Security

`by login`#

`[server]`#

`[docker]`#

`[storage]`#

`[database]`#

`[proxy]`#

`[oidc]` (optional)#

`GET /healthz`#

`GET /readyz`#

`[server]`#