docs: reposition README around orchestration for agentic workloads - #5793
NathanFlurry wants to merge 3 commits into
Conversation
Match the rivet.dev homepage: technical tagline, value-prop bullets, Actor types, agent use cases, Kubernetes comparison with current benchmarks, deploy options (self-host / Cloud / BYOC), homepage FAQ as collapsible sections, and terminology (control plane, worker, Actor). Fix stale links (/docs/self-hosting, /docs/deploy/*, rivet-dev/rivet) and the project table (website moved to its own repo; add Swift SDK, container runner). Co-authored-by: Nathaneil Flurry <nathan@rivet.gg>
|
🚅 Deployed to the rivet-pr-5793 environment in rivet-frontend
|
![the-company-company[bot]](https://avatars.githubusercontent.com/in/3874572?s=60&v=4){kind=small}
| <h3>Rivet Actors are the primitive for stateful workloads.</h3> | ||
| <p>Built for AI agents, collaborative apps, and durable execution.</p> | ||
| <h3>Fast, high-density, scalable orchestration for agentic workloads.</h3> | ||
| <p>Run agents, workflows, and sandboxes as durable Actors. 12 ms cold starts, 72 KB per Actor, billions on one control plane. Open source and self-hostable.</p> |
There was a problem hiding this comment.
🟠 Medium · Headline advertises an experimental cold-start path as generally available
The benchmark methodology later says the 12.3 ms result uses an experimental feature that is not enabled by default, while this headline—and the unqualified claims on lines 23 and 30—presents 12 ms as current standard behavior. Users evaluating the released product cannot obtain the advertised path by default. Qualify each prominent claim as experimental/p50, or defer the headline number until the feature is enabled by default.
| - **Start in milliseconds, not minutes**: A cold start includes scheduling the Actor, loading its state, and serving the first request. No image pull, no container boot. | ||
| - **Built for scale**: Actors are scheduled independently, so adding capacity means adding machines. The same control plane runs a thousand Actors or a billion. | ||
| - **Hibernates when idle, wakes on demand**: An idle Actor writes its state and unloads. The next request brings it back in 12 ms with nothing lost. | ||
| - **Durable state for every workload**: Every Actor gets a SQLite database and a POSIX filesystem, tiered to S3. Idle Actors cost nothing, so millions can sit parked with their state intact. |
There was a problem hiding this comment.
🟠 Medium · Hibernation is presented as zero cost across deployment modes
“Idle Actors cost nothing” is not true for the self-hosted deployment promoted by this README: durable state still consumes the configured persistence/storage services, and the control-plane infrastructure still has a baseline cost. The previous README explicitly scoped $0 to a serverless platform and noted that traditional deployments incur idle costs. Describe the actual invariant instead (for example, hibernated Actors consume no worker memory or per-Actor compute), or restore the deployment qualification.
| - **End-to-end type safety**: Actor definitions generate their own client types, so a signature change breaks the build rather than production. | ||
| - **React SDK**: First-party hooks that subscribe a component to an Actor's state and keep it live as the Actor updates. | ||
| - **OpenTelemetry & observability**: Traces, metrics, and structured logs emitted in OTel format, into the collector you already run. | ||
| - **Single Rust binary**: The control plane ships as one static binary with no external dependencies to stand up first. |
There was a problem hiding this comment.
🟠 Medium · The control plane still requires external infrastructure
The self-hosted control plane is not dependency-free: the repository’s Kubernetes manifests deploy PostgreSQL and NATS, and line 198 itself directs operators to use Postgres or FoundationDB plus S3. Calling the binary “no external dependencies to stand up first” gives operators the wrong deployment model. Keep the single-binary claim, but explicitly distinguish it from the required persistence and messaging services.
| **Tools**: [Vitest](https://www.rivet.dev/actors/docs/testing) • [OpenTelemetry](https://www.rivet.dev/actors/docs/general/tracing) • [Pino](https://www.rivet.dev/actors/docs/general/logging) • [AI SDK](./examples/ai-agent) • [OpenAPI](./rivetkit-openapi) • [AsyncAPI](./rivetkit-asyncapi) | ||
|
|
||
| ### Start From Scratch | ||
| [Request an integration →](https://github.com/rivet-dev/actors/issues/new) |
There was a problem hiding this comment.
🔵 Low · Repository links use the deprecated organization path
Repository convention requires public links to use github.com/rivet-dev/rivet, but this link and the Discussions/Issues links on lines 318–319 use github.com/rivet-dev/actors. They currently rely on GitHub redirects and can expose the old path in tooling or authentication return URLs. Point all three links directly at the canonical repository.
Code ReviewThis PR is a docs-only README rewrite. I checked the new/changed links against the actual doc source (docs/actors/sidebar.json, docs/general/sidebar.json, docs/integrations/sidebar.json) and against GitHub's API for the org/repo references. 1. /docs/deploy/... link tree does not exist (README.md:210, 178, 196, 225, 239)The new "Deploy workers on" line and the Local & Self-Host / BYOC cards link to /docs/deploy/self-host/workers/PLATFORM/ for all 8 platforms (Vercel, Railway, AWS ECS, AWS Lambda, GCP Cloud Run, Cloudflare, Kubernetes, Docker), plus /docs/deploy/byoc/ and /docs/deploy/self-host/control-plane/. Searching all three sidebar configs and the full docs/ tree for "deploy", "vercel", "railway", "lambda", "cloud-run", "kubernetes", "docker-compose", and "byoc" turns up exactly one hit -- an unrelated child page /docs/deploy/self-host/control-plane/rbac filed under Authentication -- and no "Deploy" or "Workers" section exists in any sidebar. These links will 404. 2. Tools links use a nonexistent /general/ path segment (README.md:216)
Both 404. The Pino link appears carried over unfixed from the pre-diff README; the new OpenTelemetry link was built on the same wrong pattern. 3. GitHub org path should be rivet-dev/rivet, not rivet-dev/actors (README.md:218, 322, 323)"Request an integration", "GitHub Discussions", and "GitHub Issues" all point to github.com/rivet-dev/actors/.... Per this repo's CLAUDE.md: "ALWAYS use github.com/rivet-dev/rivet - NEVER use rivet-dev/rivetkit or rivet-gg/*". rivet-dev/actors resolves via redirect to rivet-dev/rivet, confirming it's a stale alias rather than the canonical path. 4. Retired "Rivet Compute" term (README.md:232)docs/CLAUDE.md states: "Rivet Compute" is retired. Where prose must name the managed offering it is Rivet Cloud, and it links to https://dashboard.rivet.dev. Line 232 says "It can run your Actors for you on Rivet Compute (https://www.rivet.dev/docs/deploy/cloud/compute/)" -- wrong name, and that specific path also doesn't exist in the docs source (same pattern as #1). 5. Minor grammar (README.md:171)"Install Actors and run it locally while you build." -- plural "Actors" followed by singular "it" reads awkwardly; a reader may be unsure what "it" refers to (the rivetkit package, per the code block below). Summary: No functional/runtime code in this diff (README-only), so no security, performance, or test-coverage concerns apply. The main issue is a cluster of broken/incorrect doc links that should be fixed before merge -- items 1-3 are the most impactful since they affect prominent deploy/platform and community links. 🤖 Generated with Claude Code |
… line Amp-Thread-ID: https://ampcode.com/threads/T-f5f836c1-7c74-44e1-b756-b7a69f070fcc Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Nathaneil Flurry <nathan@rivet.gg>
Amp-Thread-ID: https://ampcode.com/threads/T-f5f836c1-7c74-44e1-b756-b7a69f070fcc Co-authored-by: Amp <amp@ampcode.com> Co-authored-by: Nathaneil Flurry <nathan@rivet.gg>
This branch had an error being deployed
2 participants
Updates the README to match the new rivet.dev homepage positioning.
<details>sections/docs/self-hosting,/docs/deploy/vercel,rivet-dev/rivetexample paths) and the project table (website is its own repo; added Swift SDK, container runner, docs, examples)The GitHub repo description still has the old tagline and should be updated to match.