docs: add BYOK reference guide - #6
Closed
SecurityQQ wants to merge 3 commits into
Closed
Conversation
Add a second rendering mode that requires only VARG_API_KEY and curl, targeting non-technical users who don't have bun/ffmpeg installed. Changes: - SKILL.md: restructure with three modes (cloud render, local render, single asset API), auto-detect environment, cloud-first documentation - scripts/setup.sh: new bash-only setup script that detects bun/ffmpeg and recommends the appropriate mode (keeps setup.ts for bun users) - references/gateway-api.md: add full Render API documentation (POST /api/render, job polling, SSE streaming, rate limits, TSX format) - references/templates.md: add cloud render curl examples at the top - Update frontmatter: add license, metadata, version 2.0.0
SKILL.md was 401 lines and loaded entirely on activation. Now it is 178 lines — a compact router that directs agents to the right reference file based on what they need. Extracted content into 3 new reference files: - cloud-render.md: cloud render TSX format, workflow, restrictions - local-render.md: local render setup, CLI commands, iteration workflow - recipes.md: character consistency, talking head, slideshow, audio patterns Also includes previous fixes: - setup.sh: ffprobe now influences mode detection (HAS_FFPROBE flag) - templates.md: jq dependency noted with grep-based fallback
Add comprehensive byok.md covering gateway API, cloud render, local render, and TypeScript client BYOK usage. Update SKILL.md references table and expand the BYOK section in gateway-api.md with examples and cross-reference.
📝 WalkthroughWalkthroughdocumentation overhaul introducing dual rendering modes (cloud vs local) across a skill guide. adds comprehensive reference docs for byok, cloud render, local render, recipes, and templates. introduces an automated setup script that detects environment capabilities and recommends the appropriate render mode. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Important Merge conflicts detected
✨ Finishing Touches
🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip CodeRabbit can generate a title for your PR based on the changes.Add |
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@varg-ai/references/gateway-api.md`:
- Around line 365-367: The example endpoint path is incorrect: replace the GET
/api/jobs reference with the render namespace used in this section (e.g., change
"/api/jobs" to "/api/render/jobs") so the documentation example matches the rest
of the /api/render/... endpoints; update the Authorization example line if
needed and scan the surrounding render-related examples (the GET snippet shown)
to ensure all usages use "/api/render/jobs" consistently.
- Around line 276-289: Add a new optional field named providerkeys to the render
request schema: update the JSON example to include "providerkeys": {} and add a
table row for `providerkeys` (type: `object` — map of provider name to key
string, Required: No) with description: "BYOK keys for cloud render; include
provider-specific key values when using bring-your-own-key (required when BYOK
is enabled)". Ensure the new field is shown alongside the existing `code`,
`verbose`, and `mode` entries so readers can discover and use BYOK for cloud
rendering.
In `@varg-ai/references/local-render.md`:
- Around line 121-124: The documented setup command is wrong: it references
"scripts/setup.ts" but the repository adds "scripts/setup.sh"; update the
example command that currently shows "bun scripts/setup.ts" to invoke the shell
script instead (e.g., use "bash scripts/setup.sh" or "./scripts/setup.sh"), and
ensure any surrounding text reflects using the .sh installer rather than a
TypeScript script so readers run the correct script.
In `@varg-ai/SKILL.md`:
- Around line 16-33: Update the Environment Detection documentation to include
ffprobe as a required local-mode prerequisite: modify the compatibility header
and the mode matrix in SKILL.md (the "Environment Detection" section and the
table rows) to list "bun + ffmpeg + ffprobe" for Local Render and ensure the
matrix logic and the note about running `bash scripts/setup.sh` reflect that
setup.sh checks for ffprobe as well.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 79efa314-0c4f-46ba-a49a-8beed75b5c10
📒 Files selected for processing (8)
varg-ai/SKILL.mdvarg-ai/references/byok.mdvarg-ai/references/cloud-render.mdvarg-ai/references/gateway-api.mdvarg-ai/references/local-render.mdvarg-ai/references/recipes.mdvarg-ai/references/templates.mdvarg-ai/scripts/setup.sh
Comment on lines
+276
to
+289
| ```json | ||
| { | ||
| "code": "<TSX code string with export default>", | ||
| "verbose": false, | ||
| "mode": "strict" | ||
| } | ||
| ``` | ||
|
|
||
| | Field | Type | Required | Description | | ||
| |-------|------|----------|-------------| | ||
| | `code` | `string` | Yes | TSX code with `export default`. No imports needed -- all components are globals. | | ||
| | `verbose` | `boolean` | No | Enable verbose logging (default: false) | | ||
| | `mode` | `"strict" \| "preview"` | No | `"preview"` uses cheaper placeholders | | ||
|
|
There was a problem hiding this comment.
document providerkeys in the render request schema.
right now the schema omits the field needed for byok in cloud render, so readers of this page won’t discover it.
suggested doc patch
{
"code": "<TSX code string with export default>",
"verbose": false,
- "mode": "strict"
+ "mode": "strict",
+ "providerKeys": {
+ "fal": "<optional>",
+ "elevenlabs": "<optional>",
+ "higgsfield": "<optional>",
+ "replicate": "<optional>",
+ "openai": "<optional>",
+ "google": "<optional>",
+ "together": "<optional>",
+ "groq": "<optional>"
+ }
} | Field | Type | Required | Description |
|-------|------|----------|-------------|
| `code` | `string` | Yes | TSX code with `export default`. No imports needed -- all components are globals. |
| `verbose` | `boolean` | No | Enable verbose logging (default: false) |
| `mode` | `"strict" \| "preview"` | No | `"preview"` uses cheaper placeholders |
+| `providerKeys` | `object` | No | optional BYOK keys per provider for this render request |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@varg-ai/references/gateway-api.md` around lines 276 - 289, Add a new optional
field named providerkeys to the render request schema: update the JSON example
to include "providerkeys": {} and add a table row for `providerkeys` (type:
`object` — map of provider name to key string, Required: No) with description:
"BYOK keys for cloud render; include provider-specific key values when using
bring-your-own-key (required when BYOK is enabled)". Ensure the new field is
shown alongside the existing `code`, `verbose`, and `mode` entries so readers
can discover and use BYOK for cloud rendering.
Comment on lines
+365
to
+367
| GET /api/jobs?limit=50 | ||
| Authorization: Bearer varg_xxx | ||
| ``` |
There was a problem hiding this comment.
fix the list-jobs endpoint path mismatch.
line [365] uses /api/jobs, but this render section consistently uses /api/render/.... this looks like a wrong path and can cause failed calls.
suggested doc patch
-GET /api/jobs?limit=50
+GET /api/render/jobs?limit=50📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| GET /api/jobs?limit=50 | |
| Authorization: Bearer varg_xxx | |
| ``` | |
| GET /api/render/jobs?limit=50 | |
| Authorization: Bearer varg_xxx |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@varg-ai/references/gateway-api.md` around lines 365 - 367, The example
endpoint path is incorrect: replace the GET /api/jobs reference with the render
namespace used in this section (e.g., change "/api/jobs" to "/api/render/jobs")
so the documentation example matches the rest of the /api/render/... endpoints;
update the Authorization example line if needed and scan the surrounding
render-related examples (the GET snippet shown) to ensure all usages use
"/api/render/jobs" consistently.
Comment on lines
+121
to
+124
| ```bash | ||
| # Run the setup script (from the skill directory) | ||
| bun scripts/setup.ts | ||
|
|
There was a problem hiding this comment.
setup command points to the wrong script.
line [123] references scripts/setup.ts, but this pr adds scripts/setup.sh. this will fail for users following setup steps.
suggested doc patch
-# Run the setup script (from the skill directory)
-bun scripts/setup.ts
+# Run the setup script (from the skill directory)
+bash scripts/setup.sh🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@varg-ai/references/local-render.md` around lines 121 - 124, The documented
setup command is wrong: it references "scripts/setup.ts" but the repository adds
"scripts/setup.sh"; update the example command that currently shows "bun
scripts/setup.ts" to invoke the shell script instead (e.g., use "bash
scripts/setup.sh" or "./scripts/setup.sh"), and ensure any surrounding text
reflects using the .sh installer rather than a TypeScript script so readers run
the correct script.
Comment on lines
+16
to
+33
| compatibility: >- | ||
| Requires VARG_API_KEY (get at https://varg.ai). | ||
| Cloud mode: curl only (zero dependencies). | ||
| Local mode: bun runtime + ffmpeg. | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
| ## Environment Detection | ||
|
|
||
| Before generating anything, verify the environment: | ||
| Before generating anything, determine the rendering mode. | ||
|
|
||
| 1. Run `bun scripts/setup.ts` (from the skill directory) to check API keys and connectivity | ||
| 2. Required: `VARG_API_KEY` (single gateway key) **or** `FAL_KEY` (direct fal.ai access) | ||
| 3. Optional: `ELEVENLABS_API_KEY` (speech/music), `REPLICATE_API_TOKEN`, `HIGGSFIELD_API_KEY` | ||
| 4. Quick smoke test: `bunx vargai hello` | ||
| Run `bash scripts/setup.sh` from the skill directory to auto-detect, or check manually: | ||
|
|
||
| If using the varg gateway (recommended), a single `VARG_API_KEY` covers all providers. | ||
| | bun | ffmpeg | Mode | | ||
| |-----|--------|------| | ||
| | No | No | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) | | ||
| | Yes | No | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) | | ||
| | Yes | Yes | **Local Render** (recommended) -- read [local-render.md](references/local-render.md) | | ||
|
|
There was a problem hiding this comment.
local-mode prerequisites are missing ffprobe.
this section says local mode is bun + ffmpeg only, but setup logic requires bun + ffmpeg + ffprobe. please align the compatibility text and matrix so mode selection guidance is accurate.
suggested doc patch
compatibility: >-
Requires VARG_API_KEY (get at https://varg.ai).
Cloud mode: curl only (zero dependencies).
- Local mode: bun runtime + ffmpeg.
+ Local mode: bun runtime + ffmpeg + ffprobe.-| bun | ffmpeg | Mode |
-|-----|--------|------|
-| No | No | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) |
-| Yes | No | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) |
-| Yes | Yes | **Local Render** (recommended) -- read [local-render.md](references/local-render.md) |
+| bun | ffmpeg | ffprobe | Mode |
+|-----|--------|---------|------|
+| No | No | No/Yes | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) |
+| Yes | No | No/Yes | **Cloud Render** -- read [cloud-render.md](references/cloud-render.md) |
+| Yes | Yes | No | **Cloud Render** -- install ffprobe |
+| Yes | Yes | Yes | **Local Render** (recommended) -- read [local-render.md](references/local-render.md) |🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@varg-ai/SKILL.md` around lines 16 - 33, Update the Environment Detection
documentation to include ffprobe as a required local-mode prerequisite: modify
the compatibility header and the mode matrix in SKILL.md (the "Environment
Detection" section and the table rows) to list "bun + ffmpeg + ffprobe" for
Local Render and ensure the matrix logic and the note about running `bash
scripts/setup.sh` reflect that setup.sh checks for ffprobe as well.
Contributor
Author
|
Replaced by PR from clean branch based on main |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
references/byok.mdcovering bring-your-own-key usage across all surfaces (gateway API, cloud render, local render, TypeScript client)gateway-api.mdwith a curl example, provider table, and cross-reference to the full guide