Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

Holocron Deploy

holocron deploy builds your docs site and uploads it to Holocron hosting. It is the fastest way to publish a site without managing your own server or Cloudflare Worker.
npx -y @holocron.so/cli deploy
The command runs your build, uploads only changed files, finalizes the deployment, and prints the live URL.

Deployment URLs

The URL format depends on how you deploy.
From GitHub Actions (OIDC): the subdomain is derived from your GitHub repo name and owner, verified from the OIDC token. Pushing to the default branch (usually main) deploys to:
https://<repo>-<owner>-site.holocron.so
For example, remorses/my-docs on main → https://my-docs-remorses-site.holocron.so.
Pushes to non-default branches or pull request events produce a unique preview URL that includes the branch name. The deploy command prints the URL after each deploy, and sets it as a GitHub Actions step output (holocron_url).
From local or API key: the subdomain uses the project ID instead of the GitHub repo name, since there is no verified GitHub context:
https://<projectId>-site.holocron.so
Custom domains are not supported yet. Use Cloudflare Workers or Node.js if you need your own domain today.

Authentication

Auth priority (first match wins):
  1. HOLOCRON_KEY env var — API key scoped to a specific project. The server resolves the org and project from the key. No flags needed.
  2. Session token from npx -y @holocron.so/cli login — if the account has multiple projects, pass --project prj_xxx or the CLI prompts interactively.
  3. GitHub Actions OIDC — automatic when running in GitHub Actions with permissions: id-token: write. No API key or login needed if the repo owner matches the Holocron account.
For local deploys, log in once:
npx -y @holocron.so/cli login
npx -y @holocron.so/cli deploy
For CI deploys, use a project API key:
HOLOCRON_KEY=holo_xxx npx -y @holocron.so/cli deploy
No project ID is saved locally on disk. It is either derived from the API key, passed via --project, or selected interactively at deploy time.

GitHub Actions OIDC (keyless deploys)

The deploy command does not need an API key when run inside GitHub Actions and the user signed in to holocron.so with the same GitHub account that owns the repo. Holocron verifies the GitHub OIDC token to authenticate. The workflow needs:
permissions:
  id-token: write
How branch detection works:
  • Pull requests: uses the head_ref OIDC claim (the PR source branch). Marked as preview automatically.
  • Pushes: uses the ref claim stripped to branch name (refs/heads/main → main). Compared against the project's default branch to decide production vs preview.
  • Explicit override: --branch <name> CLI flag.

Organizations and project resolution

Each user gets a personal org auto-created on first login. All projects and API keys are scoped to an org. Run npx -y @holocron.so/cli whoami to see all orgs and projects.
When a user belongs to multiple orgs, projects create prompts which org to use. Pass --org <orgId> to skip the prompt:
npx -y @holocron.so/cli projects create --name "My Docs" --org <orgId>
The deploy command resolves the org from the project itself, so --org is not needed for deploys.

GitHub Actions outputs

The deploy command sets GitHub Actions step outputs when GITHUB_OUTPUT is available:
holocron_url=https://...
holocron_deployment_id=dep_...

Build output

holocron deploy uses the special deploy build output at dist/.holocron/. The server bundle is uploaded as Worker files and the client bundle is uploaded as static assets.
See Build Output for the directory structure.
Powered byHolocron