Core workflow

Deploy a Web Yard

Publish durable static output to a stable public address from the CLI, CI, API, or MCP.

Before you start

Build a static directory with index.html at its root.
Select a workspace and project where you can create or deploy a Web Yard.

Create the first Web Yard

A Web Yard is a named public destination inside a project. Deploying publishes static files to its stable blobyard.app address. The stored deployment remains private Blob Yard data until you explicitly publish it.

first deployment syntax

blobyard --workspace <workspace-slug> --project <project-slug> deploy <local-directory> --yard <yard-name> --public

publish a marketing build

blobyard --workspace example-team --project web-products deploy ./dist --yard marketing --public

The result includes a stable URL for the Yard and an immutable deploymentUrl for the exact retained deployment. Rollback changes only the stable URL target. A pruned deployment URL returns 404.

Configure multiple destinations

.blobyard.toml

[yards.marketing]
directory = "apps/marketing/dist"
clean_urls = true

[yards.docs]
directory = "apps/docs/dist"
clean_urls = true

[yards.dashboard]
directory = "apps/dashboard/dist"
spa = true

deploy every configured Web Yard

blobyard deploy --all --public

Each named table is independent. A monorepo can publish marketing, documentation, a dashboard, and Storybook without forcing them into one build directory or one deployment history.

Choose routing behavior

Directory index serves a directory's index.html.
Clean URLs resolve /guide to /guide.html when that file exists.
SPA fallback serves the root index.html when no file route matches.
A root 404.html becomes the custom not-found response.
Static files support HEAD, ETag, conditional requests, and byte ranges.

Inspect history and roll back

inspect and manage a Web Yard

blobyard yard list
blobyard yard show marketing
blobyard yard history marketing
blobyard yard rollback marketing <deploy-id>
blobyard yard delete marketing

uploading means files are still transferring.
finalising means the manifest is complete and the public alias is being confirmed.
live is the deployment currently served at the stable URL.
superseded is an older deployment available for rollback.
failed records an actionable deployment error without exposing storage credentials.
pruned means the history entry no longer retains its files.

Blob Yard retains the current deployment plus the nine newest other deployments. A rollback changes the live deployment without changing the public host or any immutable deployment URL.

Deploy from automation and agents

GitHub Actions can exchange repository-scoped OIDC identity for a short machine session. API and MCP clients use the same scoped Web Yard contract. No permanent storage credential enters the runner, agent, or browser.

Understand limits and the public boundary

A Web Yard accepts at most 10,000 files in one deployment and requires root index.html.
Yard allowances are pooled across the billing account and depend on the active plan.
A plan downgrade keeps existing Web Yards serving but can block new deployments until usage is remediated.
Web Yard bytes count toward the same durable storage allowance as other Blob Yard data.
Public delivery has no bandwidth or download charge, subject to the published fair-use policy.

Recover from common failures

If root index.html is missing, rebuild the selected directory and deploy again.
If a newer deployment already started, an older upload cannot replace it. Inspect history and redeploy the intended build.
If the account is over its plan allowance or restricted, existing content keeps serving while new deployments remain blocked.
If --all reports a partial failure, retry the failed Yard by name rather than reversing successful deployments.
If a route serves the SPA shell unexpectedly, disable SPA mode and use directory indexes or clean URLs.

Reference and troubleshooting

Syntax and behavior

Reusable syntax

Web Yard deployment syntax

blobyard --workspace <workspace-slug> --project <project-slug> deploy <local-directory> --yard <yard-name> [--spa] [--clean-urls] --public

Concrete example

public marketing deployment

blobyard --workspace example-team --project web-products deploy ./dist --yard marketing --clean-urls --public

Values used

./dist: Local static output directory containing root index.html.
marketing: Stable Web Yard name inside the selected project.
--clean-urls: Allows /guide to resolve guide.html when that file exists.
--public: Explicitly confirms that the deployment may be served on blobyard.app.

Expected result

The command prints the stable public alias, immutable deployment URL, and deployment identifier after the new deployment becomes live.

If it fails

Add root index.html or choose the correct build directory when manifest validation fails.
Run blobyard yard history <yard-name> to inspect a failed or superseded deployment.
Retry only the affected Yard when a multi-Yard deployment reports mixed results.

Security and lifecycle

Web Yards are public. Storage credentials remain server-side, and user HTML is served only from the isolated blobyard.app origin.