# Redgold Documentation — full corpus > Documentation for Redgold, a platform for building typed pipeline applications with managed data, agents, models, and deployment Concatenated markdown of every public page. Source: https://docs.redgold.ai/ --- # Quickstart Source: https://docs.redgold.ai/intro/quickstart Use the hosted website, install the terminal client, call the API, or connect your existing agent to individual Redgold tools. These paths use the same account, with separate permissions for models, search, browsers, data and compute. Already using an agent? Start with [agent tools setup](/users/install/agent-tools) for the copyable setup prompt, hosted MCP and remote-build requirements. You can keep your current model provider and repository workflow. If you already have access, [download the terminal client](#2-install-the-terminal-client) or start with the [first project task](#finish-your-first-project-task). You can use the same project context to build, launch, and improve your work. A working application can grow into a product with users and permissions, payments, tested web releases, mobile-store preparation, and a plan to reach customers. You do not have to plan every stage before completing the first useful task. ## 1. Use the website Open [account access](https://redgold.ai/signup) to see whether self-serve signup is available. When open, follow the account-creation flow there. Otherwise, [request access](https://redgold.ai/request-access) and wait for an invitation. Existing account holders can sign in at [redgold.ai](https://redgold.ai). Requesting access does not immediately create an active workspace. After signing in, the website detects an incomplete workspace and opens the onboarding flow. You can use the managed Gitea service at [git.redgold.ai](https://git.redgold.ai) to host code, or connect GitHub and choose the repositories the `redgold-ai` GitHub App may access. Repository access stays limited to the repositories you select. On the welcome step, describe your first task and choose **Continue with this task** to open it as a draft you can review before sending. You can also continue through optional workspace setup and choose **Ask an agent to guide me** at the end. That conversation is prepared with a setup request so an agent can check code hosting, repository access, provider keys, and the first task. The walkthrough is also available later from **Setup → Ask an agent to guide setup**. Once setup is complete, give an AI coding agent a task. The agent runs on managed compute while the website keeps its conversation, tool calls, and session state available for later inspection. The website is the starting point for account settings, workspaces, conversations, and API keys. You can begin here without installing a local client. ### Finish your first project task Choose one result you can inspect: a working page, a repaired bug, a comparison of possible approaches, or a launch brief. For code changes, connect the repository the agent should use. Confirm the available model/provider and account usage limits in setup before starting a long run. For example, paste this into a conversation in the website or terminal and replace the bracketed text: ```text I'm working on [project and who it helps]. My next useful result is [one working feature, repair, research answer, or launch deliverable]. Use [repository, website, or source material] and keep the scope to [boundary]. The result is ready when [observable acceptance condition]. Inspect the available context and tools, then complete that deliverable. For code, follow the repository's instructions and run the relevant checks. Show the result, what you checked, and anything that still needs attention. Keep paid services and public posts in draft; I haven't authorized those. ``` For a concrete first change, ask for a project homepage that explains who it helps, shows one real example, and links to a working next step. Ask the agent to verify the page at desktop and mobile widths and check its links. Review the actual page and verification results before treating it as finished. Deployment depends on your connected environment and its release policy; a local change is not a published website. If setup blocks the task, use **Setup → Ask an agent to guide setup** and include the error text without credentials. ### Continue the same project through launch Once the first feature works, ask the agent for the next product step in the same project. A class-booking app, for example, can add customer and instructor permissions, implement Stripe payments, pass its tests and CI checks, and publish a web version before preparing Android and iOS distribution. The landing page, campaign material, and feedback-driven fixes then stay connected to what you actually shipped. [Build, launch, and grow one project](/cookbook/launch-and-grow) walks through that lifecycle and identifies the setup each stage needs. It covers current boundaries too: customer payments need their own integration, while the store settings currently prepare account connections and iOS signing rather than building and submitting customer releases. The optional USD 200 marketing budget helper is one small part of that broader workflow. ## 2. Install the terminal client The `redgold` terminal client connects to the same conversations and remote agent sessions as the website. First sign in and open [Settings → API Keys](https://redgold.ai/settings/api-keys). Create an `sk-rg-` key and copy its full value when it is shown. Export the key, run the installer, and add the installed binaries to your `PATH`: ```bash export REDGOLD_API_KEY=sk-rg-... curl -fsSL https://redgold.ai/install.sh | bash -s -- --without-engine --without-aws export PATH="$PATH:$HOME/.redgold/bin" ``` Launch the terminal interface: ```bash redgold ``` This installs `redgold`, the `rac` agent CLI and its `rci` CI companion, while omitting the optional local engine and AWS CLI. Search, browsing, memory and remote builds use their own configured services; fleet commands need managed fleet access. See [Install the terminal client and tools](/cookbook/install-client) for platform requirements and troubleshooting, and the [RAC command guide](/reference/rac) for current workflows. ## 3. Use the API Create an API key from [Settings → API Keys](https://redgold.ai/settings/api-keys) and export it as shown above. Send the key as a bearer token to list the models available to your account: ```bash curl https://api.redgold.ai/v1/models \ -H "Authorization: Bearer $REDGOLD_API_KEY" ``` The response is an OpenAI-style model list. Use one of its model identifiers with the [model API](/reference/llm-api), or follow the [first API call](/cookbook/first-api-call) and [Python client](/cookbook/model-api-python) examples. ### Use the API with coding agents This optional setup changes the client's model provider. To keep your current provider and add tools instead, use [agent tools setup](/users/install/agent-tools) or [hosted MCP](/reference/mcp). The same public API works as the model provider for Claude Code, Codex, Oh My Pi, and OpenCode. Choose a model from `/v1/models` that matches the client's wire format: Claude Code uses the Anthropic-compatible `/v1/messages` surface, while the examples for the other clients use the OpenAI-compatible `/v1/responses` or `/v1/chat/completions` surface. For Claude Code, point the Anthropic base URL at the Redgold host and use a Messages-compatible model identifier: ```bash ANTHROPIC_BASE_URL=https://api.redgold.ai \ ANTHROPIC_AUTH_TOKEN="$REDGOLD_API_KEY" \ ANTHROPIC_MODEL="model-id-from-v1-models" \ ANTHROPIC_SMALL_FAST_MODEL="model-id-from-v1-models" \ claude ``` For Codex, add a custom Responses provider to `$HOME/.codex/config.toml`: ```toml model = "redgold-flint" model_provider = "redgold" [model_providers.redgold] name = "Redgold" base_url = "https://api.redgold.ai/v1" env_key = "REDGOLD_API_KEY" wire_api = "responses" ``` Then run `codex` normally. Replace `redgold-flint` with another Responses-compatible identifier returned for your account when appropriate. For Oh My Pi, define the provider in `$HOME/.omp/agent/models.yml`: ```yaml providers: redgold: baseUrl: https://api.redgold.ai/v1 apiKey: REDGOLD_API_KEY api: openai-responses models: - id: redgold-flint name: Redgold Flint ``` Start `omp` and select `redgold/redgold-flint` from `/model`. For OpenCode, run `/connect`, choose **Other**, enter `redgold` as the provider ID, and paste the API key. Then add the provider to your project-level `opencode.json`: ```json { "$schema": "https://opencode.ai/config.json", "provider": { "redgold": { "npm": "@ai-sdk/openai-compatible", "name": "Redgold", "options": { "baseURL": "https://api.redgold.ai/v1" }, "models": { "redgold-flint": { "name": "Redgold Flint" } } } } } ``` Run `/models` in OpenCode and select the Redgold model. Clients built around the newer Responses API can use OpenCode's `@ai-sdk/openai` adapter instead. Optional session orchestration works behind the same coding-client connection. When it is enabled for your account, keep using the client normally: Redgold triages each request, gathers focused analysis in parallel, and supplies the combined context to the model producing the response. The client continues to receive its standard streamed response, so its commands, tool use, and project instructions work the same way. ## Continue Pipeline applications turn a description of what you need into a managed app. Coding agents prepare the application for your review, and Redgold operates its data, workflows, API, and deployment. Continue with [Pipeline Applications](/intro/pipeline-app-walkthrough) to see how a support request becomes a running application and what you control along the way. Use the [common task index](/intro/starting-points) to find another guide, or browse the [examples](/cookbook/overview) for step-by-step recipes. [How Redgold works](/intro/overview) explains how pipeline applications, data, coding agents, model access, and managed deployment fit together. --- # Pipeline Applications Source: https://docs.redgold.ai/intro/pipeline-app-walkthrough Redgold currently delivers pipeline applications as a managed preview. Redgold operates routing, execution, storage, and deployment. The application behavior remains visible in Git as a small set of customer-reviewed artifacts: - Rust serde types define request and stored-record shapes; - pipeline TOML declares routes, stages, datasets, and capabilities; - Rust transforms contain domain-specific behavior; - inline tests and example requests define the expected result; - a generated contract summary records the route, input, output, storage, and permission boundary. Application creation, dataset provisioning, and deployment are coordinated with Redgold during the preview. The walkthrough below shows the contract a customer reviews within that managed workflow. ## Example: support request triage Suppose an application accepts a support request, classifies it, and writes a typed queue record: ```text POST /api/app/support/submit -> authenticate the workspace -> decode SupportRequest -> run support-triage -> write SupportQueueRow -> return the accepted record ``` The checked-in Rust schema gives `SupportRequest` the fields `id`, `subject`, and `body`. `SupportQueueRow` adds `category` and `priority`. Released persisted types evolve additively so stored records remain readable. ## Pipeline TOML The manifest makes the application route and its authority visible during review: ```toml [pipelines/support-triage.toml] name = "support-triage" description = "Classify and store one support request for the authenticated workspace." family = "support" role = "route" maturity = "preview" [route] method = "POST" path = "/api/app/support/submit" protocol = "unary" requires_auth = true route_scope = "public" capabilities = ["data_engine"] [[route.stages]] kind = "function" qualified_name = "support-triage" ``` The reviewed manifest answers concrete questions: which HTTP path exists, whether it requires an identity, which transform runs, and which platform capabilities it may use. During managed publication Redgold validates the TOML, checks route and capability policy, pins the transform artifact, and provisions the application dataset. ## Rust transform The transform contains the domain decision. This excerpt shows the ordinary Rust portion; the transform crate's ABI adapter decodes and encodes canonical CBOR around it. ```rust [src/lib.rs] #[derive(Clone, serde::Serialize, serde::Deserialize)] struct SupportRequest { id: String, subject: String, body: String, } #[derive(Clone, serde::Serialize, serde::Deserialize)] struct SupportQueueRow { id: String, subject: String, body: String, category: String, priority: String, } fn triage(request: SupportRequest) -> SupportQueueRow { let urgent = request.subject.to_lowercase().contains("outage"); SupportQueueRow { id: request.id, subject: request.subject, body: request.body, category: if urgent { "incident" } else { "general" }.to_string(), priority: if urgent { "high" } else { "normal" }.to_string(), } } ``` The checked-in test calls this function with representative records and verifies the emitted row. The production adapter uses the same transform ABI exercised by the [batch transform guide](/develop/author-a-batch-transform). ## What the customer controls | Contract area | Customer-reviewed artifact | |---|---| | Data shape | Rust serde schema | | Route and execution graph | Pipeline TOML | | Domain behavior | Rust transform | | Expected behavior | Inline tests and fixture requests | | Change history | Git commits and pull requests | Redgold operates the edge, executor, data engine, storage tiers, deployment, and runtime monitoring. A coding agent can propose changes to the artifacts, while the customer reviews the same schema, manifest, transform, and tests that enter the managed release. ## Managed change lifecycle ```text Customer describes a behavior change -> an agent proposes schema, TOML, transform, and tests -> the customer reviews the Git change -> Redgold validates and deploys the approved contract -> the customer verifies one bounded request ``` Self-service publication, portable application catalogs, declarative client surfaces, sharing, and offline installation are later expansions of this contract. Their component-preview details live in the [Pipeline Apps overview](/develop/pipeline-apps/overview). Continue with the [pipeline manifest preview](/reference/pipeline-preview) for the reviewed TOML subset or [author a batch transform](/develop/author-a-batch-transform) for the current Rust execution boundary. The [model API](/reference/llm-api) and [coding agents](/applications/ai-agents/overview) remain independently usable supporting capabilities. ## Keep evolving the application Follow [an application workstream](/fleet/application-workstream) to extend this support app with duplicate-request handling, organize the issues, resolve a blocked decision and verify managed delivery. [A request through the platform](/infrastructure/request-path) explains the runtime behind the example. --- # How Redgold works Source: https://docs.redgold.ai/intro/overview Redgold is a platform for building and maintaining applications with AI coding agents. You can give an agent work in an existing repository, connect a compatible coding tool to the model API, or build an application on managed data and infrastructure. You can also add individual tools to an agent you already use: search, browsers, memory, managed compute or remote builds and testing. For managed applications, Redgold turns a checked-in application contract into a managed service. The contract remains visible and reviewable in Git while Redgold operates its routing, execution, data, storage, deployment, and monitoring. Coding agents can propose changes to the same artifacts that a developer edits directly. ## Choose a starting point | What you need | Start here | What to expect | |---|---|---| | Add infrastructure to an existing agent | [Agent tools setup](/users/install/agent-tools) | Prompt, MCP or CLI setup; keep your provider and check access per service | | Repair or extend an existing application | [Coding agents](/applications/ai-agents/overview) | Repository work with inspectable changes and checks; access depends on your account | | Use the model API in an existing client | [Model API quickstart](/intro/quickstart#use-the-api-with-coding-agents) | An API key and a model compatible with your client's request format | | Build an application with managed data and deployment | [Pipeline application walkthrough](/intro/pipeline-app-walkthrough) | Coordinated setup during managed preview | | Understand a completed website repair | [Public website case study](/applications/case-studies/public-website-seo) | First-party technical results and repeatable public checks | ## The application contract On this platform a pipeline application consists of: - a typed schema defining its records, - a pipeline manifest declaring its API routes and transforms, - transform code run by a managed executor, - datasets stored, materialized, and queried by the platform data engine, - a Git-backed build and deployment. This shape gives developers, reviewers, and coding agents the same bounded set of artifacts to inspect. Schemas are validated, routes resolve from the manifest, transforms run with defined capabilities, and changes move through Git review before managed deployment. The [pipeline application walkthrough](/intro/pipeline-app-walkthrough) follows that lifecycle end to end. ## Managed runtime An incoming API request resolves to a declared pipeline route. The executor runs the selected transform, and the data engine reads or writes the owner-scoped records defined by the schema. Managed builds produce the service images and GitOps state used for deployment. The contract in Git remains the review boundary across those runtime components. ## Data and materialized views Writes converge on an append-only record log, and readable datasets are derived from it. The same records can be materialized in several shapes for different queries. Scheduled or change-driven transforms can prepare aggregations before a read reaches them. Records retain source and ingestion metadata, while transform cursors make derived datasets recomputable. Storage placement follows the access pattern, including columnar history and Postgres-backed interactive reads under the same dataset model. ## Coding agents and model access Coding agents run in persistent, isolated repository workspaces. Their conversations, tool activity, diffs, and session state remain inspectable, and their changes use the repository's normal test and review process. Agents can author pipeline applications or work in repositories deployed elsewhere. The same account can call hosted models directly. OpenAI- and Anthropic-compatible clients connect to `https://api.redgold.ai/v1`, use an `sk-rg-` API key, and select from the models returned by `/v1/models`. Model routing, metering, and provider availability sit behind those compatible request shapes. ## Current product boundary Managed pipeline application creation, dataset provisioning, and deployment are coordinated during the preview. Coding-agent access, the model API and individual agent tools can also be used independently. Search, browser, memory and builder permissions are separate; installing RAC does not enable every service. The [comparison section](/intro/comparison/positioning) places these components against backend platforms, query engines, PaaS products, coding tools, and model providers. ## Continue Use the [quickstart](/intro/quickstart) for initial setup or the [common task index](/intro/starting-points) to find a specific guide. The developer [Pipeline Apps section](/develop/pipeline-apps/overview) covers the runtime and release model in greater depth. --- # Positioning Source: https://docs.redgold.ai/intro/comparison/positioning Redgold covers three things that normally come from three separate products: infrastructure to deploy and run on, AI coding agents, and custom data pipelines. The recommended option is a Redgold-managed cluster, provisioned and operated by us. You can also deploy Redgold to your own cluster when you need to own the infrastructure. The comparisons below show which part of that surface each category covers and where Redgold extends beyond it. The Redgold application shape comes from a small spec — a checked-in Rust serde schema encoded with CBOR, a pipeline manifest, an edge route, executor-run transform code, engine storage, and a GitOps deploy — running either on our managed cluster or on a cluster you deploy and operate yourself. In both models, an agent fleet operates the applications and platform. The comparison criteria are the deploy unit, execution model, data ownership, agent integration, and current product maturity. ## vs managed app and cloud platforms Heroku, Vercel, Railway, and Fly give you a clean path from a git push to a running app. They handle build, deploy, and scaling so you do not operate the infrastructure yourself. Raw AWS or GCP with Kubernetes gives you full control and every primitive you could want, at the cost of assembling and running it all. Redgold puts managed deploys (ArgoCD and CI, container registries, multi-tenant and GPU provisioning) in the same place as the AI coding agents and the data layer. A PaaS primarily owns the path from application source to a hosted process. Redgold also owns the schemas, dataflows, datasets, model routing, and agent workspaces that produce and operate the application. ## vs AI coding tools Cursor, Devin, Claude Code, and self-hosted agent runners focus on the editing-and-iteration loop. They generally leave the infrastructure the agents run on and the data the agents draw from to the user — you bring your own cloud, deploy pipeline, and data plumbing around them. Redgold runs AI coding agents (internal Claude-style agents and external AI agents) directly in isolated Kubernetes pods on the platform, with resumable sessions and queryable conversation, tool-call, and agent-state history. Model routing handles provider selection and rate limits. The Redgold scope begins where a model response or an editing session ends: persistent workspaces, fleet control, data access, review automation, and deployment live in the same system. ## The all-in-one case Redgold makes the three layers one platform. Whether you use the recommended Redgold-managed cluster or deploy to your own, the agents run on the same compute that deploys your apps, and both are fed by the same custom data pipelines. Piecing the equivalent together yourself means a PaaS, plus a separate AI coding tool, plus your own data and cloud infrastructure, plus the integration work to make them cooperate. Redgold's product boundary is the integrated system: agents, applications, data pipelines, and deployments share one schema and operational path. | Capability | Redgold | Managed PaaS | AI coding tool | Raw AWS + k8s | |---|---|---|---|---| | App deploy automation | yes | yes | no | build it yourself | | AI coding agents in managed pods | yes | no | editing loop only | build it yourself | | Built-in model API and routing | yes | no | provider-specific | build it yourself | | Custom data pipelines / data lake | yes | no | no | build it yourself | ## Category comparisons The sections above frame Redgold against whole-platform substitutes. The pages below give a criteria table for narrower product categories: - [vs a backend-as-a-service (Supabase, Firebase)](/intro/comparison/vs-baas) — hosted CRUD, auth, storage, and client SDKs compared with pipeline applications. - [vs serverless compute (Modal and similar)](/intro/comparison/vs-serverless-compute) — uploaded functions compared with dataflow execution over platform datasets. - [vs a do-it-yourself data stack (Kubernetes + Postgres + DuckDB + glue)](/intro/comparison/vs-diy-data-stack) — separately assembled components compared with one integrated application shape. - [vs Rama](/intro/comparison/vs-rama) — a general JVM backend programming model compared with an agent-authored declarative platform. - [vs Apache Spark](/intro/comparison/vs-spark) — a distributed analytics engine compared with a complete application runtime. - [vs Apache DataFusion](/intro/comparison/vs-datafusion) — an embeddable query engine compared with an operated data and application platform. - [vs Heroku](/intro/comparison/vs-heroku) — a hosted application runtime compared with a Kubernetes, data, and agent platform. - [vs Lovable](/intro/comparison/vs-lovable) — an AI app builder compared with a data, deployment, and agent platform. - [vs AI model providers](/intro/comparison/vs-ai-providers) — model APIs compared with provider routing plus managed coding-agent operations. - [vs Cloudflare OS](/intro/comparison/vs-cloudflare-os) — an agent workspace with per-app isolate sandboxes compared with a data platform whose agents operate the cluster. --- # vs Lovable Source: https://docs.redgold.ai/intro/comparison/vs-lovable Lovable is an AI app builder. A natural-language prompt produces a full-stack web application — a React frontend with a generated backend, typically wired to Supabase for the database and auth — which the platform hosts and republishes on each iteration. The product is organized around prompt-to-running-website, with GitHub sync for taking the generated code elsewhere. Redgold is a data engine plus a Kubernetes-integrated runtime where an application is a checked-in Rust serde schema encoded with CBOR, a pipeline manifest, an edge route, and executor-run transform code over engine storage, deployed through GitOps onto a cluster. AI coding agents author and operate that application from inside the platform, while the product boundary remains the running pipeline application. ## Criteria | Criterion | Redgold | Lovable | |---|---|---| | Product unit | A pipeline application plus its schemas, datasets, agents, and routes | A generated web application hosted as a published site | | What the AI does | Persistent coding-agent workspaces in isolated pods that author, review, and operate applications against the platform ([AI agents](/applications/ai-agents/overview)) | A generation and editing loop that produces and revises application source code | | Backend and data | Integrated Lance/Parquet cold tier and Postgres hot tier with Rust serde and CBOR pipeline records ([data and pipelines](/infrastructure/data)) | Generated backend code, typically against an attached Supabase project | | Deploy target | Your own Kubernetes cluster via CI builds and ArgoCD reconciliation ([managed deployment](/infrastructure/deployment)) | Lovable-managed hosting; export to GitHub to host elsewhere | | Code and schema ownership | The checked-in Rust serde schema and CBOR contract are the ground truth; data, routes, and transforms derive from them | The generated repository is the artifact; schema lives in the attached backend | | Compute beyond the web app | Dataflow executor, compute-on-write transforms, model serving, and agent pods | Outside the generated application; external services are integrated by prompting | | Agent operations | Fleet control, resumable sessions, review automation, and queryable agent history in the same system | Iteration is per-app, through the builder chat | | Maturity | Early, single-operator; managed onboarding while self-service is consolidated | Established hosted product with a large user base | ## Category boundary An AI app builder centers on turning prompts into a hosted web application quickly, and it owns the generation loop and the hosting. Redgold owns the layers underneath and around that loop: the typed data model, the pipeline runtime, the deployment path onto your own cluster, and the agent fleet that operates them. A generated Lovable app corresponds to a single route-and-frontend slice of a Redgold application, with the schemas, datasets, transforms, model access, and agent operations coming from outside the builder. ## When Redgold fits Redgold fits when the application is data-and-pipeline shaped — records arrive from ingestion or agents, transforms run over them, and the result is queried and deployed on infrastructure you control — and when persistent coding agents operating that same platform are part of the point. If the goal is a prompted, hosted web app with a managed backend and minimal operational surface, an AI app builder is the more direct tool. If you would otherwise combine an AI builder with your own cluster, data platform, and agent runtime, the integrated shape is the trade Redgold is offering. --- # vs Cloudflare OS Source: https://docs.redgold.ai/intro/comparison/vs-cloudflare-os Cloudflare OS is an open-source platform that gives every employee an agent workspace with an isolated code-execution runtime, a governance framework for internal data access, and a platform for personal, modifiable apps. Each app is a "file" that can be a full full-stack application — client code, server code, an API, and durable state — where the server runs as a Dynamic Worker (a V8 isolate created at runtime) instantiated as a Durable Object Facet with its own SQLite database. Agents and apps start with zero access; capabilities are granted per resource as typed bindings, credential-holding gatekeeper Workers enforce policy, and the platform tracks every resource an agent has observed. It deploys into your own Cloudflare account and runs on Cloudflare's edge. Redgold shares the goal: agents that author and modify applications inside a platform whose security model makes that safe. The substrate differs. A Redgold application is a checked-in Rust serde schema encoded with CBOR, a pipeline manifest, an edge route, and executor-run transform code over engine storage, deployed through GitOps onto your own Kubernetes cluster. The agents are persistent coding-agent workspaces in isolated pods operating the same platform, and the data layer is a content-addressed Lance/Parquet and Postgres engine rather than per-app SQLite. ## Criteria | Criterion | Redgold | Cloudflare OS | |---|---|---| | Product unit | A pipeline application: schemas, dataflows, routes, transforms, datasets, and a signed release installed per workspace ([pipeline apps](/develop/pipeline-apps/overview)) | A personal app "file": client + server + API + durable state, one Dynamic Worker instance per app | | Instance model | One installation pins one immutable release per workspace; state lives in owner-scoped engine datasets, shared by grant | One isolate per app instance with its own SQLite (Durable Object Facet); sharing the app shares state, sharing a blueprint copies code with fresh state | | Untrusted code isolation | Tiered: built-in operators and trusted native (cdylib) transforms in process, capability-limited WASM UDFs in the Wasmtime sandbox, and untrusted native/Python UDFs fail closed into Firecracker microVMs ([infrastructure overview](/infrastructure/overview)) | V8 isolates (Dynamic Workers) with outbound networking disabled, millisecond cold starts, defense-in-depth below V8 | | Capability model | Release-pinned capability consent per installation, dataset grants for shared records, runtime write enforcement against the signed release | Zero default access; typed capability bindings in `env`, gatekeeper Workers holding credentials, observation tracking gating shares and writes | | Agent-modifiable apps | Agents author the bounded artifact set (schema, pipeline, surface, UDF, release); validators reject unknown operations and undeclared capabilities before publication | The workspace agent edits the app's own code directly; every user runs their own copy, so modification needs no upstream fork | | Data model | Content-addressed Rust serde rows encoded with CBOR over a Lance/Parquet cold tier and a Postgres hot tier, owner-scoped reads ([data and pipelines](/infrastructure/data)) | Per-app SQLite in the facet; company data reached through gatekeepers and MCP portals | | Deploy target | Your own Kubernetes cluster via CI builds and ArgoCD reconciliation ([managed deployment](/infrastructure/deployment)) | Your own Cloudflare account, on Cloudflare's edge runtime | | Model access | Model API with routing and rate limits next to the agent fleet ([LLM API](/reference/llm-api)) | Any model through Cloudflare AI Gateway with per-person/team attribution and budgets | | Maturity | Early, single-operator; app contracts and installation runtime are developer preview ([pipeline apps](/develop/pipeline-apps/overview)) | Newly open-sourced after internal use; managed dashboard product on the roadmap | ## Category boundary Cloudflare OS centers on the end-user workspace: conversation-first, with documents, workflows, and personal apps materializing out of it, each app a cheap disposable isolate the user's agent can rewrite freely. Its data story is per-app state plus governed reach into existing company systems through gatekeepers. Redgold centers on the data platform underneath that loop: typed records as the ground truth, pipelines and transforms over shared engine datasets, signed releases installed into workspaces, and a coding-agent fleet that operates the cluster itself — build, deploy, review, and ingestion included. Cloudflare OS apps live on state the app owns; Redgold applications live on datasets the platform owns and grants. The security models rhyme — both make agent-authored code safe by construction, with capability grants instead of ambient authority — but enforce at different layers. Cloudflare OS isolates each app instance in its own sandbox and controls who can reach the instance. Redgold pins what an installed release may do (signed artifacts, capability consent, runtime write enforcement) and scopes what any caller may read at the engine (owner-scoped datasets, explicit grants), with the sandbox tier reserved for untrusted transform code. ## When Redgold fits Redgold fits when the applications are data-and-pipeline shaped — ingestion, transforms, and queryable datasets on infrastructure you control — and when the agents should operate that infrastructure, from CI to deploy to the data layer, rather than live inside a workspace product. If the goal is giving every employee a safe personal-app workspace over existing SaaS systems on managed edge compute, Cloudflare OS is the more direct tool. If the per-instance sandbox model appeals but the workload is heavy data processing on your own cluster with typed schemas and GitOps, the Redgold shape is the trade being offered. --- # vs a backend-as-a-service Source: https://docs.redgold.ai/intro/comparison/vs-baas A backend-as-a-service gives an application developer a hosted database, authentication, file storage, and a generated data API. Supabase puts a managed Postgres behind auto-generated REST and GraphQL, row-level security, realtime subscriptions, and client SDKs for web and mobile. Firebase provides similar application primitives around a document store with offline sync. The category is organized around web and mobile application setup rather than dataflow execution. Redgold solves a different starting problem. It is a data engine plus a Kubernetes-integrated runtime where an application is a checked-in Rust serde schema encoded with CBOR, a pipeline manifest, an edge route, and executor-run transform code over engine storage. The data layer is analytics-shaped — a columnar cold tier alongside a hot Postgres tier under one addressing model — rather than a single row-store fronted by a CRUD API. ## Criteria | Criterion | Redgold | Supabase / Firebase-class BaaS | |---|---|---| | Data model | Content-addressed Rust serde rows encoded with CBOR across a Lance/Parquet cold tier and a Postgres hot tier ([data and pipelines](/infrastructure/data)) | Managed Postgres (Supabase) or a hosted document store (Firebase), exposed directly to clients | | Deploy target | Your own Kubernetes cluster via a Git-backed build and ArgoCD ([managed deployment](/infrastructure/deployment)) | The vendor's cloud; no cluster to run | | Extensibility | Review a Rust serde schema, pipeline TOML, transform code, and tests in Git; Redgold provisions and operates the managed application ([managed application artifacts](/develop/scaffold-a-narrow-app)) | Edge/serverless functions, database triggers, SQL views | | Self-host story | Managed during onboarding today; a single-machine Docker Compose evaluation sandbox exists for local trials, and broader self-service self-hosting is planned | Supabase is self-hostable via its own Docker stack; Firebase is hosted-only | | Auth and client SDKs | No hosted auth product or first-class mobile/web client SDKs at this layer (planned) | Built-in auth, generated client SDKs, realtime subscriptions | | AI / agent integration | Coding-agent fleet in isolated pods plus model API routing, alongside the same data layer ([AI agents](/applications/ai-agents/overview), [LLM API](/reference/llm-api)) | None built in; you integrate a model provider yourself | | Maturity | Early, single-operator; the generic external data-authoring surface is still being consolidated ([data availability](/infrastructure/data#public-availability)) | Mature, widely deployed, large ecosystem and community | ## Category boundary A BaaS centers on web and mobile application primitives: auth, a database, storage, realtime updates, and client SDKs. Redgold does not currently provide equivalent sign-in flows, generated client libraries, or offline sync. Its scope starts with typed pipeline applications, managed data processing, agent workspaces, and deployment on a cluster. ## When Redgold fits Redgold fits when the application is data-and-pipeline shaped rather than CRUD-shaped: records arrive from ingestion or agents, transforms run over them with content-addressed caching, and you query the result. It fits when you want that to run on your own Kubernetes with GitOps deployment, and when a fleet of coding agents operating the same platform is part of the point. If you would otherwise combine a BaaS with a separate analytics warehouse and a separate agent runtime, the integrated shape is the trade Redgold is offering, against the maturity and polish you give up. --- # vs serverless compute Source: https://docs.redgold.ai/intro/comparison/vs-serverless-compute Serverless-compute platforms turn a function into vendor-managed cloud capacity. Modal packages Python functions and runs them on autoscaling CPU or GPU workers with usage-based billing; similar platforms cover batch jobs, inference, and scheduled tasks. The product unit is an arbitrary function with declared compute requirements. Redgold runs transform code too, but through a different model. The executor resolves a route to a dataflow, and transform stages run over engine storage with content-addressed result caching and signed input/output traces. It is built for computation that reads and writes the platform's datasets, not for hosting general-purpose functions with autoscaling and metered billing. ## Criteria | Criterion | Redgold | Modal-class serverless compute | |---|---|---| | Data model | Content-addressed Rust serde rows encoded with CBOR over a Lance/Parquet cold tier and a Postgres hot tier ([data and pipelines](/infrastructure/data)) | Stateless by default; you bring your own database or object store | | Deploy target | Your own Kubernetes cluster via a Git-backed build and ArgoCD ([managed deployment](/infrastructure/deployment)) | The vendor's cloud; functions scale up and down with no cluster to operate | | Execution model | Transform stages in a dataflow plan with caching and verifiable traces ([build a vertical](/develop/build-a-vertical)); executor tiers are in-process built-ins, trusted native (cdylib) transforms, capability-limited Wasmtime UDFs, and untrusted native/Python UDFs in a Firecracker microVM sandbox. GPU UDF execution is absent; the separate request-handler WASM host is a component preview | Arbitrary functions (Python-first) with autoscaling and per-second billing | | GPU story | Model serving runs on GPUs through the AI serving lane (spot GPUs, vLLM) ([AI and agents](/infrastructure/ai)); the dataflow executor has no wired GPU tier | On-demand GPUs attached per function, scaled and billed by the second | | Self-host story | Managed during onboarding today; a single-machine Docker Compose evaluation sandbox exists for local trials, with broader self-service self-hosting planned | Hosted-only | | AI / agent integration | Coding-agent fleet in isolated pods plus model API routing, next to the same data layer ([AI agents](/applications/ai-agents/overview), [LLM API](/reference/llm-api)) | General compute; agent orchestration is left to you | | Maturity | Early, single-operator; the generic external execution surface is still being consolidated ([data availability](/infrastructure/data#public-availability)) | Mature, widely used for ML and batch workloads | ## Category boundary Serverless compute centers on arbitrary functions running on vendor-managed workers, commonly with autoscaling and metered CPU or GPU capacity. Redgold's dataflow executor is oriented around transforms over its own engine. Its Wasmtime UDF backend is implemented and default-on, with the first route staged for publication; GPU UDF execution is absent. The feature-gated request-handler WASM host is not selected by production routing. Compute that never reads or writes platform datasets sits outside the main Redgold application shape. ## When Redgold fits Redgold fits when the compute is part of a data pipeline: transforms over datasets where caching, content-addressed reuse, and signed traces matter, running on your own cluster next to the storage and the agents. The unit is a declared application and its data, deployed through GitOps, with model serving and a coding-agent fleet on the same platform. --- # vs a do-it-yourself data stack Source: https://docs.redgold.ai/intro/comparison/vs-diy-data-stack The do-it-yourself path assembles the same pieces from separately selected parts: Kubernetes for orchestration, Postgres for the hot store, DuckDB or another columnar engine for analytics, an object store for bulk data, a workflow tool for transforms, and glue code to connect them. The operator owns every component choice, boundary, upgrade, and integration. Redgold is an opinionated version of that same stack with the integration already built. An application is a checked-in Rust serde schema encoded with CBOR, a pipeline manifest, an edge route, and transform code over a data engine that already combines a Lance/Parquet cold tier with a Postgres hot tier under one content-addressed addressing model, deployed through GitOps by default. You adopt one shape instead of wiring the seams yourself. ## Criteria | Criterion | Redgold | DIY stack (k8s + Postgres + DuckDB + glue) | |---|---|---| | Data model | Content-addressed Rust serde rows encoded with CBOR across a Lance/Parquet cold tier and a Postgres hot tier under one addressing model ([data and pipelines](/infrastructure/data)) | Whatever you pick per layer; you own the schema translation and the cold/hot split | | Deploy target | Your own Kubernetes cluster via a Git-backed build and ArgoCD, pre-wired ([managed deployment](/infrastructure/deployment)) | Your own Kubernetes, assembled from your own manifests and pipelines | | Extensibility | Review a Rust serde schema, pipeline TOML, transform code, and tests in Git; Redgold provisions and operates the managed application ([managed application artifacts](/develop/scaffold-a-narrow-app), [build a vertical](/develop/build-a-vertical)) | Unlimited, at the cost of writing and maintaining the glue between components | | Self-host story | Managed during onboarding today; a single-machine Docker Compose evaluation sandbox exists for local trials, with broader self-service self-hosting planned | Fully self-hosted by definition; you run and upgrade every piece | | AI / agent integration | Coding-agent fleet in isolated pods plus model API routing on the same platform ([AI agents](/applications/ai-agents/overview), [LLM API](/reference/llm-api)) | Integrate an agent runtime and model routing yourself | | Maturity | Early, single-operator; the generic external authoring surface is still being consolidated ([data availability](/infrastructure/data#public-availability)) | Each component is mature; the integration is only as mature as your glue | ## Category boundary A self-assembled stack leaves every component and service boundary open. It can include a managed warehouse, a dedicated workflow engine, direct DuckDB queries, or a database-specific ecosystem. Redgold deliberately constrains those choices to one application shape and one integration path maintained by a single operator. ## When Redgold fits Redgold fits when the schema-to-storage translation, cold/hot split, route and executor wiring, and GitOps deploy should operate as one system, with a coding-agent fleet included. Its value comes from turning a small spec into a deployed application through a fixed, inspectable path. --- # vs Rama Source: https://docs.redgold.ai/intro/comparison/vs-rama Rama is a JVM backend platform built around depots, topologies, and PStates. Facts enter an append-only depot, topology code processes them in streaming or microbatch mode, and results land in durable partitioned views shaped for reads. A module is its deploy unit. Redgold makes the same core bet — one write path, derived views materialized on write, one system covering storage, transforms, and background work — and reaches it from a different direction. The spec is declarative and typed: a checked-in Rust serde schema encoded with CBOR, a pipeline manifest that declares routes and the transforms behind them, transform code an executor runs in a sandbox, and datasets in a data engine that splits a columnar cold tier from a Postgres hot tier. It runs on your own Kubernetes cluster through a Git-backed ArgoCD deploy, and the layer that writes and operates it is a fleet of AI coding agents with model routing underneath them. The short version of the difference: Rama is a programming model you write in Java or Clojure, engineered for scale and general expressiveness. Redgold is a declarative shape narrow enough that an agent can fill it in and CI can check the result, with the agent runtime, the model API, and the cluster deploy in the same platform. ## Shared vocabulary | Concept | Rama | Redgold | |---|---|---| | Source of truth | Depot — an append-only distributed log of facts | An append-only record log behind a single submission path, with content-addressed records carrying source and ingestion time | | Derived state | PStates — durable views composed from maps, sets, and lists, one per access pattern | Datasets materialized by transforms, several shapes over the same records ([data and pipelines](/infrastructure/data)) | | Compute | ETL topologies in streaming or microbatch mode, colocated with storage | Executor-run transforms at request time, plus compute-on-write aggregations driven by a schedule or a change notification | | Serving | Client API against PStates via paths, plus a REST layer for non-JVM callers | Declared HTTP and WebSocket routes resolved at a stateless edge and dispatched to the executor | | Deploy unit | A module, launched and scaled with `rama deploy` / `rama scaleExecutors` | A Git-backed build to container images, Kubernetes, and ArgoCD ([managed deployment](/infrastructure/deployment)) | | Authoring | A Java/Clojure library, dataflow API intermixed with ordinary code | A Rust serde schema, CBOR record contract, and pipeline manifest plus sandboxed transform code, written by agents or by hand ([scaffold a narrow app](/develop/scaffold-a-narrow-app)) | ## Criteria | Criterion | Redgold | Rama | |---|---|---| | Programming model | Declarative spec plus transform code in a sandboxed executor; the artifact set is fixed so it can be validated | A general-purpose JVM library with a dataflow API and arbitrary code organization | | Transactional semantics | Single write path with content-addressed records; no cross-partition transaction guarantee offered at this layer | Microbatch topology writes are cross-partition transactions; ACID semantics with no isolation levels to tune | | Reactivity | WebSocket streaming at the edge and change-notification-driven transforms | Fine-grained reactive subscriptions that emit minimal diffs on PState changes | | Storage | Columnar cold tier plus a Postgres hot tier under one addressing model, queryable with SQL and via data APIs | Rama's own partitioned storage behind PStates; integrations for Postgres, Cassandra, Kafka, Kinesis and others | | Scale evidence | Single-cluster production use by one operator; no published benchmark | Vendor-published database benchmarks and a large Mastodon demonstration | | Runtime host | Your own Kubernetes cluster, GitOps deploys, standard container tooling | A Rama cluster under its own deployment and licensing model | | Language | Rust serde schemas, CBOR records, TOML pipeline manifests, and transform code in Rust, with untrusted code confined to a sandboxed UDF path | Java, Clojure, or any JVM language | | AI and agents | Coding-agent fleet in isolated pods, an OpenAI/Anthropic-compatible model API with routing, and an automated review-and-fix cycle over the same repository ([AI agents](/applications/ai-agents/overview), [LLM API](/reference/llm-api)) | None; Rama is a backend platform and you bring your own tooling | | Maturity | Early, single-operator, external authoring surface still being consolidated ([data availability](/infrastructure/data#public-availability)) | Commercial product with documentation and support | ## When Redgold fits Redgold fits when the agents are part of the point. The reason the application shape is narrow is that a narrow shape is checkable: an agent produces a schema, a manifest, transform code, and datasets, and CI plus an automated reviewer can verify each artifact before it deploys. The same platform runs the agents in persistent workspaces, meters their model spend, routes their model calls, and deploys their output to your cluster. The distinguishing Redgold surface is the integration of the application spec with agent execution, model access, review automation, and deployment. --- # vs Apache Spark Source: https://docs.redgold.ai/intro/comparison/vs-spark Apache Spark is a distributed analytics engine. It executes batch, streaming, SQL, machine-learning, and graph workloads through APIs in Python, SQL, Scala, Java, and R. Applications bring their own storage, serving layer, deployment system, and operational tooling around the compute engine. Redgold includes a dataflow engine as one part of an application platform. A typed schema and pipeline manifest connect ingestion, transforms, materialized datasets, HTTP or WebSocket routes, a GitOps deployment, and the coding agents that operate them. Its Python surface includes a PySpark-shaped compatibility layer, while the execution and storage path remains Redgold's own. ## Criteria | Criterion | Redgold | Apache Spark | |---|---|---| | Product unit | A pipeline application spanning schema, compute, storage, routes, agents, and deployment | A distributed analytics application or query job | | Authoring | Rust serde schemas encoded with CBOR, pipeline manifests, Rust transforms, and a PySpark-shaped client surface | Python, SQL, Scala, Java, or R APIs across the Spark ecosystem | | Execution | Dataflow stages resolved by the executor, plus compute-on-write transforms | Distributed execution graphs for batch and structured streaming | | Storage | Lance/Parquet cold storage and a Postgres hot tier under one addressing model ([data and pipelines](/infrastructure/data)) | Reads and writes external data systems; storage is outside the engine | | Serving | Declared HTTP and WebSocket routes dispatch into application pipelines | Application serving is assembled separately from Spark jobs | | Deployment | Git-backed container builds, Kubernetes, and ArgoCD ([managed deployment](/infrastructure/deployment)) | Cluster deployment depends on the Spark environment and surrounding platform | | AI and agents | Managed coding-agent workspaces and model API routing share the application runtime | Outside Spark's scope | | Current scale | Early single-cluster production use by one operator | Established distributed analytics ecosystem | ## Redgold scope Spark corresponds to the data-processing layer of the Redgold stack. Redgold's product boundary includes the records before a transform, the datasets and routes after it, the agent that edits the application, and the deployment that runs it. The fixed artifact set gives CI and automated review a bounded application shape to validate. --- # vs Apache DataFusion Source: https://docs.redgold.ai/intro/comparison/vs-datafusion Apache DataFusion is an embeddable Rust query engine built on Arrow. It provides SQL and DataFrame APIs, physical and logical planning, common file-format support, and extension points for building a data-centric system. The host application supplies storage policy, network APIs, deployment, tenancy, and operations. Redgold is the host platform rather than a query-engine library. Its Rust serde and CBOR dataflow contract runs through a dedicated executor and data engine, with Lance/Parquet and Postgres storage, declared application routes, sandboxed untrusted code, and GitOps deployment. Redgold does not expose DataFusion's session or extension APIs as its application contract. ## Criteria | Criterion | Redgold | Apache DataFusion | |---|---|---| | Product unit | An operated pipeline application | A Rust library embedded in another system | | Query interface | CBOR-backed Rust serde dataflow plans, data APIs, SQL surfaces, and a PySpark-shaped client | SQL and DataFrame APIs over Arrow | | Planner and runtime | Redgold's dataflow planner, executor tiers, and engine | Extensible logical and physical query planning inside the host process | | Storage | Managed Lance/Parquet cold tier and Postgres hot tier ([data and pipelines](/infrastructure/data)) | Connectors and file-format support; lifecycle and storage policy belong to the host | | Application serving | Declared edge routes resolved to pipelines and executor-run code | Supplied by the host application | | Untrusted code | Capability-limited Wasmtime for WASM UDFs; deny-by-default Firecracker path for native/Python code on opted-in nodes | Isolation policy belongs to the embedding application | | Deployment and operations | Container build, Kubernetes, ArgoCD, observability, and agent operations | Supplied by the embedding application | | AI and agents | Coding-agent fleet and model routing integrated with the same repositories and data | Outside DataFusion's scope | ## Redgold scope DataFusion corresponds to an engine component that a larger system can embed. Redgold defines and operates that larger system: schemas, ingestion, storage tiers, transformations, routes, isolation, agent workspaces, and deployments all share one application contract. --- # vs Heroku Source: https://docs.redgold.ai/intro/comparison/vs-heroku Heroku is a hosted application platform. Source code becomes a build artifact and runs as managed processes, with platform add-ons supplying databases and adjacent services. The platform abstracts the underlying compute and owns the application runtime lifecycle. Redgold deploys applications through Git-backed builds too, but the deployment target is Kubernetes reconciled by ArgoCD. The deployed artifact is connected to a typed data model, pipeline execution, engine storage, model access, and coding-agent workspaces. Provisioning remains onboarding-driven while the public self-service surface is consolidated. ## Criteria | Criterion | Redgold | Heroku | |---|---|---| | Product unit | A pipeline application plus its schemas, datasets, agents, and routes | An application composed of managed process types and add-ons | | Runtime | Containers on a managed Kubernetes and ArgoCD path | Vendor-managed dynos | | Infrastructure ownership | The application runs on a Kubernetes cluster operated through the Redgold deployment path | The application runs on Heroku infrastructure | | Data | Integrated Lance/Parquet cold tier and Postgres hot tier with Rust serde and CBOR pipeline records | Data services are attached separately through platform products or add-ons | | Deployment | CI builds images and GitOps state; ArgoCD reconciles the cluster ([managed deployment](/infrastructure/deployment)) | The platform builds a source revision and manages process releases | | Compute beyond web processes | Dataflow executor, compute-on-write transforms, model serving, and agent pods | Background and scheduled processes use the application runtime | | AI and agents | Persistent coding-agent workspaces, model routing, metering, and review automation | Outside the core application-runtime contract | | Current access | Managed onboarding; self-service controls are still being consolidated | Established self-service hosted platform | ## Redgold scope Heroku corresponds to the source-to-running-process portion of Redgold. Redgold extends the deploy path into the application schema, data engine, pipeline runtime, model routing, agent workspace, and automated review cycle, all operated through the same platform. --- # vs AI model providers Source: https://docs.redgold.ai/intro/comparison/vs-ai-providers AI providers expose hosted models through APIs and SDKs. The application selects a provider, model, request format, retry policy, and any agent framework built around the response. Provider-native products may also include tools, files, batch processing, evaluations, or managed agent features. Redgold exposes OpenAI- and Anthropic-compatible request formats backed by Redgold models. It connects model access to metering, provider routing, persistent coding-agent workspaces, repository tools, application data, automated review, and deployment. Clients discover the models available to their account through `/v1/models` rather than binding the application to an upstream provider identifier. ## Criteria | Criterion | Redgold | Direct AI provider API | |---|---|---| | API contract | OpenAI-compatible Chat Completions and Responses plus Anthropic-compatible Messages ([model API](/reference/llm-api)) | Provider-native endpoints, SDKs, and model identifiers | | Model selection | Account-scoped model discovery with model routing | Models published by that provider | | Provider handling | Model API authentication, usage metering, retry, and backend availability | The application integrates provider behavior directly | | Agent runtime | Persistent isolated coding workspaces with repository and cluster tools ([AI agents](/applications/ai-agents/overview)) | Varies by provider; model access is the common surface | | Operational record | Conversation, tool-call, token, latency, and cost metadata stored by the platform | Provider usage records plus whatever the application persists | | Data and deployment | Agents can work against platform datasets and the same GitOps application path | Supplied by the application owner | | Compatibility boundary | Compatible wire formats; model behavior and supported fields remain Redgold-specific | Native behavior and full provider feature surface | ## Redgold scope A direct provider API ends at model access. Redgold carries that request into an operated agent lifecycle: workspace provisioning, tools, budgets, provider routing, stored run history, code review, and deployment. The model API also remains usable independently through standard client request shapes. --- # Common tasks Source: https://docs.redgold.ai/intro/starting-points Use this page as the task index for the public documentation. The website, terminal client, existing agents, model API, pipeline applications and data tools share an account, with permissions and spending checked for each service. | Task | Guide | Current access | |---|---|---| | Set up an account and use the hosted website | [Quickstart](/intro/quickstart#1-use-the-website) | Check [account access](https://redgold.ai/signup); request an invitation when signup is closed | | Add tools to an existing agent | [Setup prompt and skills](/users/install/agent-tools) | Account key; service permissions checked separately | | Connect without local binaries | [Hosted MCP](/reference/mcp) | Account key and authorization for each declared API operation | | Install the terminal client | [Install the client](/cookbook/install-client) | Available with an API key | | Search the web and inspect sources | [Search and browsers](/reference/rac#search-the-web) | Search/browser permissions and authorized spending | | Recover decisions and conversation history | [Memory and conversation search](/reference/rac#remember-decisions-and-find-earlier-work) | Configured backends and accessible indexes | | Run remote builds, checks and tests | [Remote build setup](/reference/rac#run-remote-builds-checks-and-tests) | Project-specific builder, credential and budget | | Import JSONL or Parquet and compare datasets | [Data import](/develop/import-your-data) | Existing declared schema and configured engine access | | Finish a useful first project task | [First-task walkthrough](/intro/quickstart#finish-your-first-project-task) | Account and configured workspace | | Carry one project from idea through launch and maintenance | [Build, launch, and grow](/cookbook/launch-and-grow) | Account; setup varies by stage | | Add customer access rules and payments | [Users](/cookbook/launch-and-grow#2-build-the-application-and-decide-who-can-do-what) and [payments](/cookbook/launch-and-grow#3-add-payments-when-the-product-is-ready-to-sell) | App-specific implementation and payment account | | Ship and verify a tested web release | [Test and publish](/cookbook/launch-and-grow#4-test-the-journey-and-publish-the-web-version) | Onboarded managed environment or connected hosting | | Prepare an Android or iOS store release | [Mobile distribution](/cookbook/launch-and-grow#5-prepare-android-and-ios-distribution) | Account connections and iOS signing available; submission pending | | Reach customers and measure useful outcomes | [Discovery and marketing](/cookbook/launch-and-grow#6-help-the-right-people-discover-the-product) | Campaign preparation; provider setup for paid delivery | | Build or change a managed backend application | [Pipeline application walkthrough](/intro/pipeline-app-walkthrough) | Managed preview | | Give repository work to a persistent coding agent | [Coding agents](/applications/ai-agents/overview) | Available | | Organize application work across agents and sessions | [Agent operations](/fleet/overview) | Managed onboarding | | Understand the managed request and delivery paths | [Architecture](/infrastructure/overview) | Public guide | | Call hosted models from an existing application | [First API call](/cookbook/first-api-call) | Available with an API key | | Use Redgold models from a coding client | [Coding-client setup](/intro/quickstart#use-the-api-with-coding-agents) | Available with an API key | | Query data owned by your workspace | [Query application data](/cookbook/mcp-query-data) | Preview onboarding | ## Set up your account and clients The [quickstart](/intro/quickstart) covers the hosted website, repository access, API keys, the terminal client, and the first model-list request. Use the [installation recipe](/cookbook/install-client) when you need platform-specific terminal instructions and troubleshooting. ## Add tools to your existing agent Use the [setup prompt](/users/install/agent-tools) to install `redgold`, `rac`, `rci` and persistent skills, or connect [MCP](/reference/mcp) for remote API discovery and calls. Keep your model provider and add the service you need: search, managed browsing with residential routing and bounded CAPTCHA help, memory, managed Kubernetes workspaces, or remote CI and testing. The [RAC command guide](/reference/rac) covers current search tiers, skill inventory, data import and diff, support, integrations and managed diagnostics. Each service still requires its corresponding access. ## Build, launch, and grow a project Start with [one useful result](/intro/quickstart#finish-your-first-project-task): a working page, a repair, research, or a first application feature. Continue the same project with [Build, launch, and grow](/cookbook/launch-and-grow). Its class-booking example develops into a product with customer access rules, payments, tested web delivery, and mobile-store preparation. The launch page, distribution work, and later fixes use the same product context. The marketing stage covers search, communities, social content, existing customers, and partnerships. A USD 200 monthly budget draft is an optional worked example. [Settings → Marketing](https://redgold.ai/settings/marketing) connects Google Ads and sets monthly spend limits; paid delivery still uses your own advertising account. Follow the lifecycle guide's current availability notes when planning payment integrations and store submission. ## Build and understand pipeline applications A pipeline application is the main application-building model. Its reviewed contract consists of Rust schemas, a pipeline manifest, transforms, inline tests, and API routes. Redgold operates the edge, executor, data engine, storage, and deployment around that contract. The [walkthrough](/intro/pipeline-app-walkthrough) shows one complete managed application at an introductory level. The developer [Pipeline Apps section](/develop/pipeline-apps/overview) covers the deeper architecture, current runtime, portable application preview, and release lifecycle. The [Applications section](/applications/catalog) documents concrete products and case studies built on the platform. ## Work with coding agents Coding agents work in persistent repository checkouts with inspectable conversations, tool calls, and diffs. Fleet controls, budgets, live Stream sessions, pull-request review, and CI all belong to this path. Start with [Coding agents](/applications/ai-agents/overview) for the product model and available access paths. For ongoing work, follow [workstreams and issues](/fleet/workstreams-and-issues), [agent lifecycle](/fleet/agent-lifecycle), and the [application workstream example](/fleet/application-workstream). These connect individual tasks to a verified managed deployment. Agents can author changes to a pipeline application. Coding agents also work in repositories deployed elsewhere, and pipeline applications can be maintained directly through Git. The [quickstart](/intro/quickstart#1-use-the-website) covers account and repository setup before the first task. ## Use hosted models Existing OpenAI and Anthropic clients can use `https://api.redgold.ai/v1` with an `sk-rg-` API key. Redgold provides the account's model list, authentication, usage accounting, and provider routing. Follow the [first API call recipe](/cookbook/first-api-call), configure a supported [coding client](/intro/quickstart#use-the-api-with-coding-agents), or use the [model API reference](/reference/llm-api). ## Access application data Pipeline applications and agent activity write owner-scoped records to the platform data layer. Onboarded workspaces can run read-only queries over their datasets through the supported [MCP query path](/cookbook/mcp-query-data). The pipeline application guides cover application schemas, transforms, and datasets. Dataset onboarding remains coordinated during the preview. --- # FAQ Source: https://docs.redgold.ai/intro/faq ## What is Redgold? A vertically integrated platform for building and operating pipeline applications: a checked-in Rust serde schema encoded with CBOR, declared routes and transforms, managed execution, datasets, and Git-backed deployment. Coding-agent workspaces and the compatible model API support that application path and can also be used independently. The [overview](/intro/overview) explains the idea in full. ## What is a pipeline app? The current customer deliverable is a Git-reviewed Rust schema, pipeline TOML, transform, tests, and API contract running on Redgold-operated routing, execution, storage, and deployment. The broader portable package adds declarative pages, client actions, synchronization policy, permissions, and dependencies; those surfaces remain component or product previews. See the [pipeline application walkthrough](/intro/pipeline-app-walkthrough) and [Pipeline Apps](/develop/pipeline-apps/overview). ## What stops an agent from making a mess? The guardrails are structural. Schemas are validated, routes are declared in a spec and resolved by the edge, code runs in a sandboxed executor with defined capabilities, and every change goes through CI plus an automated reviewer/fixer cycle before it merges or deploys. Model spend is metered per agent, so a runaway session has a bounded cost. ## How does this compare to Rama? Rama overlaps with Redgold's backend and dataflow layer through append-only inputs and materialized views. Its unit is JVM topology code. Redgold's unit is a declarative application spec — typed schema, pipeline manifest, and sandboxed transform code — connected to the agent fleet, model routing, review cycle, and Kubernetes deployment. The [full comparison](/intro/comparison/vs-rama) lists the criteria side by side. ## Do I have to use the whole platform? No. Each layer works on its own: the model API from any existing OpenAI or Anthropic client, agent workspaces against your own repositories, or the full pipeline path with managed deployment. You can keep your own application stack and deployment and adopt only the pieces you want. ## What can I use today? Onboarded accounts can run coding-agent sessions from the web application and call the authenticated model API. Managed data and application deployment are available through onboarding while their self-service controls continue to evolve. ## Which model SDKs work? The public model API supports OpenAI-compatible Chat Completions and Responses requests and the Anthropic-compatible Messages request shape. Use `/v1/models` to discover the model identifiers available to your account. ## Does an agent session reproduce the same result? Session history is persisted and auditable. Model generation, external services, repository changes, and a growing dataset can make a replay produce different output. Reproducible evaluation requires pinned inputs, model and configuration, code revision, and a stable data snapshot. ## Why are some reachable endpoints absent from the API reference? Network reachability is broader than the supported public contract. Product UIs, agents, and internal services use routes that may change with the implementation. Public API pages are generated only from endpoints explicitly approved for external use. ## Is there a public SDK for the data platform? The stable public client surface is currently the HTTP model API. Internal Rust clients and dataflow interfaces exist, but they are withheld from the public reference until the contracts, examples, and compatibility expectations are ready for external callers. --- # Examples Source: https://docs.redgold.ai/cookbook/overview Start with the result you need: build something useful, prepare a launch, improve an existing project, or connect your tools. These recipes cover agents, the downloadable terminal client, model APIs, and managed applications. Each recipe stays focused on one outcome. Recipes explain the goal, what you need first, the steps or commands, the result you should see, and what to check when it does not work. Source links connect the walkthroughs to the relevant product and reference pages. ::note Redgold is pre-release. Model APIs use an account and `sk-rg-` API key. Pipeline applications are coordinated directly as a managed preview; their public docs explain the reviewed artifact boundary and managed provisioning flow. :: ## Build, launch, and improve your project - [Finish your first project task](/intro/quickstart#finish-your-first-project-task) — turn an idea, repair, or research question into one deliverable you can inspect. - [Download the terminal client](/cookbook/install-client) — work with agents from your terminal using your account's configured access. - [Build, launch, and grow one project](/cookbook/launch-and-grow) — continue from a working app through users, payments, tests, web delivery, mobile-store preparation, marketing, and maintenance. The USD 200 budget draft is an optional example. ## Pipeline applications Use this learning track to understand and review a managed pipeline application: 1. [Pipeline application walkthrough](/intro/pipeline-app-walkthrough) — inspect one pipeline TOML and Rust transform together with the customer/Redgold ownership boundary. 2. [Managed application artifacts](/develop/scaffold-a-narrow-app) — understand the schema, manifest, transform, tests, and contract reviewed in Git. 3. [Validate a pipeline application change](/cookbook/validate-pipeline-app) — check schema evolution, manifest lowering, transforms, and the public contract in one reviewable change. 4. [Build a vertical](/develop/build-a-vertical) — see how Redgold connects ingestion, datasets, transforms, routes, and deployment into the application repository. 5. [Verify a managed application deployment](/cookbook/verify-managed-deploy) — match the approved application version to a healthy environment and run a bounded owner-scoped smoke request. Pipeline-app routes are managed-preview routes. The [generated V1 route inventory](/reference/routes/v1) is the authority for self-service public routes; it currently lists the model API routes only. Redgold coordinates application creation, dataset provisioning, route review, publication, and environment deployment directly during the preview. ## Model API - [Create an API key and make your first call](/cookbook/first-api-call) — mint a key, set it in your environment, and confirm it against the model list. - [Call the model API from Python](/cookbook/model-api-python) — drive `/v1/chat/completions` with the OpenAI SDK. - [Use the Anthropic Messages API](/cookbook/anthropic-messages) — point the Anthropic SDK at the same endpoint with a bearer token. - [Check your model-API credit balance](/cookbook/check-credits) — read `/v1/credits` before a long run. - [Retry model API calls under rate limits](/cookbook/retry-rate-limits) — handle `429`, `402`, and `502` the way the API expects. ## Your data and agents - [Connect an MCP client and query your data](/cookbook/mcp-query-data) — attach Claude Code (or any MCP client) and run read-only SQL against a dataset you own. - [Run a pipeline from an MCP client](/cookbook/mcp-drive-agent) — prepare a bounded plan, accept its quote and inspect durable results. - [Connect the hosted MCP server](/reference/mcp) — discover and invoke API operations from your agent using your account key. - [Delegate a task to another agent](/cookbook/delegate-agent-task) — choose the customer REST or authorized managed agent-cli path for a bounded subtask. ## Repositories and pipeline applications - [Set up managed reviews and project memory](/cookbook/managed-review) — agree a paid pilot, configure review depth and spending limits, and inspect retained project context. - [Connect GitHub review automation](/cookbook/connect-github-app) — prepare an onboarded repository for App-based reviewer and fixer workflows. - [Validate a pipeline application change](/cookbook/validate-pipeline-app) — check schema, manifest, transform, tests, and generated references together. - [Walk through the tickets API](/applications/tickets/api-walkthrough) — exercise a complete owner-scoped application's lifecycle. - [Verify a managed application deployment](/cookbook/verify-managed-deploy) — match a deployed version to its repository change and smoke result. ## Terminal client - [Install the terminal client](/cookbook/install-client) — install `redgold` and `rac` with one command and confirm the client picked up your key. - [Point the terminal client at another API host](/cookbook/point-client-at-host) — connect the client to a self-hosted instance. - [Run a one-shot agent task in CI](/cookbook/one-shot-ci) — drive a single task to completion with an exit code you can gate on. --- # Run a one-shot agent task in CI Source: https://docs.redgold.ai/cookbook/one-shot-ci ## Goal Run one agent task to completion without a terminal UI and get a process exit code your CI job can gate on. ## Prerequisites - The `redgold` client installed and a key in `REDGOLD_KEY` (see [Install the terminal client](/cookbook/install-client)). - The repository the task runs against. ## Steps `--one-shot ` drives a single task to completion, then exits with a code that reflects the outcome. It needs a prompt, from `--prompt` or `--prompt-file`: ```bash redgold --one-shot redgold --prompt "run the tests" ``` It runs until the session reaches a terminal state or a bounded idle-quiescence fallback fires, then prints a final line and exits non-zero on failure or timeout: ```text [one-shot] exit_status= summary= ``` `--timeout-secs` (default 1800) bounds the whole run; exceeding it exits with `exit_status = "timeout"`. `--agent-kind` selects the backend — `claude` (the default) or `redgold`. ## Expected output A single `[one-shot] exit_status=... summary=...` line, and a process exit code of `0` on success or non-zero on failure or timeout — so a CI step fails when the task does. ## When it breaks - Exits with `exit_status=timeout` — the run exceeded `--timeout-secs`. Raise the timeout, or check whether the task actually stalled. - Non-zero exit with an auth message — confirm `REDGOLD_KEY` (or `--key`) is set in the CI environment. ## Source [Terminal client reference](/reference/cli) (batch and non-interactive runs). --- # Retry model API calls under rate limits Source: https://docs.redgold.ai/cookbook/retry-rate-limits ## Goal Make a model-API client that reacts correctly when a call is rejected for a rate limit, an upstream failure, or an exhausted balance. ## Prerequisites - A working model-API client (see [Call the model API from Python](/cookbook/model-api-python)). ## What to branch on Branch on the HTTP status, not the wording of the error message. A `429` can come from a per-key requests-per-minute cap, an account limit, or an upstream provider. The per-key limiter states the retry interval in the error message but does not set a `Retry-After` header; an upstream `429` may carry the provider's `Retry-After`, which the API does not forward. So a client honors `Retry-After` when present and otherwise applies its own bounded backoff. Retry `429`, `502`, `503`, and `529`. Do not retry `400` or `401` — correct the request or the credential instead. A `402` means the account is out of credits; add credits rather than retrying (see [Check your model-API credit balance](/cookbook/check-credits)). ## A minimal backoff loop ```python import time, random, httpx def call_with_retry(send, max_attempts=5): for attempt in range(max_attempts): resp = send() if resp.status_code not in (429, 502, 503, 529): return resp # success, or a 4xx to correct rather than retry retry_after = resp.headers.get("Retry-After") if retry_after: time.sleep(float(retry_after)) else: time.sleep(min(2 ** attempt, 30) + random.random()) return resp # surface the final provider-shaped error to the caller ``` ## Expected behavior A transient `429`/`5xx` is retried with backoff and eventually succeeds; a `400`/`401`/`402` returns immediately for you to fix; after the attempt budget is spent, the final provider-shaped error reaches the caller instead of being swallowed. ## When it breaks - Retries never stop — the loop is retrying a status it should not. Confirm only `429`, `502`, `503`, `529` are retried. - A `429` repeats immediately — you are not honoring `Retry-After`, or the per-key cap is genuinely exceeded; read the interval in the error message. ## Source [Limits and retries](/reference/limits) and [Errors](/reference/errors). --- # Connect GitHub review automation Source: https://docs.redgold.ai/cookbook/connect-github-app ## Goal Enable repository-scoped pull-request reviews and eligible follow-up fixes without placing a personal GitHub token in Redgold or repository secrets. ## Prerequisites - administrative permission to install GitHub Apps for the organization; - the repository and branches that automation may access; - a Redgold workspace approved for repository automation; - an agreed reviewer-only or reviewer-and-fixer mode. ## Steps 1. Install the Redgold GitHub App and select only the intended repositories. 2. Ask Redgold to bind the installation and repository to the workspace. 3. Confirm whether review, fixer, and issue-driven automation are enabled. 4. Open a small pull request that changes a documented or tested behavior. 5. Confirm that the App posts against the current commit and that normal repository checks still run. Installing the App grants repository access but does not activate a workflow until the binding and modes are configured. ## Expected result The pull request shows a review from the App identity. When fixer mode is enabled and an eligible finding is accepted, a follow-up commit appears on the pull-request branch and the repository's checks evaluate it. ## Failure modes | Symptom | Check | |---|---| | No review appears | Confirm repository selection, workspace binding, enabled mode, and current installation status | | Review targets an older commit | Push or synchronize the branch, then wait for the current event to be processed | | A fix cannot be written | Check branch protection, App contents permission, and whether fixer mode is enabled | | Duplicate comments appear | Confirm that only one repository automation binding is active | ## Reference For review profiles, round allowances, spending limits, and conversation-history setup, follow [Set up managed reviews and project memory](/cookbook/managed-review). See [GitHub App repository automation](/applications/ai-agents/github-app-automation) for permissions, credentials, and lifecycle boundaries. --- # Delegate a task to another agent Source: https://docs.redgold.ai/cookbook/delegate-agent-task ## Goal Give a second agent an independent, reviewable subtask while the primary agent continues coordinating the larger job. ## Prerequisites - an assigned Redgold agent slot or an authorized managed environment; - a task with a clear file or responsibility boundary; - a completion condition the assisting agent can verify. ## Customer REST path Start the assigned slot and retain the returned agent identifier: ```bash curl -X POST https://api.redgold.ai/v1/agents/spawn \ -H "Authorization: Bearer $REDGOLD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"prompt":"Inspect the API examples and report invalid JSON. Do not edit files."}' ``` Poll or send a follow-up through the same assigned-agent API. The complete request examples are in [REST agent control](/applications/ai-agents/rest-agent-control). ## Managed agent-cli path In an environment where `rac agent` is authorized, first inspect available capacity, then start or prompt the assigned helper using the curated commands in [agent-cli assistance](/applications/ai-agents/agent-cli-assistance). Keep the task description bounded and include the expected verification output. ## Expected result The helper reports its conclusion or changed files, plus the command or evidence used to verify the work. The coordinating agent reviews that result before including it in the final change. ## Failure modes | Symptom | Check | |---|---| | No slot is available | Wait for capacity or continue the task in the current agent | | The helper edits overlapping files | Stop one assignment and repartition by file or responsibility | | The helper lacks authorization | Use the customer REST surface assigned to the workspace or request onboarding | | Work continues after it is obsolete | Cancel or destroy the assigned helper through the same control surface | ## Reference The [AI agents overview](/applications/ai-agents/overview) explains execution, approval, and persistence at a higher level. --- # Validate a pipeline application change Source: https://docs.redgold.ai/cookbook/validate-pipeline-app ## Goal Turn a pipeline application edit into one coherent, verifiable repository change that is ready for managed publication. ## Prerequisites - an onboarded application repository; - a checked-in Rust serde record type; - a pipeline manifest and its transform code; - focused tests for the changed behavior. ## Steps 1. Confirm the Rust schema change is additive, keeps stable identity fields, and gives newly persisted fields compatible serde defaults or optionality. 2. Check that every persisted row has a stable dataset reference and primary key. 3. Validate the pipeline TOML with the repository's manifest test target. 4. Run the transform's focused test with a bounded timeout. 5. Regenerate any reference artifact owned by the repository and run its drift check. 6. Open one pull request containing schema, manifest, transform, tests, and docs. For this monorepo, the focused commands follow this shape: ```bash timeout 300 rac cargo test -p node docs/scripts/gen-route-reference.mjs --check ``` Use the commands supplied by an external application's repository when its layout differs. ## Expected result The manifest parses and lowers, the transform test passes, generated references match their sources, and the pull request shows the intended route and dataset changes together. ## Failure modes | Symptom | Check | |---|---| | Unknown manifest field | Compare the edit with the [pipeline preview](/reference/pipeline-preview) and repository schema | | Missing dataset | Confirm onboarding has provisioned the typed dataset | | Generated docs drift | Run the repository's generator, inspect the diff, then rerun check mode | | Route works but is absent from public reference | Public documentation requires separate contract review and allowlisting | ## Reference Continue with [Build a vertical](/develop/build-a-vertical) and [Scaffold a narrow app](/develop/scaffold-a-narrow-app). --- # Verify a managed application deployment Source: https://docs.redgold.ai/cookbook/verify-managed-deploy ## Goal Confirm that an approved pipeline application version reached its managed environment and that one bounded read or write behaves as documented. ## Prerequisites - an onboarded repository and environment; - a merged application change with passing required checks; - the deployment status surface supplied during onboarding; - a non-destructive smoke request and expected result. ## Steps 1. Record the merged commit identifier and generated application version. 2. Wait for the managed deployment status to report that exact version healthy. 3. Authenticate with a workspace credential. 4. Run the application's smallest owner-scoped read or idempotent smoke request. 5. Compare the response with the example committed alongside the application. 6. Record the version and result on the originating issue or pull request. ## Expected result The status surface and smoke response name the intended version. The request returns only records owned by the authenticated workspace and matches the documented response shape. ## Keep a useful verification record Record the commit and deployed version, environment, check time, expected result, observed result, and any unresolved limitation. Keep credentials and customer records out of the issue; use designated test data and redact identifiers where needed. For a write workflow, check that a test record survives a refresh and a new session. Use a second authorized test identity to check that private records cannot be retrieved across account boundaries. For an integration, verify the failure and retry behavior as well as a successful response. Agree on safe cleanup of any records created by the check. Before accepting important data, document the backup and recovery procedure. Rehearse a restore in a separate environment. A code rollback may not reverse a data migration, so record which versions can read the stored data and who owns recovery if verification fails. The [public website repair case study](/applications/case-studies/public-website-seo) shows how deployment checks can cover both successful routes and deliberate missing-page requests. Its technical results are separate from later search performance measurement. ## Failure modes | Symptom | Check | |---|---| | Status shows an older version | Wait for the managed deployment or ask the operator to inspect the blocked stage | | Authentication fails | Refresh the workspace credential; do not place it in an issue or log | | Empty result | Confirm the workspace owns fixture data and that the query bounds include it | | Contract differs | Stop promotion and correct the implementation or generated reference in a new pull request | ## Reference The [data platform preview](/reference/data-platform-preview) defines ownership and compatibility boundaries. The [tickets walkthrough](/applications/tickets/api-walkthrough) is a complete application-level example. --- # Build, launch, and grow one project Source: https://docs.redgold.ai/cookbook/launch-and-grow ## One project, from idea to an operating product Redgold brings agents, repositories, application data, and delivery work into one continuing project. Start with a useful result, then keep the decisions, implementation, release evidence, and customer feedback together as the product grows. You can work in the website or [terminal client](/cookbook/install-client). Imagine a class-booking app. Its first version lets someone find a class and reserve a place. The next versions introduce organizer permissions, paid passes, a public website, and eventually Android and iOS clients. Its launch needs a clear offer and a way to reach potential customers. After launch, a failed booking or a repeated question becomes the next project improvement. This guide follows that lifecycle. Use the stages your project needs; an internal tool may never need payments, app stores, or advertising. If you need account access first, follow the [quickstart](/intro/quickstart) and check [account access](https://redgold.ai/signup). Create an account when self-serve signup is open, or request access when it is closed. Managed application onboarding remains coordinated during preview. ## 1. Start with the outcome and keep the project context Give the agent the repository or source material, who the product helps, and one result you can inspect. For example: ```text Help me build and operate a class-booking app for independent instructors. A customer should find a class, reserve a place, and see their booking. Instructors should manage their own classes and attendee lists. Use [repository and project material]. Start with a working web booking flow and verify it with test accounts. Keep the product decisions, remaining work, test results, and release notes with this project. Next, we will add payments, prepare mobile clients, and decide how to reach the first customers. For this step, complete the booking flow. Tell me which account connections or product decisions the next step will need. ``` An existing project can start with a repair, migration, research question, or new feature. Use [workstreams and issues](/fleet/workstreams-and-issues) to keep larger goals connected across agent sessions. A first result should be small enough to try, but it should fit the product you intend to keep operating. ## 2. Build the application and decide who can do what For the booking example, ask the agent to build the customer journey together with its data model: classes, reservations, capacity, and cancellations. A managed [pipeline application](/intro/pipeline-app-walkthrough) gives that work a reviewed contract for its data, API routes, transforms, and deployment. Agents can also work in an existing repository with its own application stack. Introduce users and permissions before the first private records arrive. A customer should see their own reservations; an instructor should manage their own classes; an administrator may need a wider view. Have the agent implement and check those rules at the data and API boundaries, including a denied read from a second test account. Redgold has workspace membership and roles, private app sharing with eligible workspace contacts, and explicit permission grants for installed pipeline apps. Workspace onboarding and invitation administration remain managed during preview. Workspace membership controls collaboration in Redgold. Define your product's customer signup, roles, and paid entitlements with the agent as part of its application contract. The [application release lifecycle](/develop/pipeline-apps/release-lifecycle) explains installation, sharing, and capability permissions. ## 3. Add payments when the product is ready to sell When bookings work, decide what the customer buys: one class, a pack of passes, or a subscription. Ask the agent to implement the payment journey in the project repository using your chosen provider, such as Stripe. Include the checkout page, server-confirmed payment status, the entitlement the customer receives, and the cancellation or refund behavior the product needs. Use your own business's payment account and its test environment first. Verify a successful payment, a declined payment, and repeated webhook delivery. In the booking example, a browser returning from checkout should not by itself issue a paid pass; the backend must confirm the payment and issue it once. Keep credentials in the configured secret store. Redgold's own billing already uses Stripe Checkout for plans and credit top-ups, with payment confirmation and a billing portal. Those controls pay for Redgold. A customer application's Stripe integration is separate implementation and configuration work; there is currently no general self-service merchant connector in the app settings. Keep its setup, test evidence, and release work in the same project. ## 4. Test the journey and publish the web version Ask for checks that follow the product's real behavior: make a reservation, prevent overbooking, reject an unauthorized edit, and handle a failed payment. Run the relevant repository tests and CI checks against the change you intend to ship. Keep the result with its commit or pull request so a later agent can see what was verified. For a managed application, Redgold's delivery path connects the reviewed change to publication and environment deployment. For a repository hosted elsewhere, use its connected CI and hosting provider. Domain setup depends on the chosen hosting environment and access to its DNS account. After deployment, try the booking journey at the actual web address, on desktop and mobile. Confirm the deployed version, persistence after a refresh, and the permission boundary with designated test users. A passing local test is one piece of evidence; the [managed deployment recipe](/cookbook/verify-managed-deploy) covers checking the running result and planning recovery. ## 5. Prepare Android and iOS distribution The same project can include mobile clients, their store descriptions, screenshots, test plan, and release notes. Start with a testing destination so you can exercise the booking and payment journey on devices before a public release. Open [Settings → Store publishing](https://redgold.ai/settings/store-publishing) to connect your developer accounts. Then open the app in [Apps](https://redgold.ai/apps) and use **Publishing** to save its bundle or package identifier, destination, and release criteria. For **iOS**, Redgold can verify an Apple Developer connection and prepare the bundle ID, distribution certificate, and provisioning profile. You choose TestFlight or the App Store as the intended destination. An App Store Connect app record may still need to be created in Apple's dashboard before signing setup is ready. For **Android**, Redgold can verify a Google Play service account's access to a specific package by reading its reviews. You can save the intended internal, closed, open, or production track. That check does not verify release-upload permissions, and Android upload-key setup is not yet available. **Building and submitting customer store releases through these controls is not yet available.** Saved branch/tag criteria and passing-check requirements do not start a release. Keep the actual build, signing, and submission handoff in the project's release plan and use an available external release process. Apple and Google control their account requirements, review, and final store availability. ## 6. Help the right people discover the product Return to the problem the app solves. The booking app's launch page should show how someone finds a class and reserves a place, with a working signup, demo, or purchase action. Use a real example and explain access and pricing plainly. For an invite-only offer, describe what follows an access request. Have the agent research where the intended customers already look for help. Then choose a distribution approach that fits that audience: | Where the audience looks | Project work to prepare | |---|---| | Search engines | Useful pages answering specific questions, clear titles, internal links, indexing checks, and a small Search campaign if relevant demand exists | | Relevant communities | A helpful demonstration or post tailored to the community's rules | | Social feeds and video | A short walkthrough showing the result, plus reusable screenshots and copy | | Existing subscribers or customers | An announcement for a consented mailing list and an explanation of what changed | | Partners and related products | A concrete integration, referral offer, or co-marketing proposal for review | You can prepare these materials alongside the product change so the page, demo, release notes, and offer agree. Publish through accounts you control using the available tools and the scope you authorize. A campaign draft does not create an account or buy placement. For Google Ads, open [Settings → Marketing & ads](https://redgold.ai/settings/marketing). When the installation's Google Ads connection is configured, **Connect Google Ads** authorizes Redgold to discover advertisers. Choose an account and use **Use this account** to check access with Google and save the selection in your workspace. Without a workspace selected, the connection is kept in your personal workspace. If you have no advertiser yet, create one at Google Ads first. The connector currently reads account metadata only. It does not create a standalone advertiser, configure billing, or publish campaigns. Google requires you to complete its sign-in, terms, billing, and any advertiser verification. The screen links to those steps. A connected account does not prove that billing or advertiser verification is complete. If the installation connection is unavailable, Settings says so explicitly. Google login, Google Play, Search Console, and Google Ads are separate grants. ### Optional: draft a USD 200 monthly marketing budget The [browser budget draft helper](https://redgold.ai/use-cases/launch-and-grow#launch-planner) prepares a small marketing plan without a Redgold account. Enter the project, audience, public HTTPS destination, calendar month, and useful outcome. It produces a copyable agent brief, a downloadable JSON plan, and campaign links. The portable Node script `workflows/launch-and-grow/prepare.mjs` prepares the same kind of draft for an agent working in a checkout; its directory's README contains the inputs and command. A starting example is **USD 150 for one Google Search campaign and USD 50 reserved**, within **USD 200 total per calendar month**. Use unpaid content or community work first if there is no relevant search demand. The allowance includes any fees, taxes, campaign tools, or model usage charged to marketing; reduce the ad allocation when those costs need more room. The reserve stays unspent until allocated. Enter prior charges, accrued but unbilled spending, and other commitments before marking the budget reconciled. The helper does not read provider billing, store the draft in your account, connect an advertising service, or launch a campaign. Copy or download the draft before leaving. It is a budgeting aid within the larger launch, not the project's release workflow. Review the actual destination, search terms and exclusions, ad copy, location, language, conversion event, dates, and spending controls before paid delivery. An average daily budget is a pacing setting, so check the provider's current charging rules and preserve room for fees and reporting delays. Keep delivery paused if the agreed ceiling cannot be enforced or supervised reliably. ## 7. Learn from use and carry the improvements forward Connect discovery to the product journey: tagged visit → signup or accepted request → first useful booking → confirmed payment → repeat use. Count each stage when it really happens. A click is not a booking, and a checkout redirect is not confirmed revenue. Check that retries do not count twice. For example, a campaign link might use: ```text https://your-project.example/classes?utm_source=google&utm_medium=cpc&utm_campaign=classes_2026_10 ``` Use separate sources for a community post, newsletter, or partner link. Keep personal information out of tracking parameters. Apply your analytics consent settings, and report attribution gaps explicitly when visits and purchases cannot be linked. Bring failed journeys, customer feedback, usage costs, and release evidence back to the same project. Ask an agent to reproduce a failed booking, improve a confusing screen, or implement the next feature, then test and release the change through the same delivery path. Review actual conversions before increasing advertising spend. Redgold's onboarding can capture one categorical setup-failure report after a user opts in for that visit. It creates a support record for review. Ongoing observation or repair of your own application's users needs its own diagnostic scope, data access, and configured workflow. Agree what an agent may inspect, which repairs it may make, and when it should ask for a product decision. For continuing marketing, assign a review cadence and a shared spending ledger. Pause paid delivery when the destination or tracking breaks. A draft plan does not create a monitoring schedule. Keep the maintenance work, operating costs, and the next release visible alongside the product's growth results. ## What the project should retain Open **Settings → Marketing & Ads**, choose your project, and save its monthly spend limit and Google Ads share in USD. The same form is available under the app's **Launch & marketing** tab. Limits are stored with your owned app record and dated to the month they were saved; without a limit, agents treat the work as organic preparation. Redgold does not enforce them at Google, so set matching budgets in Google Ads. Audience, positioning, landing page, conversion goal and channels are worked out with your agent. **Plan strategy with your agent** opens a message with the project and its saved limits in the current account and workspace. Review and send it to start work; later agents should retain decisions, completed steps and source-linked evidence in the project's task records. RAC clients can read or install the same workflow using `rac skills show rac-marketing` or `rac skills install rac-marketing`. Connect Google Ads separately in Marketing settings. That connector currently reads account metadata; it does not inspect spend, verify billing or create campaigns. An agent can guide Search Console and analytics setup using your own authorized accounts. Saving a limit does not start paid advertising, publish community posts or enable recurring monitoring. At each stage, keep the next person or agent able to continue: the product goal, repository and app, access rules, payment integration status, relevant test results, deployed version, store preparation or release status, launch material, and unresolved work. The useful outcome is an increasingly complete product with evidence of what works and a clear next step. Continue with [common tasks](/intro/starting-points), the [application workstream example](/fleet/application-workstream), or [deployment verification](/cookbook/verify-managed-deploy) for the next part of your project. --- # Set up managed reviews and project memory Source: https://docs.redgold.ai/cookbook/managed-review Redgold's [managed review offer](https://redgold.ai/managed-review) helps small teams configure and operate pull-request reviews with useful project context. Managed review access is coordinated during preview, separately from general [account signup](https://redgold.ai/signup). An account does not activate a managed review pilot. Start with one repository, an agreed review workflow, and written pricing before enabling paid use. ## Request a setup Use the [managed review request form](https://redgold.ai/request-access?offer=managed-review). Describe the project, approximate pull-request volume, and the work you want to improve. A project description is sufficient; do not upload private code or credentials to the request form. Optional budget ranges help the onboarding discussion and are not service prices. The form saves the request only after you agree to contact about access and onboarding. A receipt confirms that the request was saved. It does not create an active workspace, activate repository automation, or charge you. Agree these items before purchasing: - the repositories, supported languages, and review behavior included; - setup work, ongoing operating help, and who handles an incomplete run; - the subscription, any setup fee, included usage, and additional usage rates; - separately billed model providers, compute, and other connected services; - the first completed review used to evaluate the pilot; - cancellation and the handling of retained project data. [Workspace prices](https://redgold.ai/pricing) are the published subscription plans. A workspace price alone is not a quote for every managed service or unlimited model and compute usage. ## Connect the repository In **Settings → GitHub account**, install or connect the Redgold GitHub App and select only the intended repositories. Redgold confirms the repository's workspace binding and enabled automation during onboarding. App installation alone does not activate review processing. Open the repository's **Review settings** and agree the initial policy: | Control | What it changes | | --- | --- | | Economy, Standard, or Deep | The review profile and depth | | Independent reviewers | The number of perspectives within a review, from 1 to 4 | | Review rounds per PR | How many review runs are allowed on one pull request, from 1 to 5 | | Allow fixer commits | Whether eligible corrections may be written to the pull-request branch | | Fixer rounds | The permitted correction attempts, from 1 to 3 when enabled | | Monthly repository automation spend | The recorded-usage limit for subsequent model calls in the monthly window | | Per-PR lifetime spend | The recorded-usage limit shared by automation for that pull request | Begin with fixer commits off while assessing review findings. Keep the repository's existing CI, branch protection, and maintainer merge policy. A review or an eligible correction is not permission to merge automatically. Spending limits stop future model calls after charged usage reaches the configured limit. Calls already in flight can overshoot, and configuration or usage can take up to 30 seconds to propagate. These controls are not a prepaid guarantee or a cap on the complete invoice. Review the actual billing terms and any direct provider charges as well. ## Prepare project context Keep current contribution rules, important constraints, and test commands in the repository. Include the reason and source for a decision so a reviewer can check whether it still applies. For supported conversation history, open **Settings → AI accounts & history → Import conversation history**. Choose the appropriate `.claude` or `.codex` folder and review the files selected for import. This is a selected-file import, not continuous synchronization with your device. Use **Check indexed history** to inspect readiness after an import. Use the separate **Search workspace history** form to find retained context. Open a result's source to confirm that it belongs to the intended workspace and is useful to the project. A saved upload, an indexed record, and a retrieved source in a review are separate outcomes; confirm the one you need instead of inferring it from another. During onboarding, agree what is retained and how to inspect, correct, or remove it. Saved history does not mean every conversation is included in every review or that a private model is trained on it. See the [project-memory guide](https://redgold.ai/learn/project-memory-for-code-review). ## Inspect the first completed review Choose a small pull request where the intended behavior and relevant project constraint are clear. Record its commit and the selected review policy. 1. Confirm that the run belongs to the intended repository and workspace. 2. Inspect its activity, outcome, and charged usage. Identify stopped, failed, and incomplete stages separately from completed review findings. 3. Confirm that the posted review refers to the intended commit. 4. Open relevant conversation or context source links. Distinguish no matching history from unavailable or failed retrieval. 5. Have a maintainer assess which findings are useful and which need correction. 6. Run the repository's normal checks and merge only under its existing policy. The pilot succeeds when your team can inspect a completed review and decide whether its findings, cost, waiting time, and operating effort are worthwhile. A completed model response alone does not establish review accuracy or savings. ## Resolve common problems | Symptom | Next check | | --- | --- | | No review starts | Repository selection, workspace binding, enabled policy, and available execution capacity | | The next review does not run | Review-round allowance, spending limits, and the activity reason | | Missing project context | Import/index readiness, workspace ownership, retrieval outcome, and the source link | | A review is incomplete | Failed stages and the recorded run status; do not count it as a complete review | | A correction is absent | Fixer setting, remaining rounds, repository permissions, and branch rules | | A review refers to an earlier commit | Compare the review's recorded commit with the current PR; confirm eligibility before requesting another round | Keep the run reference and commit when requesting operating help. Never paste tokens into public GitHub comments. For integration details, see [Connect GitHub review automation](/cookbook/connect-github-app). For a real workflow account and its limits, see [Elusive managed reviews](/applications/case-studies/elusive-managed-review). --- # Create an API key and make your first call Source: https://docs.redgold.ai/cookbook/first-api-call ## Goal Get a working `sk-rg-` API key and prove it authenticates by listing the models your account can use. ## Prerequisites - A Redgold account. Check [account access](https://redgold.ai/signup); create one when self-serve signup is open, or request an invitation when it is closed. - `curl`. ## Steps Create the key from the API-keys page in the signed-in web application. The full value is shown once — copy it then. Minting a key requires an account session; an existing API key cannot mint another. Put the key in your environment rather than typing it inline, so it stays out of shell history: ```bash export REDGOLD_API_KEY=sk-rg-... ``` Call the authenticated model list. The key goes in the `Authorization: Bearer` header — the API reads the credential only from that header (or the web session cookie), and rejects a key supplied only as `X-Api-Key` with `401`. ```bash curl https://api.redgold.ai/v1/models \ -H "Authorization: Bearer $REDGOLD_API_KEY" ``` ## Expected output An OpenAI-style model-list envelope, with one entry per model your account can reach: ```json { "object": "list", "data": [{ "id": "model-id", "object": "model", "owned_by": "redgold" }] } ``` Treat `/v1/models` as the authoritative list and read an identifier from it — the set changes independently of client code, and not every account sees every entry. ## When it breaks - `401` — the key is missing, malformed, revoked, or was sent only as `X-Api-Key`. Re-check the header and the key value. - `402` — the account is out of model-API credits. See [Check your model-API credit balance](/cookbook/check-credits). ## Source [Authentication](/reference/authentication) and [Model API](/reference/llm-api). --- # Call the model API from Python Source: https://docs.redgold.ai/cookbook/model-api-python ## Goal Send a chat completion from Python using the OpenAI SDK against the Redgold model API. ## Prerequisites - An `sk-rg-` key in `REDGOLD_API_KEY` (see [Create an API key](/cookbook/first-api-call)). - `pip install openai`. ## Steps Point the OpenAI client at `https://api.redgold.ai/v1` and pass the key as the API key. The OpenAI SDK sends it as a bearer token, which is what the model API reads. ```python import os from openai import OpenAI client = OpenAI( base_url="https://api.redgold.ai/v1", api_key=os.environ["REDGOLD_API_KEY"], ) models = client.models.list() print([model.id for model in models.data]) response = client.chat.completions.create( model="redgold-flint", messages=[{"role": "user", "content": "Hello"}], ) print(response.choices[0].message.content) ``` Read the model id from `client.models.list()` rather than hard-coding one — the available set changes independently of client code. For token streaming, pass `stream=True` and consume the SDK iterator. ## Expected output The printed list of model ids your account can reach, then the assistant's reply text from `response.choices[0].message.content`. ## When it breaks - `401` — bad or missing key. Confirm `REDGOLD_API_KEY` is exported in the shell that runs Python. - `400` with an unknown-model message — refresh the id from `client.models.list()`. - `429` — a rate limit. See [Retry model API calls under rate limits](/cookbook/retry-rate-limits). ## Source [Model API](/reference/llm-api) (OpenAI Chat Completions). --- # Use the Anthropic Messages API Source: https://docs.redgold.ai/cookbook/anthropic-messages ## Goal Call a Redgold model through the Anthropic Messages API shape on the Redgold model API. ## Prerequisites - An `sk-rg-` key in `REDGOLD_API_KEY` (see [Create an API key](/cookbook/first-api-call)). - `pip install anthropic`. - A `/v1/messages`-family model id from `/v1/models` (see [Model API](/reference/llm-api)). ## Steps Two details differ from a direct Anthropic call. Set `base_url` to the host **without** a `/v1` suffix — the SDK appends `/v1/messages` itself. And present the key on the `Authorization: Bearer` header, because the model API reads that header, not the `x-api-key` the SDK sends by default. ```python import os from anthropic import Anthropic client = Anthropic( base_url="https://api.redgold.ai", api_key="unused", # the model API reads Authorization, not x-api-key default_headers={"Authorization": f"Bearer {os.environ['REDGOLD_API_KEY']}"}, ) with client.messages.stream( model="model-id-from-v1-models", max_tokens=256, messages=[{"role": "user", "content": "Hello"}], ) as stream: for text in stream.text_stream: print(text, end="") ``` ## Expected output The assistant's reply streamed to stdout token by token. ## When it breaks - `401` — the key reached the API only as `x-api-key`. Confirm the `Authorization: Bearer` header is set in `default_headers` as shown. - `404` on `/v1/messages` — `base_url` includes a `/v1` suffix. Drop it; the SDK adds the path. - `400` unknown model — the id is not a `/v1/messages`-family model for your account. Read one from `/v1/models`. ## Source [Model API](/reference/llm-api) (Anthropic Messages). --- # Check your model-API credit balance Source: https://docs.redgold.ai/cookbook/check-credits ## Goal Read the available model-API credit balance for your account before starting a run that will make many calls. ## Prerequisites - An `sk-rg-` key in `REDGOLD_API_KEY` (see [Create an API key](/cookbook/first-api-call)). - `curl`. ## Steps ```bash curl https://api.redgold.ai/v1/credits \ -H "Authorization: Bearer $REDGOLD_API_KEY" ``` ## Expected output ```json { "balance_micros": 1000000, "balance_usd": 1.0 } ``` `balance_micros` is the balance in millionths of a dollar; `balance_usd` is the same figure in dollars. A balance at or near zero means the next model call returns `402`. ## When it breaks - `401` — bad or missing key; re-check the header. - A model call returns `402` even though this read succeeded — the account ran out of credits between the two calls. Add credits and retry. ## Source [Model API](/reference/llm-api) (Credits) and [Authentication](/reference/authentication). --- # Connect an MCP client and query your data Source: https://docs.redgold.ai/cookbook/mcp-query-data Connect your Streamable HTTP client to `https://api.redgold.ai/api/mcp` with an account key as `Authorization: Bearer`. See [MCP setup](/reference/mcp) for initialization and client configuration. Call `data_catalog` with `{"kind":"dataset","limit":20}`. Select a returned dataset reference, then call `data_describe` with `{"kind":"dataset","name":""}` to inspect its schema. Submit a query using the exact dataset name and a stable task key: ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "data_query", "arguments": { "dataset": "", "idempotency_key": "analysis-42-query", "limits": {"max_scan_rows": 1000, "max_scan_bytes": 1048576, "timeout_ms": 10000, "max_output_rows": 10, "max_charge_microusd": 100000} } } } ``` Use `tools/list` for additional supported fields. A supported single-dataset SELECT may be supplied in `sql`; all relations must resolve to the named dataset. The result's `structuredContent` contains a durable `run_ref`. Poll `pipeline_status` with that reference until execution completes, then call `pipeline_results` with `{"run_ref":"","limit":10}`. Report completeness, truncation, exact revision, usage and actual charge. A small result page does not constrain the scan by itself. Reuse the same task key after a lost query response. An `idempotency_conflict` means the key was already bound to different parameters. Bad input is rejected before effects; use `data_describe` to correct it. Denied access requires the right workspace or an authorized dataset. An uncertain supplier outcome needs its existing receipt reconciled instead of a new key. --- # Run a reviewed pipeline from an MCP client Source: https://docs.redgold.ai/cookbook/mcp-drive-agent Connect through [MCP setup](/reference/mcp), then discover recipes using `data_catalog` with `{"kind":"recipe","limit":20}`. Inspect the selected recipe with `data_describe`. Its native-generated examples and schema describe the current request contract. For a saved summary, select an accessible source dataset and a supported `sink_` output dataset. Prepare a plan: ```json { "recipe": "dataset-summary", "input_dataset": "", "output_dataset": "sink_research_summary", "parameters": {"group_by": [""], "function": "count", "output_limit": 50}, "limits": {"max_scan_rows": 1000, "max_scan_bytes": 1048576, "timeout_ms": 10000, "max_charge_microusd": 100000, "max_storage_bytes": 1048576} } ``` Preparation reports effects, revisions, the immutable price and maximum charge without executing work. If those fit the user's task and spending authority, call `pipeline_run` with `{"prepared_ref":"","idempotency_key":"research-42-summary"}`. Poll `pipeline_status`, then read a bounded `pipeline_results` page. Complete output carries an owner-scoped dataset and output receipt. Partial scans do not publish a complete summary. `search-to-dataset` combines one existing search connector with native persistence. Its parameters are `query`, `provider` and `max_results`; its output is `agent_search_result_v1`. The limits must include an authorized connector allowance and storage allowance. Supplier charges are allocated from the parent run reservation and included once in the final charge. The original stored supplier delivery is reused on recovery. For recurrence, use `pipeline_host` with action `prepare`, the accepted preparation, interval and daily/monthly budgets. `deploy` performs a paid smoke run and leaves the host `ready_paused`; only an explicitly requested `activate` starts scheduling. Every control mutation uses a stable idempotency key. Pause disables future admissions. Rollback re-verifies the prior accepted revision and returns paused without undoing existing outputs. Use the data and pipeline tools for the prepare/quote/run workflow above. The hosted server also exposes `api_search`, `api_describe` and `api_call` for declared API operations, including agent and approval APIs where the deployment and caller permit access; their existing authorization and approval rules still apply. Browser change-monitor recipes appear in discovery only after their separate connector integration is available. --- # Install the terminal client and agent tools Source: https://docs.redgold.ai/cookbook/install-client Install `redgold` for terminal conversations, `rac` for agent tools and `rci` for its CI companion. To have an existing agent do this setup, use the [setup prompt and skills](/users/install/agent-tools). For remote API tools without local binaries, use [hosted MCP](/reference/mcp). ## Before installing Create an account API key in [Settings → API Keys](https://redgold.ai/settings/api-keys). If you need an account, start with [account access](https://redgold.ai/signup). Make the key available through your secret manager as `REDGOLD_API_KEY`; keep its value out of conversations and repositories. The bootstrap reads this variable before fetching protected manifests and binaries. The Linux CLI channel requires x86_64 with glibc 2.39 or newer, such as Ubuntu 24.04 or Debian 13. Debian 12 and Ubuntu 22.04 cannot run the current `rac` binary. The current macOS agent tools are for Apple silicon; the terminal client also has a universal macOS archive. Check the installer's `--help` for the selected platform. Signature verification needs Python 3 and OpenSSL 3; the default companion install also needs `unzip`. ## Install Inspect the [official installer](https://redgold.ai/install.sh) before running it. In a shell with `REDGOLD_API_KEY` available: ```sh curl -fsSL https://redgold.ai/install.sh | bash -s -- --without-engine --without-aws export PATH="$HOME/.redgold/bin:$PATH" redgold --version rac version --json rci --version ``` The installer checks release hashes and signatures and installs to `~/.redgold/bin`. It checks the downloaded CLI before replacing an existing installation. Add that directory to your shell's `PATH` for future sessions. This command keeps the `rci` companion and omits the optional local data engine and AWS CLI. Leave off an exclusion only when you need that component. `--without-rci` omits the CI companion too; commands delegated to it then need a separately installed `rci`. Installation alone grants no builder or fleet access. ## Choose your workflow | Goal | Next step | |---|---| | Add tools to an existing agent | [Install persistent skills](/users/install/agent-tools#keep-the-skills-available-across-sessions) | | Search, browse or recover earlier decisions | [RAC command guide](/reference/rac) | | Run remote builds and tests | [Builder configuration](/reference/rac#run-remote-builds-checks-and-tests) | | Use remote API tools through MCP | [MCP setup](/reference/mcp) | | Work in a managed agent conversation | Run `redgold`, or `redgold run --prompt "run the tests"` | Keep your existing model provider when adding tools. Hosted conversations use the model access enabled for your account and workspace. Connect a BYOK provider in **Settings → AI accounts & history** where required; a download key does not supply provider credentials or enable a model plan. Model routing remains subject to the selected installation's current rollout and account policy. ## Updates Inspect and rerun the same official bootstrap to update the tool set. Compare and reinstall your selected skills afterward, preserving local edits. `redgold --update` updates the terminal client; it does not replace the whole agent-tool and skill setup. ## When it breaks | Symptom | Next step | |---|---| | Download returns 401 or 403 | Check the exported account key and selected installation | | CLI cannot run on this platform | Check architecture, glibc and installer diagnostics before replacing a working installation | | `rci` is missing | Rerun the bootstrap without `--without-rci` | | Search or browser returns 403 | Check the corresponding service permission and workspace | | Search or browser returns 402 | Check Billing credit; setup does not authorize a purchase | | Builder rejects a request | Check the project's provisioned endpoint and builder credential | | Provider returns 401 | Reconnect the selected workspace's model account | | Session disconnects | Inspect the assigned agent's status before retrying work | An API key, a successful download and a search quote verify different things. Report which checks actually completed and which services still need setup. Continue with the [terminal reference](/reference/cli) or [RAC command guide](/reference/rac). --- # Point the terminal client at another API host Source: https://docs.redgold.ai/cookbook/point-client-at-host ## Goal Point the terminal client at an API host other than the managed default — for example a self-hosted instance. ## Prerequisites - The `redgold` client installed (see [Install the terminal client](/cookbook/install-client)). - The API host URL you want to connect to, and a key that host accepts. ## Steps The installer points the client at the managed API host, so in the common case you only supply a key. To reach a different host, pass `--api ` or set `REDGOLD_API`. The key can come from `--key` / `REDGOLD_KEY`. Run with no mode flag first to confirm the wiring on the status screen: ```bash REDGOLD_API=https://api.example.internal REDGOLD_KEY=sk-rg-... redgold ``` Once the status screen shows the right host and `key` set, open a live view. `--env ` opens the environment view for a repository, where you can spawn (`s`) and stop (`x`) sessions: ```bash redgold --env redgold --api https://api.example.internal --key sk-rg-... ``` ## Expected output The status screen shows the API host you passed and the WebSocket URL derived from it. In `--env`, the environment and its live sessions list as the server reports them; `no environments yet — attaching` means the environment is still coming up — wait for it to reach `RUNNING`. ## When it breaks - Status screen shows the wrong host — the flag or env var did not reach the client. `--api` overrides `REDGOLD_API`; confirm which one you set. - Status screen shows `key: none` — the host-specific key was not picked up. Set `--key` / `REDGOLD_KEY`. - `no environments yet — attaching` stays on screen — the environment has not reached `RUNNING` yet. Wait, or check the host. ## Source [Terminal client reference](/reference/cli) (authentication and connection settings). --- # Running agent work Source: https://docs.redgold.ai/fleet/overview Use Redgold agents to build and evolve a fully managed application: describe an outcome, organize the work, review changes and verify the deployed behavior. Redgold provides the workspaces and supporting infrastructure and operates the application's pipelines, data and deployment. Fleet management is how you keep several pieces of that work moving coherently. These guides describe the managed workflow. Workstream scheduling and fleet controls depend on the environment enabled during onboarding; they are not a promise that every account has an unrestricted fleet API. The [assigned-agent REST guide](/applications/ai-agents/rest-agent-control) documents the current customer control boundary. ## The pieces you work with | Concept | What it represents | Support-app example | |---|---|---| | Application | Running behavior, schemas, pipelines and data | A support queue with automated triage | | Workstream | A continuing objective grouping related issues | Improve urgent-request handling | | Issue | A bounded outcome with acceptance and dependencies | Preserve urgency when requests are retried | | Agent | The worker assigned to investigate or change the app | Implement and verify duplicate handling | | Slot | Assigned execution capacity | An environment in which an agent can run | | Workspace | Repository checkout and working files | Schema, transform, manifest and tests | | Session | A conversation and its tool activity | The implementation run and review feedback | | Delivery | Reviewed revision through deployment and verification | The updated support route serving users | An issue can outlive a session, and a workstream can involve several issues and agents. A running agent may be waiting on a test or decision; its process state alone does not tell you whether the application objective is complete. ## Follow one application change 1. [Define the workstream and issues](/fleet/workstreams-and-issues): state the outcome, split independent work and record dependencies. 2. [Understand agent lifecycle](/fleet/agent-lifecycle): distinguish queued work, startup, active execution, waiting and completion. 3. [Supervise and recover](/fleet/supervision): inspect evidence and intervene at the right boundary. 4. [Follow an app workstream to delivery](/fleet/application-workstream): a worked example covering a blocked decision, parallel work and deployment verification. ## Working with external systems Agents can also maintain an authorized external repository, review its pull requests and use its existing checks. Managed applications can connect to external APIs and data sources. Specify which parts Redgold operates and which remain external when defining the workstream; an external repository connection does not automatically make its hosting a managed Redgold deployment. Start with [coding agents](/applications/ai-agents/overview) for a single task or [architecture](/infrastructure/overview) for how agent work connects to the managed application runtime. --- # Workstreams and issues Source: https://docs.redgold.ai/fleet/workstreams-and-issues A workstream gives a managed application a continuing objective. Issues divide that objective into changes an agent can finish and someone can verify. The workstream preserves the larger purpose when individual sessions end. ## Start with an outcome For a support application, use an objective such as “Urgent requests reach the right queue without duplicate entries.” Record the affected application and environment, expected behavior, scope limits and a way to demonstrate success. “Improve the backend” leaves too much unstated to schedule or review. A workstream is represented by an epic root ticket. Related issues point back to that root. Agents can propose a workstream and attach issues immediately; human approval is a separate step before the managed workstream scheduler admits its work. Approval applies to that root, not an unrelated proposal. ## Run the workstream conversation Each workstream has one ordinary conversation and one normal d-pod runtime. Choose **Redgold TUI**, **Codex**, or **Claude Code** before the first Run. The conversation follows the normal repository and delivery instructions, including checks, review, publication and verification when its task requires them. After approval, **Run** sends the root brief, settings and ready issue context to that conversation. It also works when the root brief is the only work available. Use `--ticket` to identify a ready member to work on first. Subsequent turns reuse the same conversation. A repeated Run while it is active or awaiting dispatch returns its current state without starting another runtime. ```sh rac workstream settings rac workstream settings --harness codex --cost normal --reasoning max --provider-policy codex-only --dry-run rac workstream settings --harness codex --cost normal --reasoning max --provider-policy codex-only rac workstream configure --runtime tui rac workstream status rac workstream run rac workstream run --ticket ``` `settings` is an alias of `configure`; `--harness` and `--reasoning` are aliases of `--runtime` and `--effort`. With no edit flags it reads compact JSON settings and ordinary conversation evidence, without loading every member. `--dry-run` validates the same change and shows before/after settings without writing. Settings changes preserve approval, pause, schedule and conversation identity; revision-aware servers reject a stale edit rather than overwrite a concurrent Stop or policy change. A failed conversation observation appears separately from whether settings were saved. Null policy values inherit conversation defaults. When switching away from a TUI with stage presets or legacy model pins, add `--clear-model-pins` to explicitly remove those TUI-specific settings. `--runtime codex` requests Codex through ordinary conversation admission. Native Codex requires an authorized personal gateway conversation; workspace and direct-credential conversations use the isolated TUI adapter. Runtime availability and authorization follow the same rules as a user-started conversation. An existing conversation retains its runtime binding. Codex also retains the original provider, model and authentication selection: changing its cost profile can hold later turns until the original selection is restored. A conflicting selection is reported instead of creating another conversation. `--runtime claude` selects the native Claude Code harness for an authorized personal Anthropic gateway conversation. It runs Claude's own interactive CLI, tools and resumable session. Its transcript stays in the workstream conversation; the native parent turn must finish before the next scheduled turn can start. Workspace, imported and direct-credential conversations retain the isolated TUI adapter. The selected model and reasoning effort remain bound to the native session; use a fresh conversation to change them. `mixed-claude` and `claude-only` are model presets for **Redgold TUI**. They choose models for its stages and do not select the native Claude harness. For native Claude, clear TUI model pins if present: ```sh rac workstream configure --runtime claude --provider-policy mixed --clear-model-pins --dry-run rac workstream configure --runtime claude --provider-policy mixed --clear-model-pins ``` To apply a changed harness, wait for the current turn to settle, then inspect `rac workstream run --fresh-conversation --ticket --dry-run`. Remove `--dry-run` to submit the guarded transition. It retains the previous conversation in history and checks the exact settled message and control generation. Approval and pause gates still apply; `rac workstream resume ` opens a paused schedule without starting a turn. After an uncertain response, recover the retained transition receipt before retrying Play. Status links to the workstream conversation and reports its acknowledged pod and session. **Pending** means dispatch is unconfirmed. **Accepted** means the message was accepted by Send. **Running** requires ordinary runtime evidence. **Idle** means the turn stopped; inspect its result to establish whether the work succeeded. Approval and scheduling holds remain visible separately from runtime state. Existing executor claims remain available as historical evidence. A live legacy execution must finish or be stopped through its existing controls before a fresh ordinary conversation can start for that root. ### Record complete delivery Keep the root and issue IDs, conversation and message IDs, runtime evidence, and the useful result. For a code delivery, also record the pull request, tested head, merge and publication revision, and deployed verification. An accepted message or an open pull request is an intermediate result. The workstream conversation owns the same delivery lifecycle as an ordinary user-started task. ## Write an issue an agent can finish Use `rac issue update --add-dependency ` or `--remove-dependency ` to change prerequisites without replacing the rest of the dependency list. Both accept repeated flags or comma-separated IDs and preserve ticket ownership and other fields. The update carries the current row revision when the server supports it; a concurrent edit requires a fresh read. A useful issue includes: - the observed problem and desired behavior; - the relevant app, repository and environment; - acceptance examples, including a failure or duplicate case; - dependencies and scope boundaries; - required evidence, including deployed behavior when delivery is in scope. For example: “Submitting the same support-request id twice must leave one queue entry. Preserve its original priority. Demonstrate the behavior with a focused test and an authorized read after managed deployment.” This defines a result without forcing the agent to follow an unverified implementation guess. ## Separate grouping from ordering Parent/root links organize issues. Dependency links define ordering. Two issues belonging to the same workstream are not automatically sequential. ```mermaid flowchart LR Contract[Agree duplicate-request behavior] --> Transform[Implement schema and transform change] Contract --> Fixture[Prepare acceptance fixture] Transform --> Verify[Integrate, deploy and verify] Fixture --> Verify ``` Keep independent investigations parallel where capacity permits. Changes to the same schema or files need a clear owner and an integration step. A dependency becoming terminal is a scheduling signal; a cancelled prerequisite still needs review to establish whether its dependent work makes sense. ## Track progress with evidence | Issue state | What to record | |---|---| | Open | Defined scope, acceptance and dependencies | | In progress | Current assignment and material findings | | Blocked | The exact missing decision, access or external condition | | Done | Evidence that the issue's acceptance criteria were met | | Cancelled | Why the work is obsolete and what happens to dependents | A code-only issue may finish with a reviewed change if that is its stated scope. A delivery issue needs the deployed result. Keep a separate delivery issue when several implementation issues contribute to one rollout. ## Pause, reprioritize and follow up Pause holds future scheduling and pauses the linked ordinary session. Resume continues that session without submitting another task. Stop holds scheduling and stops the linked session. Controls require acknowledgment before reporting success; an uncertain result leaves the scheduling hold in place. Completed issues retain their state, and the conversation association remains available. ```sh rac workstream pause rac workstream resume rac workstream stop ``` `play` aliases `run`; `unpause` aliases `resume`. Add `--dispatch-only` to Pause or Resume when only the root's scheduling gate should change. These controls preserve approval, issue history and unrelated agent assignments. Run can reopen an explicitly held root after the linked session's state has been confirmed. When priorities change, identify both queued and active assignments so obsolete work does not continue unnoticed. Put newly discovered work into linked follow-up issues with its own acceptance criteria. This keeps the current change reviewable while preserving discoveries. Use issue comments for significant failures and their resolution, with links to the corresponding revision and verification result. The [tickets application](/applications/tickets/overview) explains the managed issue store and its onboarding API. Continue with [agent lifecycle](/fleet/agent-lifecycle) to follow an eligible issue into execution. ## Queue automation **Manual** waits for an explicit Run. **Continuous** wakes the same conversation when ready work is available and the previous turn has stopped. **Scheduled** uses a five-field UTC cron expression and sends one workstream brief turn when due, including when no issues are ready. Ready issues are included as context; paused or dependency-blocked issues remain ineligible. Continuous waits when the ready queue is empty. Missed occurrences are combined into one wake. The next occurrence reuses the same conversation after its previous turn has stopped. Saving a new schedule starts its clock at the save time. All three modes use ordinary conversation Send. The conversation selects and completes work using its normal instructions. Scheduling does not create a per-ticket executor claim or manage another review and publication lifecycle. Each workstream remains one conversation even when its agent delegates internally. The core engine hosts scheduling as native cron or retained-event pipeline activation. Each program has a durable clock/event cursor, an immutable pending invocation and a fenced retry lease. Workstream settings project into that same language, so the existing CLI and UI controls retain their behavior. The engine reuses ordinary conversation admission, runtime quotas, approval, dependencies and root holds. A paused or busy conversation cannot admit another automatic turn. The executor pool no longer owns workstream scheduling. Recurring queue producers are declarations under `pipelines/automations/workstreams/`. They retain existing ticket IDs and bounds, with frozen submissions checked against the root's control generation. Finite native-release/question workers run as Jobs dispatched by the engine; their timing is also engine-owned. Configuring automation does not approve a proposal, resume an intentionally paused root, or change autoscaler settings. ```sh rac workstream schedule --mode continuous rac workstream schedule --mode cron --cron '0 9 * * 1-5' rac workstream schedule --mode manual ``` --- # Agent lifecycle Source: https://docs.redgold.ai/fleet/agent-lifecycle An agent's runtime, its issue and the application's deployment each have their own progress. Read them together: “agent stopped” does not mean “issue done,” and “change merged” does not mean “application updated.” ## From queued work to a running session The following stages describe the workflow rather than a single API enum. | Stage | What it means | What to check | |---|---|---| | Queued | Work is recorded but execution has not started | Dependencies, approval, pause policy and capacity | | Assigned | A worker or slot has been selected | Assignment identity and target workspace | | Starting | The runtime accepted startup and is preparing the session | Readiness rather than the acknowledgement alone | | Working | The agent is inspecting, editing or verifying | Conversation, tool activity and current diff | | Waiting | Progress depends on a check, decision or external condition | The specific dependency and who can resolve it | | Delivering | Reviewed work is moving through publication and deployment | Approved revision and current delivery stage | | Finished | The run ended | Issue acceptance and remaining delivery work | Starting an assigned slot through REST is asynchronous. The response contains a command id and a provisioning status. It acknowledges the request before the agent is ready, and does not allocate additional capacity. The [REST control guide](/applications/ai-agents/rest-agent-control) provides exact request examples and the supported readiness surfaces. ## Continue or redirect work Send a follow-up in the existing session when its context still applies. Name the issue, correction and expected result: “Keep the current schema; fix duplicate handling in the transform and rerun its focused test.” Record a material scope change on the issue too, so a later session inherits it. When delegating, give each helper an independent responsibility and an explicit completion condition. The coordinating agent must review and integrate the results. Multiple agents editing the same files without coordination increases conflict risk and can erase the expected benefit of parallel work. ## Stop, pause and recover Pausing a workstream gates new assignments. Stopping an assigned agent requests termination of that runtime and is asynchronous. Neither action rolls back an already published application change. Confirm termination before assigning a replacement writer to the same work. A persistent workspace and recorded conversation support resuming interrupted work. A replacement process still needs to inspect what was saved: issue context, local changes, commits, checks and any delivery already attempted. Persistence does not imply that every process or model context continues unchanged. ## Finish against the issue's acceptance For a fully managed application change, the evidence chain normally includes the reviewed diff, required checks, publication/deployment status and a bounded application request at the intended revision. Redgold operates those delivery steps within the configured approval policy; the customer evaluates whether the result meets the objective. For work on an externally hosted repository, completion follows that repository's agreed scope and CI/release process. Record that boundary explicitly instead of reporting an external merge as a Redgold-managed deployment. Continue with [supervision and recovery](/fleet/supervision) for deciding what to do when these stages stop advancing. --- # Supervision and recovery Source: https://docs.redgold.ai/fleet/supervision Supervise a fleet by following outcomes and evidence. Begin with the workstream: which issues are eligible, assigned, blocked or finished, and which application changes have reached users? Then inspect the run responsible for a particular issue. The managed environment supplies execution capacity and infrastructure; your intervention should resolve scope, access or acceptance decisions. ## Ask for a useful status A useful report names the workstream and issue, current assignment, last verified result, blocker and next action. It distinguishes active work from queued work and identifies stale or unavailable observations. A quiet terminal is not proof that a task is stuck, and a live process is not proof of progress. Use the signed-in agent view and conversation/tool history available to your account. Fleet-wide scheduling and lifecycle inspection depend on the managed environment provisioned during onboarding. The [CLI assistance guide](/applications/ai-agents/agent-cli-assistance) covers the authorized managed CLI path; access to one assigned slot does not grant fleet administration. ## Intervene at the failing boundary | Observation | Next action | Evidence of recovery | |---|---|---| | Issue never starts | Check dependencies, workstream approval/pause and assigned capacity | A current assignment and observed startup | | Startup accepted but no session ready | Report the command id and assigned slot through managed support | Session readiness | | Agent needs a decision | Answer the specific question and update issue scope | Agent continues with the recorded decision | | Two agents change the same files | Stop or redirect one assignment and choose an integration owner | One coherent diff with combined checks | | A test repeatedly fails | Inspect the actual failure and changed behavior before rerunning | Relevant test passes on the corrected revision | | Session ends during implementation | Recover the existing workspace and last recorded result | Saved changes inspected and a clear continuation | | Merge succeeds but app serves old behavior | Follow managed publication and deployed revision | Intended revision plus a matching smoke response | | External connection fails | Check that integration's account permissions and service response | A successful authorized operation | ## Example: the change merged, but the old behavior remains Suppose a duplicate-handling fix passed its tests, yet the support app still creates two queue entries. Keep the issue open while you establish which revision is serving. If publication or rollout has not completed, Redgold recovers that stage. If the intended revision is live, capture a sanitized reproduction and inspect application behavior and data assumptions. Repeating implementation before checking the revision can create another fix for code that has not run yet. Repeating a write before checking its result can also create more duplicates. Use the smallest authorized read to establish state. ## Review the intervention too Record the decision or recovery action on the issue, including the affected revision and new verification result. A cancelled task needs a reason and a review of dependent work. An active run needs explicit interruption if it should stop; pausing its workstream only prevents new dispatches. See [the application workstream example](/fleet/application-workstream) for how these decisions fit into a complete managed delivery. --- # An application workstream from request to delivery Source: https://docs.redgold.ai/fleet/application-workstream This illustrative workstream extends the [support-triage application](/intro/pipeline-app-walkthrough). It shows how to organize a real change once the application and environment have been onboarded. The issue names and evidence below are a proposed acceptance plan, not a recorded production run. ## Objective > When our helpdesk retries a support submission, keep one queue record and > preserve its original urgency. Ship the change to our managed application and > verify it with a duplicate submission. Redgold continues to operate the route, executor, datasets and deployment. The helpdesk is an external integration: its retry behavior and granted connection are inputs to the application contract. ## 1. Agree the contract and record the work Create a workstream for reliable support intake. Its root records the managed application, environment, intended result and integration boundary. Split it into reviewable issues: | Issue | Acceptance | Depends on | |---|---|---| | Define duplicate semantics | Decide how request id, changed body and urgency interact | Customer decision | | Implement duplicate handling | Focused tests prove one logical queue entry and preserved urgency | Agreed contract | | Prepare acceptance requests | First submit, identical retry and changed-body retry have explicit expected results | Agreed contract | | Deliver and verify | Reviewed revision is deployed and the acceptance requests match | Implementation and fixtures | The workstream can hold these issues while proposed. Human approval and the managed scheduler's eligibility rules govern automatic dispatch. ## 2. Resolve a blocked decision The implementing agent discovers that the helpdesk may resend the same id with an edited body. Overwriting the original could change priority; ignoring the edit could hide new information. It records that question on the issue instead of silently choosing product behavior. For this example, the customer chooses: identical retries return the existing record, and a changed body under the same id is rejected. The decision becomes part of acceptance. The agent can now continue against an explicit contract. ## 3. Run independent work and integrate One agent owns the schema/transform change. Another can prepare acceptance fixtures from the agreed behavior without editing the implementation files. The coordinating run brings the results into one reviewed change and checks that the fixtures actually exercise the implementation. If the implementation session restarts, recover its workspace diff, issue comments and last test result before continuing. The new session should not create a second implementation because the original terminal disappeared. ## 4. Review and release through the managed path Review the behavior change, compatibility with stored records and focused test output. Redgold validates and publishes the approved artifacts and reconciles the deployment for the managed environment. An approved diff, passing check and live revision are separate pieces of evidence. The customer does not need to provision a queue database, run executor pods or edit deployment manifests to complete this workflow. The onboarding agreement identifies the application's delivery/status surface and approval policy. ## 5. Verify the result and close the loop Run the application's committed acceptance requests with an authorized test record. Record the actual result next to these expectations: | Action | Expected result for the agreed contract | |---|---| | Submit an urgent request with a new id | One accepted high-priority queue record | | Repeat the identical request | Existing logical record; no duplicate queue entry | | Reuse the id with changed body | Documented rejection; original record preserved | | Read the test record in its authorized scope | Original urgency and content remain | Attach the revision, required check results, managed deployment evidence and sanitized smoke results to the delivery issue. If the running revision differs, recover deployment before diagnosing the transform. Close the workstream only when its objective is met and any residual work is explicitly accounted for. The same organization supports an external app repository. In that case, replace the managed publication stage with the connected repository's own release process and identify who verifies its hosting. Continue with [managed deployment](/infrastructure/deployment) for the Redgold application path. --- # Connect your existing agent Source: https://docs.redgold.ai/users/install/agent-tools Use Redgold tools from your existing agent and repository. You can add one service at a time while keeping your model provider and delivery workflow. Search, browsers, memory, agent pods and builders have separate permissions; installing a client does not enable every service. ## Choose a connection | Connection | Best for | What it adds | |---|---|---| | [Setup prompt](#ask-your-agent-to-set-up-the-tools) | An existing agent that can inspect and install local tools | `redgold`, `rac`, `rci` and reusable skills | | [Hosted MCP](#connect-through-mcp) | An MCP client using remote API tools | API discovery and calls, data and reviewed pipelines; no local binaries | | [Terminal installation](/cookbook/install-client) | Installing the tools yourself | The same binaries, with explicit platform and update instructions | The [RAC command guide](/reference/rac) covers the current commands and the access each workflow needs. These connections also work alongside the [hosted website](/intro/quickstart#1-use-the-website). ## Ask your agent to set up the tools Copy the current [setup prompt](https://redgold.ai/agent-setup.txt) from the [splash page](https://redgold.ai/splash#agent-setup) into your agent. It points to the reviewed [setup skill](https://redgold.ai/skill.md). The [agent documentation index](https://redgold.ai/llms.txt) links the related guides and skills. The prompt contains no credentials. Before running it, make an existing account API key available through your secret manager as `REDGOLD_API_KEY`. If you need an account, start with [account access](https://redgold.ai/signup), then create a key in [Settings → API Keys](https://redgold.ai/settings/api-keys). Keep its value out of the conversation and repository. Search and browser operations need their respective service permissions and Billing credit; model API access alone does not establish either. The setup skill asks the agent to inspect the installer, install the tools, preserve existing instructions and model settings, and report versions and remaining access requirements. Search verification starts with a quote that executes no provider work. An actual search needs an authorized tier price; remote builds need the project's provisioned endpoint and credentials. ### Keep the skills available across sessions The installer supplies the binaries. Install the reusable instructions into the skill directory your agent uses. Inspect the inventory first: ```sh rac skills list --scope all --json rac skills show redgold ``` For Codex user skills: ```sh rac skills install redgold --target "$HOME/.agents/skills" rac skills install rac-research --target "$HOME/.agents/skills" rac skills install rac-build --target "$HOME/.agents/skills" ``` For Claude Code personal skills: ```sh rac skills install redgold --target "$HOME/.claude/skills" rac skills install rac-research --target "$HOME/.claude/skills" rac skills install rac-build --target "$HOME/.claude/skills" ``` Honor an existing custom skill directory. Repository-scoped skills can use `.agents/skills` or `.claude/skills`. Compare locally edited instructions before using `--overwrite`. If your release does not bundle a skill yet, the setup skill links to its public Markdown. Reconnect or start a new agent session if the new skills do not appear. ## Connect through MCP Add a Streamable HTTP server at `https://api.redgold.ai/api/mcp`, authenticated with your account API key. The [MCP reference](/reference/mcp) has Claude Code and Codex configuration, workspace selection and the complete tool list. Begin with `api_search`, then `api_describe` on a returned operation identifier. Discovery performs no build, purchase or data write. `api_call` forwards an authorized request to that declared operation. Data tools have their own prepare, quote, run and status workflow. MCP exposes remote API operations. Local checkout uploads, interactive terminals and filesystem commands still need their native client, such as `rac cargo` or `rac pnpm`. API discovery does not provision a builder or agent pod. The MCP connection also leaves your existing model provider settings in place; [using Redgold as a model provider](/intro/quickstart#use-the-api-with-coding-agents) is a separate option. ## Add the service your task needs | Service | Workflow | Required access | |---|---|---| | Agent search | Quote a Quick, Standard or Deep search, then execute within the authorized price | Web-search permission and Billing credit, or a centrally funded grant | | Managed browser | Quote a hosted session, choose routing, interact and retain results | Browser-session permission and a spending cap; residential routing and CAPTCHA assistance depend on the configured service | | Memory and conversation search | Discover enabled memory backends, save durable facts and recover earlier decisions | An authenticated, configured memory backend or accessible conversation index | | Managed agent compute | Work in persistent Kubernetes workspaces and inspect assigned sessions | A provisioned environment and corresponding agent permissions | | Remote CI, builds and tests | Submit finite Cargo or pnpm work and retrieve outputs | The project's approved builder endpoint, credentials and budget | The [command guide](/reference/rac) includes quotes, replay rules and examples. For managed pods, continue with [coding agents](/applications/ai-agents/overview) and [agent operations](/fleet/overview). A persistent workspace preserves files; it does not keep every terminal process running through a restart. ## Check and maintain the connection Record `rac version --json`, `redgold --version` and `rci --version`, the skill locations, and the result for each service you configured. A working MCP discovery request or installer download does not verify search, persistence or build execution. Report an unavailable service as remaining setup. To update, inspect and rerun the official installer using the existing key, then compare and reinstall the selected skills. See [installation troubleshooting](/cookbook/install-client#when-it-breaks) for platform requirements and common access errors. The documentation's [public index](https://docs.redgold.ai/llms.txt) and [full Markdown](https://docs.redgold.ai/llms-full.txt) are also available to agents. --- # Architecture Source: https://docs.redgold.ai/infrastructure/overview Redgold brings application authoring and operation into one managed platform. Describe the behavior you need, review the proposed application change, and use the deployed result. Redgold operates the routing, execution, typed storage, builds, and deployment behind it. Persistent agents help create and maintain the application; issues and workstreams keep that work connected to an outcome. Fully managed describes who operates the infrastructure. Pipeline applications are currently a managed preview: account setup, datasets, application publication, and environment provisioning are coordinated during onboarding. ## Two connected paths An application has a delivery path that changes its behavior and a request path that serves its users. An agent finishing a task changes neither the live route nor the stored data by itself; the reviewed change must pass through publication and deployment. ```mermaid flowchart TB Goal[Application objective] --> Work[Workstream and issues] Work --> Agent[Managed agent workspace] Agent --> Git[Reviewed schemas, pipelines, transforms and tests] Git --> Release[Managed build and publication] Release --> Runtime[Deployed application revision] User[App user or API client] --> Edge[Authenticated edge] Edge --> Executor[Pipeline executor] Runtime --> Executor Executor --> Data[Data engine and typed storage] Executor --> Integration[Authorized external services] ``` ## The application contract The durable application definition lives in Git. Rust serde schemas describe records; pipeline TOML describes routes and execution stages; transforms supply domain behavior; tests and example requests define the expected result. Managed publication validates these artifacts together and deploys the supported runtime configuration. The [support-triage walkthrough](/intro/pipeline-app-walkthrough) shows this contract in code. | Area | Your application decision | Redgold's managed responsibility | |---|---|---| | Behavior | What requests mean and which outcomes are correct | Execute the reviewed pipeline and transform | | Data | Record shape, identity, access requirements | Provision datasets and operate storage and scoped access | | Delivery | Scope, acceptance criteria and required approval | Build, validate, publish and reconcile deployment | | Agent work | Objectives, priorities and review feedback | Provide workspaces, tools, session history and assigned capacity | | Integrations | Which external repository or service to connect | Use the configured connection within its granted permissions | ## Read the architecture through an event - [A request through the platform](/infrastructure/request-path) follows a support request from authentication to a stored queue record, including failure points. - [Agent work and durable state](/infrastructure/agent-work) follows an application change through issues, execution, review and recovery. - [Managed deployment](/infrastructure/deployment) explains how approved source becomes a live revision and what counts as verification. - [Running agent work](/fleet/overview) explains the customer workflow for issues, workstreams, fleet supervision and lifecycle decisions. ## Why these boundaries exist The edge authenticates and relays requests; application code runs in executors. This keeps route handling separate from the compute that can fail or need more capacity. The data engine owns durable writes and scoped reads, so an application uses the managed data boundary instead of operating a separate storage stack. Git records intended application changes; runtime evidence tells you what is actually serving. Keeping both is essential when a build passes but a rollout has not reached the expected revision. Shared infrastructure also means applications follow explicit schema, capability, and publication contracts. A new external dependency or runtime requirement may need onboarding work. The [runtime placement guide](/develop/pipeline-apps/overview#runtime-placement) describes which execution choices are available and which remain previews. ## External systems fit around the managed application A managed pipeline application can integrate with authorized external services and data sources. Agents can also work on an external repository whose CI and hosting stay elsewhere. The model API can be used independently by existing applications. These connections do not automatically move external deployment, storage, or access policy under Redgold management. See [GitHub repository automation](/applications/ai-agents/github-app-automation), and the [model API](/reference/llm-api) for their supported boundaries. ## Current capability matrix Status verified 2026-08-14 against the executor conformance test and the Git-authored route inventory. | Capability | Status | Access boundary | Detail | |---|---|---|---| | `pipelines/routes//*.toml` route manifests | preview | Developer onboarding; publication is managed | [Build a vertical](/develop/build-a-vertical#6-declare-routes-in-the-pipeline-manifest) | | In-process built-in operators | available | Platform-managed operators | [Pipeline Apps runtime placement](/develop/pipeline-apps/overview#runtime-placement) | | Trusted native transforms (`NATIVE_DYLIB`) | available | Reviewed, trusted code in managed pipelines | [Pipeline Apps runtime placement](/develop/pipeline-apps/overview#runtime-placement) | | Firecracker UDF sandbox (`MICROVM`) | available | Onboarded workloads on opted-in KVM nodes | [Pipeline Apps runtime placement](/develop/pipeline-apps/overview#runtime-placement) | | Server request-handler WASM host | component preview | Feature-gated host and local fixtures; production route selection is not wired | [Pipeline Apps runtime placement](/develop/pipeline-apps/overview#runtime-placement) | | Dataflow UDF WASM tier | component preview | Default-on Wasmtime backend is implemented in the executor; capability-limited, bounded, no WASI, first route staged for publication | [Pipeline Apps runtime placement](/develop/pipeline-apps/overview#runtime-placement) | | GPU executor tier | stub | Model serving uses a separate GPU lane | [AI and agents](/infrastructure/ai) | --- # A request through the platform Source: https://docs.redgold.ai/infrastructure/request-path Consider the support-triage application in the [pipeline walkthrough](/intro/pipeline-app-walkthrough). Its illustrative route accepts a support request and returns a classified queue record. The path below explains the managed runtime behind that example; it is not a shared demo endpoint. ```mermaid sequenceDiagram participant Client as Application client participant Edge as Authenticated edge participant Executor as Pipeline executor participant Engine as Data engine Client->>Edge: Submit support request with credential Edge->>Edge: Resolve caller and route Edge->>Executor: Dispatch pipeline with verified identity Executor->>Executor: Decode and classify request Executor->>Engine: Write typed queue record with caller scope Engine-->>Executor: Write result Executor-->>Edge: Application response Edge-->>Client: Accepted record or error ``` ## 1. Resolve identity and route The edge receives the request, authenticates the caller for the route, and resolves the published pipeline. A URL alone grants no access. The caller's identity travels with the execution request so downstream data access can apply the appropriate ownership and permission checks. The pipeline manifest connects the HTTP method and path to execution stages and required capabilities. Redgold publishes this mapping as part of the managed application. You do not need to run a separate web server for each transform. See [authentication](/reference/authentication) and the [pipeline preview](/reference/pipeline-preview) for supported public contracts. ## 2. Execute application behavior The executor runs the declared pipeline. Built-in operators handle supported data operations; registered transforms supply application-specific behavior. In this example, the Rust function adds category and priority to the submitted record. The edge relays the response and runs no application handler code. A model call or external integration is an additional dependency only when the application explicitly uses it. The support example's keyword classifier does not need a model. Adding one introduces provider latency, errors and usage into the application contract; tests should cover those outcomes too. ## 3. Persist the result The data engine is the managed boundary for durable writes and scoped reads. The support request becomes a typed queue record in its provisioned dataset. Native schema values use canonical CBOR at platform boundaries; the public request and response encoding follows the particular route's API contract. Clients should not infer that every HTTP endpoint accepts CBOR. Storage combines a hot tier for recent activity with columnar storage for larger historical reads. The application works against its dataset and schema contract; Redgold operates the storage tiers. [Data and pipelines](/infrastructure/data) explains the underlying model. Record identity matters when retrying a submission. A stable request id helps an application implement duplicate handling, but does not by itself guarantee idempotence. Define and test what a second submission does before automatically retrying writes. ## 4. Return and verify A successful application response must mean what the route promises. For this example, compare the returned id, category and priority with the documented fixture, then use an authorized read if acceptance requires confirming storage. A healthy service alone does not establish that classification is correct. | Symptom | Boundary to investigate | Useful evidence | |---|---|---| | Authentication rejected | Credential and route access | Status, credential type and target environment | | Route missing after a change | Publication and deployed revision | Expected path, method and approved revision | | Invalid input or classification | Schema and transform | Sanitized request, response and focused test | | Write denied or dataset unavailable | Dataset provisioning and access | Dataset reference and caller scope | | Timeout after submission | Execution, storage or external dependency | Request timing and an authorized read before retrying | | Read returns no records | Identity, filters and stored fixture | Workspace, query bounds and record id | Bring that evidence to the managed support workflow or the originating issue. Redgold investigates service execution and rollout state; the application owner confirms intended behavior. Continue with [managed deployment](/infrastructure/deployment) for the path that changes the running implementation. --- # Agent work and durable state Source: https://docs.redgold.ai/infrastructure/agent-work Maintaining a managed application involves two kinds of state: the application's records and the work used to change its behavior. Redgold keeps issues, conversation history and delivery evidence so a change can be understood beyond one agent session. ## From objective to execution A workstream groups an application objective and its issues. An issue carries a bounded change, dependencies and acceptance criteria. An assigned agent works in a repository workspace, reads the relevant context, edits the application contract and records verification evidence. Fleet capacity and scheduling policy determine when eligible work can start. ```mermaid flowchart LR Work[Workstream objective] --> Issue[Issue and acceptance criteria] Issue --> Run[Assigned agent run] Run --> Workspace[Repository workspace] Run --> History[Conversation and tool history] Workspace --> Review[Diff and checks] Review --> Delivery[Managed publication and verification] Delivery --> Issue ``` The agent runtime and the application runtime serve different purposes. An agent workspace is where a change is authored. The deployed pipeline executor serves application requests. Closing an authoring session is not an application shutdown; starting an agent is not an application deployment. ## What survives, and where | State | Durable record or boundary | Recovery implication | |---|---|---| | Objective and acceptance | Workstream, issue and comments | Another run can recover the task's purpose | | Source changes | Workspace checkout and Git commits | Inspect local edits and the recorded revision before continuing | | Conversation and tool activity | Persisted session history | Recover prior evidence; do not assume identical model replay | | Current process | Agent runtime | A restarted process may need a fresh session and context | | Intended release | Reviewed Git change and published artifacts | Identify what was approved | | Running release | Deployment and verification evidence | Confirm what actually reached users | | Application data | Managed datasets | Independent of the authoring session's lifetime | Persistent workspace storage supports continuity across sessions. It does not make every terminal process or in-memory context durable. Before recovering an interrupted run, inspect the issue, workspace diff, commit and latest check result. Avoid starting a second writer while the original assignment may still be active. ## Coordination and authority A proposed workstream can hold issues before its human approval. Automatic scheduling checks the workstream root's approval and pause policy, together with issue eligibility and capacity. Adding an issue does not prove it was dispatched; a dispatch acknowledgement does not prove the agent has started. Application permissions, repository permissions and approval decisions remain separate from task instructions. A prompt to connect an external system cannot grant credentials or tenant access. Redgold supplies the managed execution environment; the configured account policy determines which actions it may take. ## Recovery follows the last verified boundary If tests failed, resume from the failure and changed files. If a change merged but publication failed, recover delivery for the approved revision. If deployment succeeded but the smoke request failed, investigate the running contract and application data. Repeating the whole task can create duplicate edits or writes. For externally hosted repositories, the same work records can lead to an external pull request and that repository's checks. Its hosting and release policy remain with the configured external system. See [agent lifecycle](/fleet/agent-lifecycle) and [supervision and recovery](/fleet/supervision) for the customer workflow. --- # Data and pipelines Source: https://docs.redgold.ai/infrastructure/data The platform data layer is the runtime foundation for pipeline applications. It stores typed application records, executes declared transforms, and keeps agent activity available as a supporting dataset for authoring, history, and operational review. ## Datasets A dataset is a named collection of typed records. Records retain source and ingestion metadata so callers can distinguish when an event occurred from when the platform received it. Hot query paths use Postgres-backed services, while larger analytical collections can use columnar storage. ## Pipelines Pipelines describe how records enter the platform, how transforms run, and how a result is returned or stored. The platform uses these contracts for product features as well as application-specific work. ## Agent history Conversations, messages, tool activity, usage, and lifecycle events can be stored as structured records alongside application data. This makes a session inspectable and queryable while agents help author and operate pipeline applications. It does not make model generation deterministic; a reproducible evaluation also needs pinned code, data, model, and configuration. ## Public availability The data engine and pipeline system are active parts of the hosted platform. Their broad generic execution and authoring interfaces are still under development as external contracts, so they are excluded from the public API inventory. Supported endpoints will appear in the [generated public API reference](/reference/routes/v1) only after they have reviewed schemas, examples, and compatibility expectations. --- # AI and agents Source: https://docs.redgold.ai/infrastructure/ai Redgold provides managed coding-agent sessions, an HTTP model API and tools for agents running in an existing workflow. Agents can author pipeline applications or work in repositories deployed elsewhere. Search, browsers, memory and remote builds can be adopted individually with their corresponding permissions. ## Tools for an existing agent The [setup guide](/users/install/agent-tools) connects an existing agent through a prompt, hosted MCP or local CLI installation. `rac` supplies search, browser, memory, data and build commands; `rci` implements its CI and publication families. The [command guide](/reference/rac) covers current usage and access. Hosted MCP exposes declared API operations and data tools. Filesystem uploads, interactive terminals and local checkout operations still need the native client. Tool setup preserves the agent's model provider; configuring the model API below is a separate choice. ## Coding agents A coding agent runs in an isolated workspace associated with a repository and conversation. The workspace provides the filesystem and allowed tools. Session history lets users inspect messages and tool activity and continue work later. Agents can delegate independent subtasks to additional agents when a problem benefits from parallel investigation. Each child has a bounded assignment, and its result returns to the parent conversation. ## Model API and routing The model API accepts supported OpenAI and Anthropic request formats at `https://api.redgold.ai/v1`. Callers authenticate with an account token or `sk-rg-` key. `/v1/models` reports the identifiers available to the current account. Model routing handles platform authentication, metering, and backend selection. Provider errors and rate limits can still reach the caller; clients should honor `Retry-After` and use bounded exponential backoff where appropriate. ## One-shot application benchmark The repository includes a paired full-application benchmark under `crates/ai/benchmark/oneshots/`. Its habit-tracker task gives Codex, Claude, and the Redgold Fusion runtime the same prompt and verifier in fresh workspaces, with explicit time, step, token, and USD caps. The companion `report.py` keeps pass@1, artifacts, and observed cost comparable without guessing a provider price; paid sweeps remain operator-authorized. ## Persistence and replay Persisted messages and tool events support review, search, and context reconstruction. A replay can differ when model weights, sampling, tools, external APIs, repository state, or datasets differ. Treat a run as reproducible only when those inputs are pinned. Continue with the [coding agents guide](/applications/ai-agents/overview) or [LLM API reference](/reference/llm-api). --- # Managed deployment Source: https://docs.redgold.ai/infrastructure/deployment Redgold operates the build, publication and deployment path for your managed application. You define the expected behavior and review the change under your account's approval policy. The platform carries the approved schema, pipeline, transform and supporting artifacts into the managed runtime. Application and environment provisioning are coordinated during onboarding. Fully managed deployment does not require the customer to operate Kubernetes, a registry or a deployment controller. The configured repository, environment, domain and status surface identify where the application is delivered. ## From source to a running revision ```mermaid flowchart LR Change[Reviewed application change] --> Checks[Required checks] Checks --> Publish[Versioned artifacts and route publication] Publish --> Desired[Git-backed desired deployment state] Desired --> Reconcile[Managed runtime reconciliation] Reconcile --> Verify[Revision and application smoke check] ``` | Boundary | What happens | What the result establishes | |---|---|---| | Review | Evaluate schemas, pipelines, transforms and tests together | The application behavior is approved | | Checks | Validate the affected contract and implementation | The checked revision passed the required checks | | Publication | Publish the affected versioned artifacts and route definitions | The runtime can obtain the approved artifacts | | Desired state | Generate deployment configuration in Git | The intended environment revision is recorded | | Reconciliation | Deployment controllers apply that desired state | The runtime is converging on the requested revision | | Verification | Inspect revision and exercise the application | The intended behavior reached the target environment | Underlying service builds publish container images; pipeline and transform publication follows the affected artifact path. A pipeline edit does not imply a new standalone service for that application. Kubernetes and ArgoCD provide the managed reconciliation layer, while the customer works with the application contract and its delivery evidence. ## Verify behavior as well as health For the support-triage example, a healthy rollout is only the first check. Send the committed support-request fixture and compare its returned category and priority with the expected values. If the change concerns persistence or retry behavior, include an authorized read or duplicate-submission check. Keep the approved revision, required check results, deployed revision and smoke result together on the delivery issue. A merged pull request alone does not prove the application was published. A successful health check alone does not prove the new business behavior is correct. ## Recover at the failed stage If checks fail, correct and re-review the source change. If publication or reconciliation fails, Redgold investigates that stage using the intended revision. If the expected revision is live but acceptance fails, capture the smallest sanitized reproduction and review the application contract. A rollback also needs compatibility review: reverting code does not automatically undo stored records or external effects. Keep schema evolution and application retry semantics explicit so recovery preserves the intended data behavior. The [supervision guide](/fleet/supervision) describes the corresponding issue and agent decisions. ## External repositories and services Agents can work on external repositories with their existing CI and deployment systems. Those releases follow the external repository's policy unless managed Redgold deployment was explicitly configured. A managed application can also call an authorized external service; publishing the application does not deploy or manage that service itself. Follow [the application workstream](/fleet/application-workstream) for the full customer workflow, or [verify a managed deployment](/cookbook/verify-managed-deploy) for the delivery checklist. ## Local evaluation sandbox To evaluate the request path on a single machine without the cluster, there is a docker-compose sandbox at `resources/self/selfhost/compose/`. It runs the minimal path — postgres, the engine (data-engine-service), the dynamic-transport-service edge, and the dataflow-executor — from the same images CI publishes, resolving credentials from a local `.env`. This is the sanctioned local exception to the GitOps-only deploy path: a generated compose artifact for a desktop or laptop, not a cluster deployment. It is for evaluating the request path, not parity — there is no ArgoCD, secret manager, cold-tier storage, observability, or identity provider in the sandbox. Bring it up with `./smoke.sh` (bounded, self-terminating) and see that directory's `README.md` for the quickstart, the manual smoke recipe, and what is degraded versus a cluster deployment. --- # Authentication Source: https://docs.redgold.ai/reference/authentication Interactive Redgold clients use an account session. API clients use an `sk-rg-` key. Both credentials are sent as bearer tokens, but their lifecycle differs. ## API keys Create a key from the API-key page in the signed-in web application. The complete value is shown once. Store it in a secret manager or environment variable and revoke it when it is no longer needed. ```bash export REDGOLD_API_KEY=sk-rg-... curl https://api.redgold.ai/v1/models \ -H "Authorization: Bearer $REDGOLD_API_KEY" ``` Send the key in the `Authorization: Bearer` header. The model API reads the credential only from that header (and, for the signed-in web application, the session cookie); it does not read an `X-Api-Key` header, so a request that supplies the key only as `X-Api-Key` is rejected with `401`. ### CLI credential file `rac`, `rci`, and `rdg` can read a key from `~/.redgold/credentials.toml`: ```toml api_key = "sk-rg-..." ``` A nonempty `REDGOLD_API_KEY` environment variable takes precedence. When it is unset or blank, the CLI loads the file key into its process environment so delegated commands use it too. Missing files and missing or blank `api_key` values leave the existing authentication fallbacks available. An unreadable or invalid file produces an error without printing its contents. Keep this file private (`chmod 600 ~/.redgold/credentials.toml` on Unix). Install scripts and other API clients still require their documented credentials. ### XMPP with the same API key `rac xmpp install` installs the private Slixmpp environment. Bind the key to your workspace with `rac xmpp connect --workspace `, then run `rac xmpp check` to verify the connection. The returned JID identifies this key and workspace. Use `--server ` for a different API realm. Cloud runtimes that require an HTTP proxy can use XMPP over HTTPS BOSH: ```bash rac xmpp connect --workspace --transport bosh rac xmpp check ``` The transport choice is saved with the connection. The default `auto` selects BOSH when an HTTPS proxy or BOSH-only proxy applies; `NO_PROXY` is respected. Otherwise it uses direct TLS. An explicit `--transport direct` or `--transport bosh` overrides the saved choice for an operation. Supply your runtime's approved HTTPS proxy configuration and trusted CA configuration through its normal environment. TLS verification is required, and credential-bearing redirects are refused. When the identity API and BOSH endpoint need different approved proxies, keep the normal proxy environment for the API and set `RAC_XMPP_BOSH_PROXY` to the BOSH endpoint's HTTP CONNECT proxy. The equivalent per-command option is `--bosh-proxy `. This override affects only BOSH; `NO_PROXY` and trusted CA configuration still apply. Proxy settings remain runtime configuration and are not saved by `connect`. Use `--server` for the HTTPS API origin reachable through the API proxy, and verify the returned JID/workspace. `rac xmpp send` returns a stable stanza ID and reports `submitted` until a peer receipt confirms `delivered`. `rac xmpp receive` reads durable archive history; retain its cursor after handling a page. Both transports use the same identity and archive. `rac xmpp disconnect` disables only the XMPP grant; the account API key continues to work for other commands. ## Account sessions The web application establishes an account session during sign-in and uses it for interactive requests. Treat the session as a user credential. Do not copy it into source code or use it as a long-lived CI secret. Some account-management operations, including minting a new API key, require an account session and do not accept an existing API key as authority to create another key. ## Credential handling - Keep keys out of repositories, prompts, logs, and screenshots. - Give each automation context its own key so it can be revoked independently. - Use the lowest practical request limit for unattended clients. - Replace a key if its value may have been exposed. ## Authentication failures A missing, malformed, revoked, or unknown key returns `401`. An account out of model-API credits returns `402`. On the data API a valid identity without permission for an operation returns `403`; the model endpoints do not emit `403`. Model endpoints return the error envelope matching their OpenAI or Anthropic request shape. Continue with the [LLM API](/reference/llm-api) or [errors](/reference/errors). --- # Security disclosure policy Source: https://docs.redgold.ai/reference/security-disclosure Redgold runs tenant data on shared infrastructure, so we take security reports seriously and want to make responsible disclosure easy. This page is the canonical disclosure policy referenced by our [`/.well-known/security.txt`](https://redgold.ai/.well-known/security.txt). ## Reporting a vulnerability Email **security@redgold.ai** with a description of the issue, the affected endpoint or component, and enough detail to reproduce it. A proof-of-concept or minimal reproduction helps us triage quickly. English is preferred. Please do not open a public issue, post to a forum, or disclose the problem publicly until we have had a chance to investigate and remediate. ## Scope In scope is anything under the Redgold platform: the public API surface (`api.redgold.ai`, `/v1/*` and `/api/*`), the web application, the docs site, and the agent and data-pipeline services behind them. Out of scope: reports that require physical access to a user's device, social engineering of Redgold staff or users, denial-of-service or volumetric testing, spam or content-injection findings with no security impact, and issues in third-party services we depend on (report those to the respective vendor). ## Safe harbor We will not pursue or support legal action against researchers who act in good faith, follow this policy, avoid privacy violations and service degradation, and give us a reasonable opportunity to remediate before any disclosure. If in doubt about whether an action is authorized, ask first at security@redgold.ai. ## What to expect We aim to acknowledge a report within **three business days** and to provide an initial assessment shortly after. We will keep you updated as we work toward a fix and will let you know when the issue is resolved. We do not currently run a paid bug-bounty program; this policy covers coordinated disclosure only. --- # RAC command guide Source: https://docs.redgold.ai/reference/rac `rac` is the Redgold agent CLI. Install it with the [terminal client and tools](/cookbook/install-client), or give your agent the [setup prompt](/users/install/agent-tools). `redgold` provides the terminal conversation interface. The sibling `rci` implements CI and publication commands reached through `rac ci`, `rac leg` and related families. Commands are available according to the selected service, caller and workspace. An account API key does not grant fleet administration or access to arbitrary repositories, datasets or builders. The examples below assume the corresponding service is configured. ## Discover current syntax ```sh rac version --json rac --help rac search --help rac skills install --help ``` Use the installed command's scoped help for flags. The complete operational index is generated from the Rust command definitions in the repository; this public guide selects workflows useful to customers and their agents. ## Search the web Search uses fixed-price tiers with a preset provider mix and server-side Luna ranking and source-grounded features: | Tier | Price per search | |---|---| | `quick` | USD 0.01 | | `standard` | USD 0.05 | | `deep` (default) | USD 0.10 | Start with a quote, which executes no provider work and reserves no credit: ```sh rac search 'Rust official documentation' --tier quick --max 3 --quote ``` After the selected price is authorized, omit `--quote` to execute. Set a stable `RAC_WEB_TOOL_REQUEST_ID` for that request and preserve the same query, tier, filters and ID after an interrupted response. Changing the request requires a new ID. A quote is not a search result. Use `--site`, `--exclude-site`, `--start` and `--end` to narrow results, and `--json` to inspect `provider_statuses`, enrichment and the billing receipt. Partial provider failures and degraded enrichment are reported separately; fetch the relevant sources before relying on their contents. The former `--mode`, `--provider`, `--self-hosted-only` and custom search-budget flags are retired. A free-only task must not be converted into a paid tier request. Search defaults to the public API. `AC_SEARCH_API_BASE` explicitly selects a different installation; its permissions, funding and available tiers can differ. Search and browser Billing credit is separate from model-API credit. ## Fetch and browse pages `rac fetch '' --json` retrieves a page over HTTP. `rac browse` renders pages through Camoufox and returns readable text, with JSON, HTML and screenshot options. For an account with hosted-browser access, inspect a bounded quote: ```sh rac browse https://example.org --api-base https://api.redgold.ai \ --max-cost-usd 0.05 --quote ``` Execute only within the authorized cap. Hosted sessions meter traffic and have lifetime limits. Residential egress is explicit; managed environments with the required proxy configuration can select `--egress oxylabs --geo us`. Direct requests never automatically switch to a paid proxy. For interaction, `rac pw --help` describes isolated browser profiles, navigation, snapshots and the existing CAPTCHA solver. Managed Camoufox sessions and local `rac pw` profiles have separate setup. CAPTCHA assistance is bounded and can still require a person. Inspect returned page text; an HTTP 200 or a CAPTCHA script in the HTML alone does not establish useful retrieval. ## Remember decisions and find earlier work ```sh rac memory backends rac memory search 'release decision' --limit 5 rac search 'release decision' --memories --max 5 rac search 'release decision' --conversations --since 7d --max 5 ``` Memory searches federate across enabled backends and return source provenance. `--backend` selects a system; `rac memory add --help` describes saving a durable fact. `rac memory system --help` covers repository and skill indexing, capture and retrieval evaluation. Each backend needs its own configured identity and access. Inspect partial errors before treating a search as complete. `rac conv list`, `rac conv search` and `rac conv archive-search` inspect accessible conversation summaries, content and imported archives. Conversation and memory queries stay on their internal retrieval paths and never go to web providers. They do not use web-search tier pricing. Avoid storing credentials or copying private conversation content into public research. ## Run remote builds, checks and tests Use the project's provisioned builder endpoint and credential. An installed CLI or search key does not provision build capacity. External Cargo workspaces require a builder that supports source-tree uploads: ```sh rac cargo --source-tree check -p my-crate rac cargo --source-tree test -p my-crate ``` For a configured pnpm builder, run from the package directory: ```sh rac pnpm --remote "$PROJECT_PNPM_BUILDER_URL" --timeout-secs 900 run build ``` `PROJECT_PNPM_BUILDER_URL` is an example project setting. Read the [remote build skill](https://redgold.ai/skills/rac-build/SKILL.md) for `RAC_CARGO_SOURCE_TREE_REMOTE`, credential configuration and repeatable `--fetch ` output retrieval. Uploads include uncommitted source; review the upload scope first. Commands must terminate; watchers and development servers do not belong on these build routes. Retain the returned request identifier and exit status. `rac out read` and `rac out grep` recover full retained output without repeating a build. Configured repository CI uses `rac ci` and `rac leg` through `rci`; publication and deployment follow that project's release policy. ## Data and installed applications | Task | Commands | Boundary | |---|---|---| | Inspect datasets and sample rows | `rac dataset list`, `describe`, `head`, `rows`, `indexes` | Configured engine access and dataset permissions | | Compare data or historical snapshots | `rac dataset diff --help` | Bounded owner-scoped reads; no repair or writes | | Import JSONL or Parquet | `rac des import --help` | Existing declared schema and authorized write access; [import guide](/develop/import-your-data) | | Discover an installed app | `rac app list`, `describe`, `docs` | Selected installation and workspace | | Inspect or invoke an installed operation | `rac app --help` | The app's declared actions, permissions and spending rules | MCP clients can use the [hosted API and data tools](/reference/mcp) for declared remote operations. Local CLI command names are not MCP tool names. ## Other recent command families | Workflow | Start here | Access and behavior | |---|---|---| | Reusable instructions | `rac skills list`, `show`, `install` | Inventories repository, bundled and installed skills; differing local files need explicit overwrite | | Platform help and bug reports | `rac support --help` | Caller-owned reports; supports `--dry-run`, saved requests and bounded status reads | | External website signup | `rac site catalog`, `template`, `status` | Requires an authorized scoped identity, mailbox and provider setup; retains submission and recovery state | | Private bank history | `rac banking --help` | Plaid connection in the selected workspace; the account owner completes bank authorization | | Privacy.com card proposals | `rac privacy status`, `list`, `get`, `request` | Connected account; a request creates an owner-review proposal and requires owner approval before card creation | | Managed compute and diagnostics | `rac fleet status`, `rac fleet health`, `rac agent --help` | Assigned environment and fleet permissions | | Workstream supervision | `rac workstream status`, `diagnose`, `forecast` | Provisioned workstream access; approval and pause policies continue to apply | | Usage attribution and plan limits | `rac usage --help` | Managed operator access; estimates and attribution are distinct from provider invoices | | Recover after rewritten integration history | `rac branch sync --help`, `rac pr sync --help` | A configured repository and verified task-commit boundary; preserve unfinished work first | Use [agent-cli assistance](/applications/ai-agents/agent-cli-assistance) for managed fleet workflows and [authentication](/reference/authentication) for credential configuration. A help entry describes an available command, while the service enforces permission for each operation. --- # Model API Source: https://docs.redgold.ai/reference/llm-api The public model API is served from `https://api.redgold.ai`. Every model behind it is a Redgold model. The flagship, `redgold-flint`, is a fusion model: one model interface backed by multiple expert models, with per-request routing across the experts handled inside the serving stack. `redgold-flint-base` is the same interface without the fusion routing layer. The API speaks two wire formats, so you can reach the models with whichever SDK you already use: the OpenAI-compatible surface (`/v1/chat/completions`, `/v1/responses`) and the Anthropic-compatible surface (`/v1/messages`). Both authenticate the Redgold account, meter usage, and route to an available backend. ## Discover models Model availability changes independently of client code. Query the authenticated model list and use an identifier returned for your account. ```bash curl https://api.redgold.ai/v1/models \ -H "Authorization: Bearer $REDGOLD_API_KEY" ``` The response follows the OpenAI model-list envelope: ```json { "object": "list", "data": [{ "id": "model-id", "object": "model", "owned_by": "redgold" }] } ``` The list contains identifiers for both API families. `redgold-flint` and `redgold-flint-base` use the OpenAI-compatible routes (`/v1/chat/completions`, `/v1/responses`). The remaining identifiers in your account's list are served through the Anthropic-compatible `/v1/messages` route; use one exactly as returned. Treat `/v1/models` as authoritative and read identifiers from it rather than hard-coding them — the set changes independently of client code, and an account may not see every entry. An unknown identifier, or one sent to the wrong API family, returns a model-not-found error. ## OpenAI Chat Completions Use `POST /v1/chat/completions` with the normal OpenAI message shape. Both complete JSON responses and server-sent-event streams are supported. ```python import os from openai import OpenAI client = OpenAI( base_url="https://api.redgold.ai/v1", api_key=os.environ["REDGOLD_API_KEY"], ) models = client.models.list() print([model.id for model in models.data]) response = client.chat.completions.create( model="redgold-flint", messages=[{"role": "user", "content": "Hello"}], ) print(response.choices[0].message.content) ``` For streaming, pass `stream=True` and consume the SDK iterator. ## OpenAI Responses `POST /v1/responses` accepts the OpenAI Responses shape for compatible models. Use this endpoint for clients that are built around the newer Responses API instead of Chat Completions. ```bash curl https://api.redgold.ai/v1/responses \ -H "Authorization: Bearer $REDGOLD_API_KEY" \ -H "Content-Type: application/json" \ -d '{"model":"model-id","input":"Hello"}' ``` ## Anthropic Messages The Anthropic SDK should use the host without an added `/v1` suffix because the SDK appends `/v1/messages` itself. The model API authenticates from the `Authorization: Bearer` header and does not read the `x-api-key` header the SDK sends by default, so present the key as a bearer token: ```python import os from anthropic import Anthropic client = Anthropic( base_url="https://api.redgold.ai", api_key="unused", # the model API reads Authorization, not x-api-key default_headers={"Authorization": f"Bearer {os.environ['REDGOLD_API_KEY']}"}, ) with client.messages.stream( model="model-id-from-v1-models", max_tokens=256, messages=[{"role": "user", "content": "Hello"}], ) as stream: for text in stream.text_stream: print(text, end="") ``` ## Credits `GET /v1/credits` returns the available model API credit balance for the authenticated account. ```json { "balance_micros": 1000000, "balance_usd": 1.0 } ``` ## Streaming and errors Streaming responses use server-sent events. An error before response headers returns a normal provider-shaped HTTP error. An error after a stream begins can arrive as an in-band error event. Clients should handle both cases. Upstream `429` responses can reach the caller, but the provider's `Retry-After` header is not forwarded. Honor a `Retry-After` header when one is present and otherwise apply bounded exponential backoff. See [limits](/reference/limits) and [errors](/reference/errors). The [generated public route inventory](/reference/routes/v1) lists endpoints explicitly approved for external documentation. [API contract details](/reference/api-contracts) add request, response, streaming, error, limit, compatibility, and example guidance. Reachable platform routes absent from the inventory are outside the supported public contract. --- # MCP server Source: https://docs.redgold.ai/reference/mcp Redgold exposes a hosted MCP server over Streamable HTTP. Connect once to discover API operations, read and write data, and run reviewed pipelines. Every request validates the account credential, workspace membership and current grants. Paid data work uses prepaid admission with a caller-supplied charge ceiling. This is one of the [ways to connect an existing agent](/users/install/agent-tools). The [setup prompt](/users/install/agent-tools#ask-your-agent-to-set-up-the-tools) installs local binaries and skills instead. Either path can keep the client's existing model provider. The [RAC command guide](/reference/rac) maps CLI workflows; MCP calls use the declared API operations rather than CLI commands. The free [data skill bundle](/skills/redgold-data.tar.gz) includes setup, query, transformation and hosting references plus a stdlib client. Download its [checksum](/skills/redgold-data.sha256), verify it, and extract the `redgold-data` folder into your agent's skill directory. ## Endpoint and authentication No local Redgold binary is required. In your agent's MCP settings, choose an HTTP server, enter the URL below, and configure the `Authorization` header with your account API key. Keep the key in the client's secret configuration. ```text POST https://api.redgold.ai/api/mcp Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream ``` Create a key through [authentication](/reference/authentication). Keep it in your client's secret configuration. An optional `x-redgold-tenant` selects a workspace; a workspace-bound key cannot select another workspace. Personal scope remains available when the key has no workspace binding. Operator service tokens cannot invoke this customer profile. Supported MCP versions are `2025-06-18`, `2025-03-26` and `2024-11-05`. Send `initialize`, then `notifications/initialized`, then `tools/list` or `tools/call`. Notifications receive an empty HTTP 202. Subsequent requests carry the negotiated `MCP-Protocol-Version`. Responses use JSON; this stateless profile does not require an SSE session. Requests are bounded to 256 KiB and responses to 1.5 MiB. ```bash claude mcp add --transport http redgold https://api.redgold.ai/api/mcp \ --header "Authorization: Bearer $REDGOLD_API_KEY" ``` Make `REDGOLD_API_KEY` available in your terminal before running this command; the shell expands it into the client's stored header. Treat that client configuration as a secret. Restart or reconnect your agent if it does not discover the server immediately. Ask it: “Search the Redgold API for build jobs, describe the create and status operations, and show me the required inputs.” Discovery executes no build. For Codex, add the following to `~/.codex/config.toml` and make `REDGOLD_API_KEY` available in the environment that starts Codex. The configuration refers to the variable name and does not store its value: ```toml [mcp_servers.redgold] url = "https://api.redgold.ai/api/mcp" bearer_token_env_var = "REDGOLD_API_KEY" ``` See the [official OpenAI documentation for MCP](https://developers.openai.com/codex/mcp/) for Codex's HTTP transport, environment-backed headers and connection settings. For other MCP clients, use these connection settings: | Setting | Value | |---|---| | Transport | Streamable HTTP | | URL | `https://api.redgold.ai/api/mcp` | | Header | `Authorization: Bearer ` | | Optional workspace header | `x-redgold-tenant: ` | An HTTP 401 means the key is missing or invalid. HTTP 403 means the selected account, workspace or operation is not permitted. Discovery lists declared operations for this deployment plane; it does not grant access to them. ## API tools The API directory is compiled from pipeline route manifests and the gateway's checked route inventory. Route additions become discoverable when the MCP server containing those declarations is published. It covers the declared API counterparts used by `rac` and `rci`, including forge and search operations, remote build jobs and their status operations. The public endpoint lists public routes; the separately configured operator deployment can also list internal routes. A route declaration does not prove its backing service is currently available. Internal routes that rely on network trust instead of caller authentication require their native operator transport and cannot be invoked through MCP. | Tool | Purpose | |---|---| | `api_search` | Search operations by words, method or path. Use `limit` and `offset` to page results. | | `api_describe` | Inspect an `operation_id`, path/query parameters, transport, permissions and registered native request/response schemas. | | `api_call` | Invoke that operation with path parameters, query values, a JSON or base64 body and optional idempotency or conditional headers. | For example, call `api_search` with `{"query":"build jobs"}`, then pass a returned `operation_id` to `api_describe`. Supply exactly that operation ID to `api_call`; there is no arbitrary URL or shell-command execution. Request and response schemas come from the native registry when available. A `null` schema explicitly means the declaration has no registered native schema; mined parameters may be incomplete, and the underlying API validates every request. Calls forward the caller's account and selected workspace to the ordinary API. They do not install an operator credential or bypass authorization, approvals or spending rules. Existing data tools below remain available, including their prepare/quote/run workflow. For long work, submit through an existing job API, retain its job/run identifier, then use its status/results operations. The MCP adapter does not turn a synchronous endpoint into a durable job. Calls have one deadline of 1–120 seconds (30 by default) and a 1.5 MiB response bound. A timeout, interrupted response or oversized result can leave a mutation's outcome unknown. Reconcile through its status API and stable idempotency key before retrying; the adapter never automatically retries mutations. Forwarded response metadata includes HTTP status, content type, `location`, `retry-after` and `etag` when present. Responses identify `body_encoding` as `json`, `text` or `base64`; binary bytes are preserved as base64. Large downloads need a smaller `range` header or the native download API. For binary uploads, send `body_base64` with `content_type` instead of `body`. Wildcard-method operations require an explicit `method`; a fixed method cannot be overridden. Only declared prefix operations accept `path_suffix`. SSE reads return a bounded text window with `complete: false` if the upstream stream is still open at the deadline. Such a window can end mid-event; it is not proof that the underlying operation completed. Use the native streaming client for continuous subscriptions. The `last-event-id` header is accepted for APIs that support resumption; the adapter does not invent a cursor or replay calls. WebSocket operations are discoverable but require their native transport. Commands that depend on a local checkout, terminal, filesystem or local credentials need a remote API equivalent or a local `rac` installation. ## Data tools `tools/list` returns JSON Schema generated from the checked-in native request types. Use it and `data_describe` for the exact input contract. | Tool | Purpose | |---|---| | `data_catalog` | Page accessible datasets, installed actions, supported recipes and hosting templates. | | `data_describe` | Inspect schema, exact revisions, allowed fields and examples. | | `data_query` | Run a bounded read with a stable idempotency key; no cache loading step. | | `data_write` | Create or update records through declared installed entity operations. | | `pipeline_prepare` | Validate a reviewed recipe or exact installed action and return effects, limits and a quote. | | `pipeline_run` | Accept the prepared plan once under a stable task key. | | `pipeline_status` | Inspect durable state, diagnostics and billing without repeating effects. | | `pipeline_results` | Read a bounded result page and committed output provenance. | | `pipeline_host` | Prepare, deploy, inspect, activate, pause, roll back or export recurring work. | Dataset names come from discovery and use the existing engine ownership and workspace policies. Shared datasets need an explicit service allowlist; existing ingested data is not automatically licensed for resale. Arbitrary code, sinks and schema registration are outside the data-tool contract. The compatibility names `list_storage_datasets`, `query_datasets`, `query_schema`, `query_data` and `load_storage_dataset` delegate to this same DES boundary. Paid query/load aliases require a stable `idempotency_key`; their returned run is inspected through status/results. No alias creates a process-local cache. Agent and infrastructure API operations, when declared for the selected deployment, use the API tools above and retain their own authorization and approval policies. ## Results and spending A tool result contains a short `content` summary and the native JSON projection in `structuredContent`. Rejected tool calls set `isError: true` and include a stable error code, retryability and a next action. Authentication failures return HTTP 401 or 403 before effects. A prepared plan binds its exact spec, schema, grant and price revisions. It expires after 15 minutes. Preparation executes no supplier calls, data writes or schedule activation. Execution reserves the quote before effects, and settles integer micro-USD (1000000 = USD 1) from durable usage. Search child receipts consume the parent reservation without a second account debit. Use the same `idempotency_key` after a lost response. Changed parameters require a new plan and key. Poll status instead of repeating supplier calls. `uncertain` retains its reservation until the original receipt can be reconciled. `complete: false` describes a partial or rejected result; a partial summary is never committed as a complete output. Result pages expire after 24 hours. Limits separately cover materialized source rows/bytes, execution time, cooperative memory enforcement, output bytes/rows, retained payload bytes, concurrency and charge. An output limit is not a scan limit. These limits do not represent physical disk-I/O caps or hard process preemption. Retained payloads currently have a quota and one-time byte charge rather than a duration-based storage charge. ## Recurring execution Hosting requires an interval and explicit daily/monthly spending allowances. Deployment performs a real paid smoke run and checks the scheduler binding, then returns `ready_paused`. `activate` is a separate requested action. Deploy, activate, pause and rollback require stable control idempotency keys. Credit exhaustion disables future admissions. A retry of rollback selects the same generation; rollback never reverses data already emitted. See [query data via MCP](/cookbook/mcp-query-data) and [run a pipeline via MCP](/cookbook/mcp-drive-agent). The distributable `redgold-data` skill includes authenticated setup, current workflows and a bounded stdlib client. Commercial listing and retail-rate approval remain separate launch steps. The reviewed `change-monitor` hosting template compares complete snapshots of an accessible dataset; partial scans preserve its prior baseline. `research-endpoint` serves bounded pages of a fixed hosted plan's latest complete committed run. Discover them with `data_catalog` kind `host_template`, inspect their native schema, and set `template` at host preparation. Consumers use `pipeline_host` action `results` or POST the same arguments to `/api/agent/data/pipeline_host` with ordinary account authentication. Responses distinguish the latest attempt from the last complete result and retain result expiry and provenance. Browser collection remains with the separately authorized browser service. --- # Data platform preview Source: https://docs.redgold.ai/reference/data-platform-preview Redgold applications store typed records in owner-scoped datasets and process them through declared pipelines. Checked-in Rust types with serde derives are the schema source. CBOR is the binary storage and HTTP encoding. ::caution{icon="i-lucide-construction"} Developer Preview features can change with migration guidance. Direct HTTP integrations are limited to routes present in the [generated API reference](/reference/routes/v1). :: ## Supported contract | Capability | Access | Stability | |---|---|---| | Query records owned by a workspace | MCP data tools and configured applications | Owner scope and bounded reads are required | | Address a typed dataset | `DatasetReference` | Field names and semantic identity are reviewed | | Address one logical record | `PrimaryKeyId` | Content identity and source time remain explicit | | Carry generic field values | `TypedValue` | Prefer a domain Rust record when the schema is known | | Author a pipeline | Git-authored TOML | The [pipeline preview](/reference/pipeline-preview) subset is supported | | Publish or deploy a pipeline | Repository automation | Managed preview | ## Data model A dataset has a stable type name and owner. Every row has a `PrimaryKeyId`. The key distinguishes ingestion time from the producer's source time, which supports late events and deterministic reprocessing. The authoritative definitions are checked in under the focused schema crates: - `redgold_primary_key::{DatasetReference, PrimaryKeyId}` - `redgold_schema_base::base::typed_value::TypedValue` - the domain record module used by the dataset adapter ## Queries and writes Queries are owner-scoped and bounded. Results may come from the hot record tier or the columnar tier; storage placement is an implementation detail. Typed writes use CBOR-encoded domain records, a deterministic primary key, and a narrow application route that validates ownership and input. General arbitrary file upload is outside the preview. Dataset onboarding defines the Rust record, source-time mapping, primary-key construction, and ingestion route together. ## Versioning and operational boundary Pin a pipeline-backed application to an exact pipeline revision when a client needs reproducible behavior. A new behavior or persisted schema requires a new reviewed revision and migration guidance; the managed installation may retain a previous compatible revision for rollback. The `latest` pointer is a registry convenience, not a client compatibility guarantee. The public V1 route inventory is the authority for self-service routes. It currently lists the model API; application routes remain onboarding/managed preview routes until their dataset, publication, and environment are approved. The public inventory has no generic pipeline-app health endpoint, so managed users should use the deployment status surface supplied during onboarding plus a bounded owner-scoped smoke request. There is no documented promise of zero-downtime migration for preview applications. ## Compatibility Released Rust schema fields evolve additively where persisted data requires it. New fields are optional or have serde defaults, retired fields receive migration guidance, and route additions require the explicit public API tag. The full internal schema and route inventory remains an implementation detail. --- # Terminal client Source: https://docs.redgold.ai/reference/cli `redgold` is the terminal interface to Redgold conversations and managed agent workspaces. The same account's sessions are available through the website. The terminal client's agent tools, approvals and transcript follow the assigned workspace's permissions. ## Install and authenticate Follow [Install the terminal client and agent tools](/cookbook/install-client). The public bootstrap uses an account API key in `REDGOLD_API_KEY`, verifies the release, and installs `redgold`, `rac` and `rci` into `~/.redgold/bin`. Installation does not provision a managed agent slot or model entitlement. Run the configured client interactively or send one headless task: ```sh redgold redgold run --prompt "run the tests" ``` `redgold --help` describes the installed release's options. The public installer selects the public API; use `--api ` or `REDGOLD_API` for an explicitly configured alternative. Model access follows the account and selected workspace; see the [installation recipe](/cookbook/install-client#choose-your-workflow) for BYOK setup and access requirements. ## Tools for your existing agent `rac` provides search, browsers, memory, data, builds and managed fleet commands. `rci` implements its CI and publication families. Read the [RAC command guide](/reference/rac) for those workflows and their access needs. The [setup prompt](/users/install/agent-tools) installs tools and skills for an existing agent while keeping its model provider. The [hosted MCP server](/reference/mcp) provides API discovery and calls without a local binary. Administrative commands require the corresponding managed environment and permissions. --- # Pipeline manifest preview Source: https://docs.redgold.ai/reference/pipeline-preview A Redgold pipeline manifest is TOML that describes a named graph of inputs, transforms, outputs, and optional HTTP entry points. CI parses the manifest, validates it, and lowers it to the signed runtime specification used by the executor. This Developer Preview covers the authoring shape used by onboarded application repositories. Publication and deployment remain managed and approval-gated. ## The three layers | Layer | Purpose | Lifetime | |---|---|---| | Dataflow | One relational query plan | One execution | | Pipeline specification | Named, versioned execution graph | Registered runtime version | | Pipeline manifest | Human-authored desired state in Git | Reviewed and regenerated by CI | Application authors normally edit the manifest. CI owns generated signatures, hashes, timestamps, and deployment state. The current pipeline content hash and author signature cover the canonical CBOR encoding of `nodes`, `output_node_ids`, and `spec_name`. `version_tag`, description, tags, `latest`, and timestamps are registry/display metadata outside that identity. Resolve an exact revision with `spec_name` and `spec_hash`. The portable `AppRelease` contract adds a separate whole-package hash and signature boundary over schemas, pipelines, surfaces, assets, capabilities, and dependencies. Local builds currently emit unsigned release candidates; registry signature verification is planned. ## Smallest useful manifest ```toml name = "ticket-summary" description = "Create a compact summary when a ticket changes." tags = ["tickets", "preview"] family = "tickets" role = "materialization" origins = ["ticket-events"] maturity = "preview" [[flow]] transform = "ticket-normalize" in = "ticket" out = "ticket_normalized" [[flow]] transform = "ticket-summarize" out = "ticket_summary" ``` Each `[[flow]]` step consumes the previous step's output. Use independent `[[nodes]]` entries for fan-out or multiple input leaves. ## Reviewed authoring subset ### Manifest fields | Field | Required | Meaning | |---|---|---| | `name` | yes | Stable manifest identifier | | `description` | recommended | Human-readable behavior shown in reviews and references | | `tags` | recommended | Search, maturity, and documentation labels | | `family` | no | Typed topology family, such as `tickets` or `conversations` | | `role` | no | Typed pipeline role, such as `route`, `ingestion`, or `materialization` | | `origins` | no | External or upstream origins represented by this pipeline | | `maturity` | no | Lifecycle label such as `preview` or `stable` | | `[[flow]]` | one graph form | Ordered transform chain | | `[[nodes]]` | one graph form | Explicit DAG nodes | | `[route]` | one graph form | Compact single HTTP-route dataflow | All four typed metadata fields are optional. Existing `family:*`, `role:*`, and `origin:*` tags remain accepted. Typed fields take precedence, and catalog inference still supplies family and role when neither form is present. Choose one of `flow`, `nodes`, or `route` in one manifest. Node identifiers must be unique after lowering. ### Transform node fields | Field | Required | Meaning | |---|---|---| | `transform` | yes | Registered transform function name | | `node` | for reused or ambiguous transforms | Stable node identifier | | `in` | first step or explicit node | Source dataset type | | `out` | when records are persisted | Target dataset type | Transform bindings can run continuously, on a schedule, or manually. Managed onboarding chooses the mode and required capabilities when the short form is insufficient. ### Inline typed dataflow For common row operations, a node can carry the complete dataflow directly in TOML. This is the read path from the collaborative-board fixture: ```toml [[nodes]] node = "read" [nodes.dataflow] limit = 500 [nodes.dataflow.source] kind = "dataset" dataset = "app_example.collaborative_board.Card" [[nodes.dataflow.stages]] kind = "filter" [[nodes.dataflow.stages.must]] column = "archived" op = "eq" value = false [[nodes.dataflow.stages]] kind = "sort" columns = ["column_id", "title"] direction = "ascending" [[nodes.dataflow.stages]] kind = "project" op = "select" columns = ["id", "column_id", "title", "labels"] [nodes.dataflow.sink] kind = "http_response" ``` The current strict authoring catalog covers `filter`, `project`, `aggregate`, `sort`, `window`, `distinct`, `partitioned_limit`, `http_fetch`, and an execution-boundary `exchange`. A `transform` stage applies declared builtin functions, `operator` names a typed engine factory, and `function` pins a custom artifact. Each stage lowers into the checked-in Rust `Dataflow` model used by the executor; misspelled fields and unavailable stage kinds fail during parsing. Analytic windows can participate in the ordinary batch graph. Current durable streaming authoring requires exactly `window` followed by `aggregate`, supports bounded tumbling/sliding shapes, and rejects session windows, watermark hints, nonzero lateness, excessive sliding fan-out, and unsupported aggregations. ### Compact HTTP routes The top-level `[route]` form describes the common single-node HTTP dataflow. HTTP fields live directly on `route`, an inline source is supplied by default, and `[[route.stages]]` preserves executor order: ```toml name = "ticket-list" description = "List tickets owned by the authenticated workspace." family = "tickets" role = "route" [route] method = "POST" path = "/v1/tickets/list" protocol = "unary" requires_auth = true route_scope = "public" match_kind = "exact" capabilities = ["data_engine"] [[route.stages]] operator = "internal.data_engine_execute" [route.stages.internal_rpc] mode = "data_engine_execute" payload_column = "request" [route.stages.internal_rpc.dataset_read] dataset = "tickets_v1" [[route.stages.internal_rpc.dataset_read.stages]] kind = "filter" must = [{ column = "completed", value = false }] [[route.stages]] operator = "response.unwrap_de_rows" ``` `operator = "factory.name"` is stage sugar for `kind = "operator"` plus `name = "factory.name"`; the expanded form remains accepted. Routes that need something beyond the inline-source default can declare `[route.source]` and `[route.sink]`. Dataflow-level `limit`, `offset`, `stream_mode`, `[[route.param_overlay]]`, and `[route.resource_limit_overrides]` also live under `route`. `route_scope = "public"` controls edge reachability. It does not publish an API contract. Public reference inclusion requires a separate reviewed `public-api` tag, complete documentation metadata, and generator checks. ## Validation lifecycle Repository automation performs these checks before a manifest can progress: 1. Parse TOML with unknown-field rejection. 2. Lower the authoring form into the runtime graph. 3. Verify unique nodes, valid edges, and resolvable functions. 4. Check route scope, authentication, and capability declarations. 5. Compare generated artifacts with the committed versions. 6. Run repository tests and request approval for publication or deployment. A parse or lowering failure should be corrected in the manifest. Generated runtime files should be regenerated through the repository workflow. ## Public route, version, and service expectations `route_scope = "public"` describes intended edge reachability for an onboarded application. It does not make a route self-service. The [generated V1 route inventory](/reference/routes/v1) is the public contract for general API-key callers; pipeline-app routes become callable only after managed onboarding, dataset provisioning, review, publication, and deployment. Pin application behavior to an exact pipeline revision (`spec_name` plus `spec_hash`) when reproducibility matters. Treat `latest` and human `version_tag` values as mutable registry/display metadata. Publish a new revision for behavior or schema changes, record migration guidance for stored data, and keep old revisions available for the installation's rollback policy. Deprecation and removal are managed release decisions; a route should remain in the generated public reference while it is supported. The public V1 inventory currently contains the model API routes and does not provide a generic pipeline-app health endpoint. During managed deployment, use the onboarding deployment status surface and a bounded, owner-scoped smoke request. Treat authentication, validation, and contract-shape failures as application or release signals; retry only statuses documented by the API contract. ## Current limits - Manifest publication is available to onboarded repositories. - The public preview does not expose signing fields or deployment topology. - Inline relational dataflow bodies use a strict, implemented projection into the checked-in Rust `Dataflow`. Unknown keys and incompatible stage shapes fail during parsing. - The strict TOML compiler currently rejects two-input `merge`, `join`, and `set_op` stages because the normal executor request carries no independent right-hand input branch. It also rejects stage-level `limit` until the standard executor has a compatible backend. Top-level output `limit` remains available. - `exchange` currently marks an execution boundary. Physical partitioning strategy fields are rejected until the runtime applies them. - Unsupported operators fail validation instead of being ignored. - Direct route consumers should rely on the [generated public API reference](/reference/routes/v1), not the manifest alone. Continue with the [data platform preview](/reference/data-platform-preview) or the [tickets application walkthrough](/applications/tickets/overview). --- # Limits and retries Source: https://docs.redgold.ai/reference/limits Limits can come from the Redgold account, an individual API key, platform capacity, or an upstream model provider. The response body and headers identify the path that rejected a request where possible. ## Per-key request limits An API key may have a positive requests-per-minute setting. The model API enforces that cap over a rolling 60-second window. When the cap is exceeded the response is a `429` whose error message states the retry interval; the per-key limiter does not set a `Retry-After` header. A key without a positive cap relies on account and provider limits instead. ## Provider limits Upstream providers may return `429` during a capacity or quota event, and that status propagates to the caller. The provider's own `Retry-After` header is not forwarded, so a client should apply its own bounded backoff. The public API does not promise an inline retry that hides the first `429`. ## Client behavior For `429`, `502`, `503`, and `529` responses: 1. Honor `Retry-After` when present. 2. Otherwise use exponential backoff with jitter and a bounded retry count. 3. Avoid retrying a non-idempotent operation unless the API contract supplies an idempotency mechanism. 4. Surface the final provider-shaped error to the user. Validation and authentication failures should be corrected rather than retried. See [errors](/reference/errors). Specific numeric account limits can vary by plan and are shown in the account interface. Planned quota controls are omitted from this page until they are enforced on the public path. --- # API contract details Source: https://docs.redgold.ai/reference/api-contracts Use the base URL `https://api.redgold.ai` and authenticate as described in the [authentication guide](/reference/authentication). The [V1 route inventory](/reference/routes/v1) is generated independently from deployed route manifests. ## `POST /v1/chat/completions` **Request:** An OpenAI-compatible chat-completions object. `model` and `messages` are required; `stream` selects complete JSON or SSE delivery. **Response:** An OpenAI-compatible chat-completion envelope when `stream` is false, or chat-completion chunks when it is true. **Streaming:** Set `stream` to true for server-sent events. Consume each `data:` event until the terminal marker. A failure after headers can arrive in-band. **Errors:** Uses the OpenAI-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page. **Limits:** Model context, output, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses. **Compatibility:** Designed for standard OpenAI SDK clients. Redgold model identifiers, availability, metering, and some provider-specific optional fields differ. ### Example request ```json { "model": "redgold-flint", "messages": [ { "role": "user", "content": "Hello" } ], "stream": false } ``` ### Example response ```json { "id": "response-id", "object": "chat.completion", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "Hello" }, "finish_reason": "stop" } ] } ``` ## `GET /v1/credits` **Request:** No request body. Send the API key as a bearer token. **Response:** The available account balance in integer micro-units and decimal US dollars. **Streaming:** This endpoint is unary and does not stream. **Errors:** Returns the standard OpenAI-compatible error envelope. Authentication failures use 401. **Limits:** Normal account and key request limits apply. **Compatibility:** This is a Redgold account endpoint and has no upstream OpenAI or Anthropic equivalent. ### Example response ```json { "balance_micros": 1000000, "balance_usd": 1 } ``` ## `POST /v1/decisions` **Request:** Send a platform sk-rg API key as a bearer token and JSON with arbitrary `state` plus 1–64 named `questions`. Questions use `type: choice` with instructions and named, described criteria, or `type: noul` with instructions. Optional `task` normalizes state to `{task, context: original_state}`. Optional `model` must be `typesafe/jev-1.13`. **Response:** The Jev provider JSON, including named `answers` and `usage` with input_tokens, output_tokens and USD cost. Choice answers contain a supplied candidate id, confidence and candidate probabilities; noul answers contain a probability. The engine validates answers and usage before returning success. **Streaming:** Unary JSON only. `stream: true` is rejected. **Errors:** Malformed requests return 400; missing platform identity returns 401. Gateway authentication, spend and rate-limit errors retain their HTTP status. Invalid or oversized successful upstream responses return 502; gateway configuration or connection failures return 503. **Limits:** Requests are limited to 24 KB and responses to 64 KB. Each choice accepts 1–64 criteria. Gateway account, key and spend limits apply, with a bounded provider deadline. The engine and rac client do not retry automatically. **Compatibility:** Jev choice/noul decision JSON with an optional task shorthand. State-only requests retain their original state. This route always forwards through the authenticated gateway, including when other LLM routes use direct upstream or BYOK settings. Decisions do not execute tasks. ### Example request ```json { "task": "Identify the failed job", "state": { "jobs": [ { "id": "test", "status": "failed" } ] }, "questions": { "next": { "type": "choice", "instructions": "Choose the job requiring attention from state.context.jobs.", "criteria": { "test": "Test job", "none": "No job requires attention" } }, "failed": { "type": "noul", "instructions": "Does the evidence show a failed job?" } } } ``` ### Example response ```json { "answers": { "next": { "type": "choice", "choice": "test", "confidence": 0.99, "probabilities": { "test": 0.99, "none": 0.01 } }, "failed": { "type": "noul", "noul": 0.99 } }, "usage": { "input_tokens": 30, "output_tokens": 10, "cost": 0.00001 } } ``` ## `POST /v1/messages` **Request:** An Anthropic-compatible Messages object. `model`, `max_tokens`, and `messages` are required; `stream` selects complete JSON or SSE delivery. **Response:** An Anthropic-compatible message object when `stream` is false, or Messages API events when it is true. **Streaming:** Set `stream` to true for server-sent Messages events. Clients must handle an in-band error after the stream begins. **Errors:** Uses the Anthropic-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page. **Limits:** Model context, `max_tokens`, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses. **Compatibility:** Designed for Anthropic SDK clients when the API key is supplied as an Authorization bearer token. Model availability and metering are Redgold-specific. ### Example request ```json { "model": "model-id-from-v1-models", "max_tokens": 256, "messages": [ { "role": "user", "content": "Hello" } ], "stream": false } ``` ### Example response ```json { "id": "message-id", "type": "message", "role": "assistant", "content": [ { "type": "text", "text": "Hello" } ], "stop_reason": "end_turn" } ``` ## `GET /v1/models` **Request:** No request body. Send the API key as a bearer token. **Response:** An OpenAI-compatible model-list envelope. Use an `id` returned for the authenticated account rather than assuming every model is available. **Streaming:** This endpoint is unary and does not stream. **Errors:** Returns the standard OpenAI-compatible error envelope. Authentication failures use 401. **Limits:** Account and key request limits apply; cache briefly when selecting models for repeated calls. **Compatibility:** The list envelope follows the OpenAI model-list shape. Availability and model metadata are Redgold-specific. ### Example response ```json { "object": "list", "data": [ { "id": "model-id", "object": "model", "owned_by": "redgold" } ] } ``` ## `GET /v1/models/{model}` **Request:** No request body. Send the API key as a bearer token and the model id as the path segment. **Response:** A single OpenAI-compatible model object for the requested id, scoped to the authenticated account. **Streaming:** This endpoint is unary and does not stream. **Errors:** Returns the standard OpenAI-compatible error envelope. Authentication failures use 401; an id not available to the account returns 404. **Limits:** Account and key request limits apply; prefer the list endpoint plus brief caching over per-id polling. **Compatibility:** The object follows the OpenAI model shape. Availability and model metadata are Redgold-specific. ### Example response ```json { "id": "model-id", "object": "model", "owned_by": "redgold" } ``` ## `POST /v1/responses` **Request:** An OpenAI-compatible Responses object. `model` and `input` are required; `stream` selects complete JSON or SSE delivery. **Response:** An OpenAI-compatible response object when `stream` is false, or Responses API events when it is true. **Streaming:** Set `stream` to true for server-sent response events. A failure after headers can arrive in-band. **Errors:** Uses the OpenAI-compatible error envelope. Common statuses are 400, 401, 402, 429, 502, and 529; see the errors page. **Limits:** Model context, output, account-credit, and request-rate limits apply. Use bounded backoff for retryable statuses. **Compatibility:** Supports the core Responses request/response flow. Optional tools and provider-specific fields depend on the selected model and may differ from OpenAI. ### Example request ```json { "model": "redgold-flint", "input": "Hello", "stream": false } ``` ### Example response ```json { "id": "response-id", "object": "response", "status": "completed", "output": [ { "type": "message", "role": "assistant", "content": [ { "type": "output_text", "text": "Hello" } ] } ] } ``` --- # Errors Source: https://docs.redgold.ai/reference/errors Model endpoints return the error shape associated with the request family. OpenAI-compatible routes return an OpenAI-style envelope. The Anthropic-compatible Messages route returns an Anthropic-style envelope. Streaming failures may arrive as events after the HTTP response has started. ## OpenAI-compatible error ```json { "error": { "type": "authentication_error", "message": "Authentication failed" } } ``` ## Anthropic-compatible error ```json { "type": "error", "error": { "type": "authentication_error", "message": "Authentication failed" } } ``` ## Status codes | Status | Meaning | Client action | |---|---|---| | `400` | Invalid request or unsupported model | Correct the request; refresh `/v1/models` if the model is unknown | | `401` | Missing or invalid credential | Replace or refresh the credential | | `402` | Account is out of model-API credits | Add credits, then retry | | `429` | Key, account, or provider limit | Honor `Retry-After` when present and back off | | `502` | Upstream model request failed | Retry cautiously if the operation is safe | | `529` | Model temporarily overloaded | Retry with bounded backoff | Do not depend on the exact wording of `message`. Branch on HTTP status and, when present, the structured error type. For streaming calls, handle both a non-2xx response before the stream starts and an in-band error event after it starts. See [limits and retries](/reference/limits). --- # Memory routes Source: https://docs.redgold.ai/reference/routes/memory ::note{icon="i-lucide-bot"} This page is generated from routes explicitly approved for the public API contract. Use the base URL `https://api.redgold.ai` and authenticate as described in the [authentication guide](/reference/authentication). :: ## `POST /api/memory/system/evaluate` Authenticated scoped memory system evaluate. Authentication: required. Protocol: `unary`. ## `POST /api/memory/system/index` Authenticated scoped memory system index. Authentication: required. Protocol: `unary`. ## `POST /api/memory/system/ingest` Authenticated scoped memory system ingest. Authentication: required. Protocol: `unary`. ## `POST /api/memory/system/recall` Authenticated scoped memory system recall. Authentication: required. Protocol: `unary`. ## `POST /api/memory/system/snapshot` Authenticated scoped memory system snapshot. Authentication: required. Protocol: `unary`. --- # V1 routes Source: https://docs.redgold.ai/reference/routes/v1 ::note{icon="i-lucide-bot"} This page is generated from routes explicitly approved for the public API contract. Use the base URL `https://api.redgold.ai` and authenticate as described in the [authentication guide](/reference/authentication). :: ## `POST /v1/chat/completions` Create an OpenAI-compatible chat completion, with optional server-sent-event streaming. Authentication: required. Protocol: `streaming`. ## `GET /v1/credits` Return the authenticated account's available model API credit balance. Authentication: required. Protocol: `unary`. ## `POST /v1/decisions` Evaluate bounded Jev task/state/questions JSON through the authenticated gateway. Authentication: required. Protocol: `unary`. ## `POST /v1/messages` Create an Anthropic-compatible Messages response, with optional server-sent-event streaming. Authentication: required. Protocol: `streaming`. ## `GET /v1/models` List the model identifiers currently available through the public model API. Authentication: required. Protocol: `unary`. ## `GET /v1/models/{model}` Fetch one model object from the public model API — ports the gateway GET /v1/models/{model} route. Authentication: required. Protocol: `unary`. **Parameters** | name | in | type | effect | |---|---|---|---| | `model` | path | string | path segment | ## `POST /v1/responses` Create an OpenAI-compatible Responses API result, with optional server-sent-event streaming. Authentication: required. Protocol: `streaming`. --- # Voice routes Source: https://docs.redgold.ai/reference/routes/voice ::note{icon="i-lucide-bot"} This page is generated from routes explicitly approved for the public API contract. Use the base URL `https://api.redgold.ai` and authenticate as described in the [authentication guide](/reference/authentication). :: ## `POST /api/voice/intent` Same-origin authenticated completion route for contextual voice intent. Authentication: required. Protocol: `streaming`. --- # Author a batch transform Source: https://docs.redgold.ai/develop/author-a-batch-transform A batch transform is a trusted native compute unit in an engine pipeline. It accepts one Arrow IPC stream, emits zero or more Arrow IPC streams, and loads in the dataflow executor as a content-addressed Rust `cdylib` through the `NATIVE_DYLIB` tier. Use this path for reviewed platform code. Tenant-supplied WASM uses the separate capability-limited Wasmtime UDF lane, while untrusted native or Python code uses the Firecracker `MICROVM` lane on opted-in KVM nodes. The conversation extraction transform is the maintained native example: - input schema: `redgold.ai.conversation_message_gateway.ConversationMessageGateway` - transform: `crates/exec/data-transform-batch-conversation-message-extract` - output schema: `redgold.ai.conversation_message_extracted.ConversationMessageExtracted` - runnable pipeline: `pipelines/jobs/memory-r1-messages.toml` - inline ABI test: `crates/exec/data-transform-batch-conversation-message-extract/src/lib.rs` :::caution Batch artifact fetching is enabled on the managed dev executor variants. The public dataflow executor does not expose the batch-transform surface, so publishing a `PipelineSpec` does not make a native batch job publicly callable. ::: ## Create one ```bash rac transform new example-rows ``` This writes `crates/exec/data-transform-batch-example-rows/{Cargo.toml,src/lib.rs,pipeline.toml,job.toml}`. The generated transform is an identity stage with an inline ABI test. The scaffold test uses placeholder bytes, so replace it with a real Arrow IPC fixture as part of implementing the row conversion. Replace `run_transform` while retaining the exported `transform_batch_abi_version` static and `transform_batch` function. `pipeline.toml` is the route-less PipelineManifest registered for inspection; `job.toml` is its directly executable standalone form. Fill in `[package.metadata.batch-transform]` with the input and output dataset names, stable Rust schema type identifiers, the checked-in example job, and the pipeline manifest. Move or adapt `job.toml` under `pipelines/jobs/`. Its shape is: ```toml [dataflow.source] kind = "jsonl" hos_prefix = "raw/example/" [[dataflow.stages]] kind = "function" qualified_name = "data-transform-batch-example-rows" pin_artifact_hash = "PUBLISH_RESULT_GOES_HERE" [dataflow.sink] kind = "hos" hos_path = "derived/example/{run_id}/example_rows" ``` Stored and wire schemas use the component's checked-in Rust serde types and CBOR. Reuse the focused schema micro-crate in transform code, and treat Arrow, Lance, SQL, and index layouts as projections of that source type. The `qualified_name` identifies the function. The `pin_artifact_hash` selects the exact published bytes. Keep both in the committed job so an executor cannot silently run a newer build under the same name. ## Check and publish ```bash rac transform check crates/exec/data-transform-batch-example-rows rac run \ --with-secret DTS_DATABASE_URL \ --with-secret HETZNER_S3_URL \ --with-secret HETZNER_S3_ACCESS \ --with-secret HETZNER_S3_SECRET \ -- \ rac transform publish crates/exec/data-transform-batch-example-rows ``` `check` validates the package prefix, `cdylib` target, ABI dependency and version, metadata identity, exported ABI symbols, pipeline reference, and local job reference. It is a structural check; run the crate's inline test to verify the actual Arrow conversion before publication. `publish` builds the release library, computes its BLAKE3 digest, uploads it to `transforms/batch/.so` in HOS, registers the code metadata, injects the pin into the route-less pipeline text in memory, and publishes the resulting signed `PipelineSpec` to DES. The command prints one `registered transform=... artifact_blake3=...` line after all registration steps succeed. Publication requires the four canonical vault items shown above, a configured `DATA_ENGINE_URL`, and a registered local signing identity created through `rac auth keygen`. A failed build, upload, or registration returns an error without a usable new pin. Copy the printed `artifact_blake3` value into the committed job's `pin_artifact_hash`. Executors with HOS artifact fetching enabled retrieve that exact object and verify its BLAKE3 digest before loading it. Re-publishing unchanged bytes returns the same content address. ## Run the canonical example The bounded conversation job carries a checked-in artifact pin: ```bash dataflow-runner --user-id system-backfill submit \ --manifest pipelines/jobs/memory-r1-messages-validate.toml \ --run-id conversation-extract-check ``` The bounded job reads 50 gateway objects, invokes the Rust transform, deduplicates on its `data_hash` output column, and writes Lance output to HOS. The full `memory-r1-messages.toml` job uses the same transform and pin; its companion `memory-r1-messages-compact.toml` performs cross-partition deduplication. The route-less manifest in the transform crate and the two runnable memory jobs currently pin different published revisions. Treat each checked-in hash as an independent deployment choice; publication does not rewrite any of those files. The source crate is the implementation reference because its inline test constructs real Arrow IPC input, calls the exported ABI, decodes every emitted batch, and verifies `data_hash = blake3(primary_key)` for each result. Before committing a new pin, run the transform crate's focused inline test and validate the two manifest forms: ```bash timeout 300 rac cargo test \ -p redgold-data-transform-batch-example-rows rac transform check crates/exec/data-transform-batch-example-rows ``` --- # Pipeline apps Source: https://docs.redgold.ai/develop/pipeline-apps/overview ::caution Pipeline applications are currently delivered as a managed preview. Customers review their Rust schemas, pipeline TOML, transforms, tests, and API contract in Git. Redgold operates publication, routing, execution, storage, deployment, and monitoring. The portable `app.*` package, declarative client surfaces, catalog sharing, and offline installation are developer-preview components beyond the current customer deliverable. Public self-service publication remains planned. :: ## Current managed contract The current contract has a deliberate ownership boundary: | Customer reviews and controls | Redgold operates | |---|---| | Rust serde schemas | Edge routing and authentication | | Pipeline TOML | Pipeline validation and publication | | Rust transform code | Sandboxed execution | | Inline tests and fixture requests | Data engine and storage tiers | | API contract and Git history | Deployment, monitoring, and recovery | A coding agent may author changes inside the customer-controlled column. The customer reviews those artifacts before Redgold validates and deploys the managed application. Start with the [artifact walkthrough](/intro/pipeline-app-walkthrough). The sections below describe how this managed backend grows into a portable application package. Their maturity tables distinguish current runtime behavior from component previews and planned distribution features. A pipeline app expresses application behavior as artifacts the platform can inspect: typed records, dataflows, routes, transforms, datasets, and deployment state. The application contract adds page surfaces, client actions, synchronization policy, capabilities, and exact dependency pins. The managed registry and installation runtime load verified remote releases inside the shared Redgold web, Android, and iOS client code. ## Mental model ```mermaid flowchart LR Project["Logical app id"] --> Release["App release\nlocal compiler"] Release --> Schema["Rust serde schemas"] Release --> Pipelines["Pipeline specs"] Release --> Surfaces["UI surfaces\nlocal host"] Release --> Assets["Assets"] Release --> Policy["Capabilities + merge policy\nvalidated"] Pipelines --> Server["Engine + executor\ncurrent"] Surfaces --> Host["Shared Vue host\nweb + Android + iOS"] Policy --> Portable["Portable Rust/WASM dataflow core\ncomponent preview"] ``` The application envelope belongs above the execution DAG. A pipeline remains a reusable graph that can be invoked by several applications. An application release groups exact pipeline revisions with its schemas, surfaces, assets, and security policy. An installation pins one release for one workspace and records the capabilities that workspace accepted. ## What exists at each maturity level | Level | Capability | |---|---| | **Current** | Rust serde records, one-shot dataflows, registered pipeline DAGs, built-in operators, trusted native batch transforms, capability-limited Wasmtime UDFs, Firecracker isolation for opted-in untrusted native/Python workloads, owner-scoped datasets, and Git-backed deployment | | **Developer Preview** | Git-authored `pipelines/*.toml`, strict portable-app TOML parsing, exact pipeline resolution, canonical unsigned build candidates, signed immutable publication, tenant installation/upgrade/rollback/consent services, verified remote host loading, durable Rust/WASM mutation replay, and descriptor-bound causal set/list/delete merge | | **Planned** | Deterministic custom client transforms, arbitrary descriptor-generated subscriptions and native host effects, and public self-service catalog publication | ## The five layers ### 1. Schema defines durable meaning Checked-in Rust serde types define stored records and over-the-wire payloads. A dataset reference can carry a type URL and a pinned schema-descriptor hash, which lets a runtime distinguish revisions of the same logical type. Schema remains the source of field names, types, validation inputs, form generation, and merge policy. This layer is current. See [data and pipelines](/infrastructure/data) and the [Developer Preview schema](/reference/data-platform-preview). ### 2. Pipelines define server behavior A `Dataflow` is one relational execution. A registered `PipelineSpec` is a named DAG. A `PipelineManifest` is the readable TOML desired state that CI lowers into a runtime spec. Routes, reads, writes, subscriptions, schedules, and transform stages use this path. Manifest authoring is Developer Preview and publication remains managed. See the [pipeline manifest preview](/reference/pipeline-preview). ### 3. Transforms provide the escape hatch The declarative target covers filter, project, map fields, validate, aggregate, join, sort, merge, and emit. The current strict compiler supports the unary subset and fails closed on two-input stages until the executor supplies an independent right-hand branch. A custom transform is appropriate when the operation needs domain code. Its ABI, input/output schemas, artifact digest, resource limits, and allowed host access form part of its contract. Trusted Rust batch transforms and their content-addressed artifact pins are current. A deterministic client transform format that can use the same typed expression model is planned. ### 4. Surfaces define client behavior The preview `ComponentNode` contract is a constrained component tree with typed data bindings and actions. A local Vue host prototype currently allowlists `stack`, `grid`, `card`, `text`, `markdown`, `form`, `input`, `button`, `list`, `board`, `tabs`, and `navigation`. Its golden collaborative-board fixture uses host-owned lower-snake-case callbacks such as `create_card`, `open_card`, and `add_example_card`. The host validates component and action graphs and routes effects through injected host ports for pipeline invocation, entity operations, navigation, local state, capabilities, and events. The installed-package source fetches the tenant installation and verifier key over the authenticated service channel. It verifies both the immutable publication receipt and the registry-signed mutable installation projection before opening the shared durable runtime. The signed installation sequence prevents revision rollback. Within one sequence, the service atomically allocates and persists each attestation `issued_at_ms` while locking the installation and its exact transitive release closure. The runtime rejects an older projection, requires equal timestamps to reproduce the same projection hash, and retains root-release revocation or dependency-driven suspension as terminal state for that sequence and release. The checked-in fixture remains useful for local authoring. The descriptor-driven entity adapter validates and queues create, scalar edit, set-membership add/remove, move, and comment records. Authoritative batch hydration is folded with cached and queued state before rendering. Arbitrary descriptor-generated subscriptions and native host effects remain planned. The renderer lives in the canonical Vue application, which Capacitor packages for Android and iOS. Portable action effects have a narrow v1 host contract: - `invoke_pipeline` accepts an empty input, or one input value declared by the signed action config. A parameter binding names the input key, filter column, comparison (`eq`, `neq`, `gt`, `gte`, `lt`, or `lte`), and scalar kind (`string`, `int64`, `double`, or `bool`). The host converts that value into the executor's audited dataflow overlay; undeclared keys and type mismatches fail closed. - `query_entity` accepts exactly one `entity_id` or a bounded `entity_ids` array. It uses the signed entity descriptor and installation-authorized batch endpoint, then returns `{ entities: [...] }` in request order while omitting absent identities. - `emit_event` dispatches a browser-local `redgold:runtime-app:event` with the installation id, verified app id, safe event name, and cloned payload. It creates no server or cross-application side effect. - `invoke_function` remains publication-ineligible in runtime v1. Function artifact pins exist, while an authenticated host request/response contract and portable ABI input encoder do not. The pipeline binding is authored on an `invoke_pipeline` action node: ```toml [actions.nodes.config] pipeline_input_key = "column_id" pipeline_filter_column = "column_id" pipeline_filter_operator = "eq" pipeline_filter_value_kind = "string" ``` ### 5. Releases and installations define distribution The immutable-release contract pins every schema, pipeline, transform, surface, asset, capability, and dependency it needs. The local compiler lowers an app manifest, validates its graph, resolves each pipeline to an exact content hash, and writes deterministic CBOR and JSON release candidates. The resulting release hash is a publisher-independent package digest. Its installation contract records that exact digest, tenant scope, accepted permissions, and upgrade history. Managed publication verifies the publisher attestation and stores the immutable release and receipt. Tenant installation, upgrade, rollback, capability consent, revocation projection, and runtime write enforcement use that stored release identity. Every installation response also carries a fresh registry signature over its exact state, grants, release projection, revocation state, and revision sequence. Discovery, installation, and data sharing are separate decisions. Installing an application does not expose another user's data. Dataset grants continue to control shared records independently. The Apps UI exposes three library scopes. **My apps** combines authored Vibe projects with installations in the active workspace. **Shared with me** shows private app entitlements granted to the caller or workspace. **Discover** shows public catalog entries whose current release an operator approved. Owners can share a released app with an active trusted contact after that contact resolves to a joined workspace member; the share is an `APP` resource grant over the stable `app_id`. The recipient installs an independent copy into a workspace where they are owner or admin and explicitly accepts the release capabilities. Public submission creates a pending catalog revision. Operators review its publisher, exact release, requested capabilities, tags, and description at `/admin/apps`. Approval makes that revision discoverable; denial records a reason and leaves private owner/grantee access intact. Review history is append-only while immutable release bytes remain unchanged. ## Schema plus transforms The authoring goal is a small common case: ```text schema declares records and field policy pipeline declares reads, writes, subscriptions, and common transforms surface declares pages, bindings, and actions custom UDF supplies the domain-specific operation when needed release groups and pins the artifacts above ``` An agent can generate this bounded artifact set, and validators can reject unknown operations, missing schemas, undeclared capabilities, and unresolved references before publication. ## Runtime placement | Runtime | Status | Intended work | |---|---|---| | Engine and dataflow executor | Current | Dataset scans, relational operators, standing pipelines, trusted native transforms, and isolated server UDFs | | Shared Vue and Capacitor host | Current | The platform-authored web UI packaged for browser, Android, and iOS | | Declarative application renderer | Developer preview | Allowlisted components, bindings, validated action DAGs, injected effect ports, a golden board fixture, verified installed-package loading, and descriptor-driven board create/edit/move/comment/label actions | | Portable Rust/WASM dataflow core | Developer preview | Strict installed-bundle verification, installation-bound canonical-CBOR state, durable operation replay, cached entities, HLC/causal metadata, and CBOR entity operation/batch-observation transport | | Server request-handler WASM host | Component preview | A feature-gated host and local unary/streaming/WebSocket fixtures exist; production route selection is not wired to it | | Dataflow UDF WASM backend | Component preview | Default-on executor backend with fuel, memory, and wall-time bounds, no WASI, and a `UDF_WASM_DISABLE=1` kill switch; first route staged for publication | ## Hashes, versions, and signatures A current `PipelineSpec` revision hash and author signature cover the canonical canonical CBOR encoding of its nodes, output node ids, and spec name. The human-readable `version_tag`, description, tags, registry `latest` flag, and timestamps are outside that content identity. An exact pipeline revision is therefore identified by `spec_name + spec_hash`, and an exact compiled transform by its artifact hash. `AppRelease.content_hash` covers the canonical package graph and exact referenced hashes with `content_hash`, `author_hash`, `author_signature`, and the provenance publisher fields cleared. It is therefore independent of publisher identity. A separate publisher attestation binds signer identity to that digest. Canonical hashing is implemented for local release candidates; local inspection distinguishes an unsigned draft from registry verification. Managed publication strictly decodes the wire bytes, rejects unknown fields and tags, binds the authored source to the normalized manifest and release digest, verifies the publisher attestation and referenced evidence, and issues the opaque receipt used by installation and remote loading. A signed pipeline alone does not authenticate a page layout, asset, dependency, capability request, or migration. Read [release and security lifecycle](/develop/pipeline-apps/release-lifecycle) for the full boundary. ## Continue - [Collaborative board walkthrough](/develop/pipeline-apps/collaborative-board) shows how the complete target fits together. - [Release and security lifecycle](/develop/pipeline-apps/release-lifecycle) covers signatures, permissions, installation, upgrades, sharing, and forks. - [Managed application artifacts](/develop/scaffold-a-narrow-app) defines the current customer-reviewed backend contract. - [Build a vertical](/develop/build-a-vertical) covers the current repository implementation path in detail. --- # Collaborative board walkthrough Source: https://docs.redgold.ai/develop/pipeline-apps/collaborative-board ::warning This is the golden developer-preview fixture for the portable Pipeline Apps contract. It covers strict authoring, managed signed publication, tenant installation, verified remote loading, the shared Vue host, durable Rust/WASM replay, schema-descriptor-driven board mutations, and schema-descriptor-bound causal entity merge, owner/grantee sharing, and operator-reviewed catalog publication. Arbitrary schema-descriptor-generated subscriptions, custom client transforms, and public self-service publication remain planned. :: The collaborative board is deliberately ordinary: columns contain cards, cards have labels and comments, several people can edit, and the application works on web and mobile. That makes it a useful proof of the complete contract. It exercises typed storage, reads, writes, subscriptions, page layout, local state, conflict resolution, permissions, installation, and upgrades without requiring a separate service architecture. ## Target experience 1. A user installs a pinned board release into a workspace. 2. The shared client renders the release's board and card-detail surfaces. 3. Queries resolve through exact named pipeline revisions; the foreground host refreshes declared entity collections from authorized snapshots. 4. Edits become typed operations and enter the durable device queue. 5. Offline operations replay after reconnect or app resume. 6. The server authorizes operations, merges them, and materializes cheap read datasets. 7. Other visible, online clients refresh the converged server materialization. 8. An upgrade displays schema, pipeline, surface, dependency, and permission changes before moving the installation pin. ## Artifact map | Artifact | Board responsibility | Status | |---|---|---| | Rust serde schemas and runtime descriptors | `Board`, `Column`, `Card`, and `Comment` records | Exact schema-descriptor and dataset pins are validated and registered with installed releases | | Pipeline manifests | Strict row-shape list/write/move/comment/event fixtures | Resolved to exact `PipelineSpec` hashes with declared capability checks | | Custom transform | Domain-specific move validation or derived activity rows | Trusted native server transforms current; portable client UDF planned | | Entity operation policy | Field clocks, sets, ordered references, and tombstones | Descriptor-checked causal reducer with durable dots/version vectors and server materialization | | Surface tree | Board and card-detail pages with bindings and actions | Verified installed-package source and shared Vue/Capacitor host with create/edit/move/comment/label adapters | | Application release | Exact membership, hashes, capabilities, and provenance | Local unsigned candidates plus managed signing, strict verification, receipt, and immutable registry storage | | Installation | Tenant pin, accepted permissions, and upgrade history | Tenant-scoped install, consent, upgrade, rollback, revocation projection, and write enforcement | ## Try the local release path From the repository root: ```bash rac app validate apps/collaborative-board/app.toml rac app build apps/collaborative-board/app.toml rac app inspect apps/collaborative-board/build/app-release.pb ``` Validation reports `valid=true` for the local application graph. Building strictly parses all six referenced pipeline files, resolves their canonical `PipelineSpec` hashes, and writes deterministic CBOR and JSON artifacts. The CLI retains the `app-release.pb` filename for compatibility; the local candidate payload is deterministic CBOR, with a JSON companion. Inspection reports `publish-eligible=false` because the local fixture has no registry-resolved schema-descriptor/dataset proofs or publisher signature. Those warnings are part of the publication boundary rather than skipped checks. ## 1. Define records The `card` entity in `apps/collaborative-board/app.toml` declares its fields directly, each with the merge policy that governs it: ```toml [[entities]] id = "card" type_url = "app_example.collaborative_board.Card" dataset = "app_example.collaborative_board.Card" identity_fields = [1] display_fields = [3] [[entities.fields]] tag = 1 name = "id" kind = "string" cardinality = "required" merge = "immutable" [[entities.fields]] tag = 2 name = "column_id" kind = "entity_reference" cardinality = "required" references = "column" merge = "last_writer_wins" ``` The remaining fields follow the same shape: `title` (searchable, max length 200), `description`, `labels` (repeated, `add_wins_set`, tombstone-retaining), `assignee_id`, and `archived` (bool, defaulting to false). Field tags are stable identity for the merge reducer, so a field keeps its tag across revisions. The final stored records also follow the platform's owner scope and primary key conventions. Schema registration gives each type URL an exact schema hash. In this walkthrough, a descriptor is the runtime metadata derived from that checked-in Rust serde schema: field tags, kinds, identity fields, and merge policy. It is runtime schema metadata, rather than a code-generation artifact. Surface fields and transforms refer to this registered schema metadata rather than recreating a TypeScript-only model. The merge policy belongs beside the schema contract: | Field | Policy | Reason | |---|---|---| | `title`, `column_id`, `assignee_id` | HLC-ordered LWW register | One current scalar value | | `labels` | Causal add-wins set | Concurrent add/remove events retain their causal frontiers before policy resolution | | comments | Independent immutable records | Child operations participate in durable ordered replay | | deleted state | Clocked tombstone | Old updates cannot revive a deleted card | | `description` | LWW initially; text CRDT opt-in | Character-level merging adds cost and should be explicit | The entity merge crate validates manifest field declarations against an exact pinned schema-descriptor set. Its preview reducer applies immutable and LWW registers, causal add/remove sets, ordered references, and delete/update frontiers to dynamic messages. Installation-qualified client sites allocate durable dots; the DES oplog validates dot collisions against the exact tenant, entity reference, and canonical payload before materializing the result. ## 2. Declare server pipelines The current manifest path can express the board's backend routes as small graphs: - `board-list` reads active and archived rows with nonempty ids, columns and titles, excluding legacy incomplete records from hydration without deleting them. It sorts active cards first and then by `column_id` and `title`, and projects the card fields. The Board and Archive surfaces select their display from the same bounded collection; - `board-upsert-card` trims titles, rejects empty ids/titles, and projects a complete row into the card dataset; - `board-move-card` rejects empty card/column ids and projects a complete card row; - `board-add-comment` trims bodies, rejects empty ids/card ids/bodies, and projects a comment row; - `board-comments` reads workspace-authorized comments in creation order; the detail list filters by the selected card, and hydration merges durable pending creates into the same fixed collection used by optimistic writes; - `board-events` subscribes to non-archived card rows with a bounded projection. These are executable row-shape manifests. Portable entity writes use the installation-bound CBOR `EntityOp` transport and require an active, verified `DATASET_WRITE` grant for the release-pinned dataset. The schema-descriptor-driven action adapter covers card creation and editing, moves, label-set membership, and comment creation. A future custom transform could handle a rule such as “a closed card cannot move into an active sprint without reopening,” with pinned input/output schemas and an exact artifact hash. The [public pipeline manifest preview](/reference/pipeline-preview) covers the referenced execution graphs. The application compiler separately parses the outer manifest and resolves every `source` path through that strict pipeline parser. ## 3. Group a release The checked-in fixture uses accepted application TOML. This is a shortened excerpt from `apps/collaborative-board/app.toml`: ```toml [app] id = "collaborative-board" name = "Collaborative Board" version = "0.1.3" minimum_runtime_version = "1.0.0" default_view = "board" [[entities]] id = "card" type_url = "app_example.collaborative_board.Card" dataset = "app_example.collaborative_board.Card" [[pipelines]] name = "board-list" source = "pipelines/board-list.toml" [[views]] id = "board" name = "Board" initial_page = "board" ``` `rac app build apps/collaborative-board/app.toml` resolves every pipeline, computes the publisher-independent canonical package hash, and writes deterministic CBOR and JSON candidates under the fixture's ignored `build/` directory. The local candidate is deliberately unsigned. Managed publication binds the exact authored source and normalized manifest to that digest, rejects unknown field tags, verifies the separate publisher attestation, stores the immutable release, and returns a signed verification receipt. ## 4. Describe the board surface Surface declarations live in the same accepted manifest: ```toml [[views.pages]] id = "board" route = "/" title = "Collaborative Board" [views.pages.root] id = "board-shell" type = "stack" [[views.pages.root.children]] id = "board-columns" type = "board" ``` The component and action names come from an allowlisted registry. The shared validator checks v1 route, component, action-target, binding-shape, execution site, capability, and schema-descriptor rules. The current adapter derives safe create, edit, move, label, and comment operations from signed entity schema descriptors; arbitrary schema-descriptor-generated live subscriptions remain planned. ### Card lifecycle The create form accepts a title and description. Card edits, moves and label changes update the selected entity after the durable operation succeeds, so the next action uses the resulting values. Archive and restore change only the existing `archived` field through the same offline-capable entity path; the card and its comments remain stored. The Archive page opens archived cards for restoration to their previous column. The board component accepts a static `archiveFilter` prop with `active`, `archived`, or `all`. Omission preserves the existing `all` behavior. Filtering and display projection run in the shared Rust core/WASM, before the per-column display limit. Display excerpts never replace the full entity carried by a selection action, including long descriptions, labels and identifiers. Cached archived records can therefore remain available for offline restoration without appearing on the active board. This remains a bounded preview: `board-list` reads at most 500 cards, and active cards sort before archived cards within that window. The Archive page does not provide pagination or promise a complete history beyond that limit. Version 0.1.3 must be published after deploying the host and publication validator that support `archiveFilter`; existing installations must upgrade their signed pin. Runtime version 1 alone does not negotiate this additive component property. ## 5. Execute on web and mobile The canonical Vue application already builds into the Capacitor Android and iOS shells. The local fixture and remote installed-package source run through that shared Vue code. Remote loading resolves the authenticated tenant installation, verifies the immutable receipt and signed mutable installation projection, checks the authenticated response sequence, requires an active installation, and then projects the release: ```text AppRelease -> verify hashes and signature -> register schema descriptors and components -> resolve installed capabilities -> build routes and surfaces -> open query/subscription bindings -> render with the shared Vue host ``` Native actions such as notifications, camera input, file selection, or location will use separately declared host capabilities. Arbitrary schema-descriptor-generated subscriptions and native effect adapters are still planned. ## 6. Work offline and converge The portable Rust/WASM runtime binds state to the installation, tenant, user, and an installation-qualified device site. It persists one bounded canonical CBOR envelope containing HLC state, entity cache, causal context, queue sequence, retry metadata, acknowledgements, dead letters, and verified package trust state through Capacitor Preferences. Mutations reload the latest durable snapshot under a cross-tab lock, and reconnect/resume hooks replay the ordered queue through the installation-bound CBOR entity endpoint. An offline move follows this path: 1. Validate the proposed `Card` change against the pinned Rust schema descriptor. 2. Create a typed operation with an id, site id, and HLC stamp. 3. Persist the operation before exposing the queued result. 4. Replay after reconnect in deterministic order. 5. Record an applied, duplicate, retry, or permanent-rejection disposition. 6. Merge accepted operations and any concurrent remote operations using the field's declared policy. 7. Refresh the rendered board through the signed query and entity-read interfaces. Authentication and dataset grants remain server-authoritative. Optimistic state can be rejected, in which case the client records the error and re-materializes from acknowledged operations. ### Foreground synchronization The signed release opts into foreground refresh with root config `runtime_entity_refresh = "foreground_snapshot_v1"`. This is the author's declaration that all entity hydration pipelines are read-only and safe to repeat. The board's card and comment queries satisfy that contract. The execution API does not enforce a read-only mode, so existing releases without the opt-in keep startup-only hydration and must be explicitly upgraded to enable refresh. The installed host refreshes the opted-in collections declared by signed entity hydration actions, including cards and comments. It runs at most one refresh pass at a time, with at least 15 seconds between starts while the app is visible and online. Reconnect, returning to the app, replay completion and settled local actions request a refresh through the same bounded scheduler. Failures retain the current display, show an error and retry with backoff up to two minutes. Each pass invokes exact release-pinned pipelines with the installation identity, then reads authorized entity values and folds pending durable operations. A local action or installation/workspace change invalidates an overlapping display result. Only declared collections are replaced; drafts, selected-card form values and navigation remain local. Open another card to load its refreshed values into the editor. Hidden and offline clients refresh after returning online and visible. This is periodic snapshot convergence, not a live subscription guarantee. The server does not yet accept installed application specs on its subscription endpoint; the `board-events` fixture alone does not create a browser subscription. Refresh retains the existing bounded query windows, so it does not establish pagination, arbitrary board/column editing or native background synchronization. Two independent browser contexts can verify this shared host behavior; native device conformance still requires its own device run. ## 7. Share, upgrade, and fork - **Share the application:** grant a principal access to the private catalog entry; the grantee sees it under **Shared with me** and can install the pinned release into an authorized workspace. - **Share board data:** create a separate dataset grant, potentially read-only. - **Upgrade:** inspect changes to schemas, pipelines, surfaces, dependencies, migrations, and capabilities, then move the installation pin. - **Rollback:** return to a compatible prior release while preserving the append-only operation history. - **Fork:** create a new app identity and release lineage. Source data stays in place unless the user explicitly copies or grants it. ## Preview verification checklist The developer-preview implementation exposes each lifecycle boundary for targeted verification. A deployment or device-conformance result should be claimed only after its corresponding check has run: - publish and install a signed release, then load it without a hard-coded app route; - render the same installed surface through the shared web and Capacitor host; - inspect every exact schema, pipeline, artifact, surface, and dependency pin; - replay concurrent offline edits from installation-qualified sites and inspect the converged materialization; - reject an undeclared capability, inactive installation, and tampered bundle; - inspect an upgrade diff, preserve pending operations across the rebind, and exercise rollback. Continue with [release and security lifecycle](/develop/pipeline-apps/release-lifecycle) or return to the [Pipeline Apps mental model](/develop/pipeline-apps/overview). ### Comment visibility and bounds Comment display uses the generic list `filterField` and bound `filterEquals` properties. Exact matching happens before the display limit; an empty or missing selection renders no rows. This display filter does not authorize data access: installation grants and workspace scope remain enforced by the server. The reference query reads at most 200 comments and the selected-card list shows at most 100. Pagination and live comment subscriptions remain future work. ### Causal list contract Ordered reference fields use unique, nonempty string members and causal snapshot frontiers. A snapshot replaces only snapshots its causal context observes. Concurrent snapshots retain their union: traverse maximal snapshots in ascending (site id, counter) order and append each member at its first occurrence. This resolves conflicting reorders deterministically without using wall clocks. An observed later snapshot can reorder or remove any member. A concurrent snapshot that still contains a removed member retains it until a later edit observes both. This is a snapshot sequence contract; it does not promise character-level editing or positional insertion intent across concurrent reorders. The server persists the maximal snapshots with the entity clock rollup; the portable runtime retains this rollup and uses its version vector on the next queued operation. Portable list and set mutations require causal dots. The current board surfaces mutate cards and comments; arbitrary list-editing controls are not yet exposed by the host action contract. Publication requires a trusted signed receipt naming `redgold.causal-snapshot-lists-add-wins-sets.v1`, bound to the exact release. The verifier first compiles every entity with the installed-write descriptor mapping. Missing or unknown attestations and unsupported merge strategies remain ineligible. Local unsigned candidates cannot assert their own compatibility. For UI deployment evidence, read the `redgold-ui-revision` comment in the served HTML index. For UI prefixes, the proxy derives `/build-revision.txt` from that same index stamp rather than the legacy storage object. The endpoint is non-cacheable and fails closed when the index has no valid revision; docs prefixes retain their separate marker protocol. Compare the marker with the loaded application and service worker when verifying browser delivery. --- # Release and security lifecycle Source: https://docs.redgold.ai/develop/pipeline-apps/release-lifecycle ::caution The developer-preview lifecycle implements strict local lowering, canonical hashing, publisher attestation verification, immutable registry storage, signed verification receipts, tenant installation, capability consent, upgrade/rollback diffs, revocation projection, verified remote loading, owner/grantee sharing, and operator-reviewed public catalog entries. Public self-service publication remains planned. :: Portable applications add a software supply chain to the platform. A release can contain executable transforms, pages, actions, dependencies, and requests for data or device access. Reproducible hashes and explicit capability grants therefore belong in the base contract rather than in catalog policy added later. ## Application identities and roles | Identity or artifact | Lifetime | Mutable state | |---|---|---| | Logical app (`app_id`) | Long-lived product identity | Display and repository metadata live in authoring/catalog records | | `PipelineAppManifest` | Mutable authoring input | Readable unresolved members, configuration, and tags | | `AppRelease` | Immutable artifact graph | None; a content change creates a new release hash | | `AppInstallation` | One tenant's realization of a release | Current pin, accepted grants, local configuration, upgrade and rollback history | | `AppCatalogEntry` | Public or tenant-private discovery record | Summary, latest-release pointer, categories, preview assets, and visibility policy | Keeping these roles separate allows several installations to pin different releases while preserving one logical app and publisher lineage. Catalog visibility grants neither installation authority nor dataset access. ### Read-only dataset operations `GET /api/apps/installations/{installation_id}/operations/datasets` resolves the authenticated owner/workspace and the authoritative installed release on the server. The URL selects an installation, not a tenant, release, or dataset. The response contains `appId`, `installationId`, `tenantId`, `releaseHash`, and `items`. Each item names a release-declared entity dataset or a registered dataset covered by a current dataset-read grant and its release capability request. Wildcard grants expand registered dataset names only; constrained grants do not establish an unrestricted count. `rowCount` contains `value`, `status` (`known` or `unknown`), `complete`, and `reason`. Counts measure projected rows, including the reader's entity/version folding, not raw storage images. The engine's normal bounded, owner/workspace read supplies the rows with administrative and subscriber bypasses disabled. An incomplete, failed, or timed-out scan never yields a zero or a partial count: that dataset's count is unknown with reason `dataset_scan_incomplete`, `dataset_read_failed`, or `observation_budget_exhausted`, and the other datasets are still reported. Unknown sources, inactive installations, and datasets without owner-scoped reads also return explicit unknown counts. The request shares a ten-second observation budget (`source.observationBudgetMs`) across at most 128 datasets; datasets are read one at a time, not as one cross-dataset transactional snapshot, and those not reached within the budget are unknown. `source` identifies the engine dataset, storage tier, scope, read start and completion times. These are observation-request provenance, not the age of the source data. Freshness has three separate measurements: `sourceObservedAtMs`, `latestCompleteRankingActivationAtMs`, and `laterUserExclusionChangeAtMs`, each with `value`, `status`, `complete`, and `reason`. They remain unknown until release-bound semantic provenance is available. Neither an installation update, a storage write, a successful execution, nor the request's clock proves any of these timestamps. In the Media example, Candidate source observations, a complete Ranking activation, and later Seen/history/request/library or exclusion changes must not collapse into one timestamp or make an underfilled queue appear empty and healthy. This endpoint performs reads only and sets `Cache-Control: no-store`. It does not invoke pipelines, refresh integrations, or repair incomplete scans. The operations UI remains on its existing description read until deployed count and provenance verification is complete. ## Current pipeline signing boundary A current `PipelineSpec` content hash is BLAKE3 over the canonical CBOR encoding of: ```text nodes + output_node_ids + spec_name + cli ``` The author signature verifies that hash. The optional `cli` value contains the published command name, aliases, and help text; changing that surface creates a new content revision. `version_tag`, description, tags, `latest`, and timestamps are excluded. Changing those metadata fields does not create a new content revision. The stable revision key is `spec_name + spec_hash`; `latest` is a mutable registry pointer. Function source and compiled artifacts have their own content hashes. When a pipeline carries `pin_ast_hash` or `pin_artifact_hash`, resolution must use that exact source or binary. A human `version_tag` remains useful for display and release notes, while the hash is the reproducibility boundary. ## Application signing contract `AppRelease.content_hash` is computed over canonical package bytes with `content_hash`, `author_hash`, `author_signature`, and the publisher identity fields in provenance cleared. It is a publisher-independent digest of the package graph. A separate publisher attestation binds signer identity to that digest. The local compiler implements canonicalization and deterministic hashing, then emits an unsigned candidate. Managed publication verifies the publisher attestation and referenced registry evidence before it stores the immutable release. The shared release validator separates structural validity from publication evidence. Local callers can supply the authored manifest whose hash is carried by the release and prove the normalized resolved graph still matches it. The cryptographic/registry evidence fields are opaque and cannot be asserted by a caller. The release-bound verifier strictly rejects unknown schema fields and tags, binds authored source bytes and their hash to the exact normalized manifest and release digest, verifies the publisher attestation, and issues an opaque signed receipt. Local unsigned candidates remain inspectable and ineligible until they pass that managed boundary. The canonical release is intended to cover: - application identity and release format version; - exact schema descriptor references; - exact pipeline revisions; - exact transform and asset artifacts; - surface trees, bindings, actions, and navigation; - dataset declarations and migration policy; - capability requests; - exact dependency releases; - collaboration, offline, and compatibility policy; - provenance and fork parent. The release signature authenticates that full graph. Each referenced artifact also retains its own hash and signature, so an inspector can verify both the package and its components. ## Lifecycle ```mermaid flowchart LR Draft --> Validate Validate --> Sign Sign --> Publish Publish --> Install Install --> Run Run --> Upgrade Upgrade --> Run Run --> Rollback Rollback --> Run Publish --> Fork Publish --> Revoke ``` ### Draft The author works with readable schema, pipeline, surface, and release files. References may use local paths or qualified names. `rac app validate`, `build`, and `inspect` exercise the local draft lifecycle. Drafts cannot be installed outside their development workspace. ### Validate Local validation rejects unknown TOML fields, malformed pipeline graphs, incompatible entity merge policies, unsupported v1 surface/action shapes, dangling references, undeclared effect capabilities, direct self-dependencies, and incompatible resolved dependency versions. Building also resolves referenced pipeline sources to exact `PipelineSpec` hashes. Resolved dataset sources and sinks must be covered by matching read/write capabilities. An `http_fetch` stage requires a matching network capability, and an authenticated fetch also requires a secret capability matching the referenced secret name. The same resolution check runs in `rac app validate`. Publication validation additionally rejects unknown schema fields and tags; binds authored source bytes to the exact normalized manifest, resolved package graph, and release digest; and verifies the transitive dependency graph, descriptor and artifact registry evidence, runtime compatibility, route ownership, publisher keys, and migrations through a release-bound receipt. A local scaffold report may omit checks that need a registry. A publishable verdict is separate and fail-closed: a skipped required gate produces an incomplete release rather than a publishable one. Runtime v1 also validates parameterized pipeline actions as a signed, four-field filter binding: input key, destination column, comparison operator, and scalar kind. Partial bindings are invalid. `invoke_function` actions are rejected at publication until the client host has an authenticated invocation transport and an ABI-compatible input/output encoder. ### Sign and publish The publisher attests to the publisher-independent package digest, binding its signer identity to those exact contents. Publication stores immutable release metadata, the attestation, content references, and the verifier's signed receipt in the managed registry. An owner can create a private catalog projection for trusted account or tenant grantees, or submit the exact current release for public review. Public discovery requires an operator approval recorded in the append-only app catalog review log. Native function references are resolved against the dedicated DTS code registry. Pipeline execution and future runtime materialization require the exact function name, source-AST hash, artifact hash, ABI, symbol, target, and verification evidence. The registry keeps the function-to-artifact association append-only, so rebuilding the same AST cannot make an older signed release unresolvable. ### Install Installation validates the release and dependency closure, records accepted grants, registers its verified entity descriptors, and pins the exact release for a tenant. The registry signs the complete mutable installation projection, including its state, grants, projected revocation metadata, and monotonically increasing revision. Remote clients verify that attestation and the immutable publication receipt before persisting or activating the bundle. Discovery permission and installation permission are distinct. The Apps UI lists owner, grantee, and approved-public catalog scopes. A private share grants read/discovery permission over the stable `app_id`; it does not copy the publisher's installation or widen access to the publisher's datasets. Installation into the active workspace still requires tenant owner/admin authority and explicit acceptance of every required capability. Trusted contacts become eligible share targets only after their email matches an active, authenticated workspace member. The attestation issuance time is a second monotonic replay barrier within a single installation revision. The registry allocates it from persisted state while locking the installation, root release, and sorted transitive dependency closure. Clients reject older issuance times, require an equal issuance time to carry the same bundle hash, and retain a verified root revocation or dependency-driven suspension as terminal for that sequence and release. ### Upgrade and rollback An upgrade diff groups changes by: - schemas and migrations; - pipeline and transform revisions; - pages, bindings, and actions; - dependencies and assets; - newly requested or broadened capabilities; - compatibility with stored data and the client runtime. The installation pin moves only after validation and approval. Rollback points to a previously accepted compatible release. Append-only data and operation history remain intact. ### Fork and revoke A fork receives a new project and publisher identity with provenance pointing to the source release. Data is copied or granted through a separate explicit operation. Revocation blocks new installation and dependency resolution. Existing installations follow policy: warn, quarantine, disable, or roll back to a known release. The decision and reason remain auditable. ## Capabilities Capabilities are names and scoped parameters, never embedded credentials. | Class | Examples | Enforcement point | |---|---|---| | Dataset | Read/write a named app dataset | Engine authorization and installation grants | | Network | Connect to an allowlisted service or domain | Server egress or client host policy | | Secret | Resolve a named server-side secret | Server secret resolver; values never enter the release | | Device | Camera, microphone, notifications, location, files | Browser/Capacitor host plus OS permission | | Background | Schedule, push subscription, background sync | Server scheduler or native host | | Cross-app | Invoke or read an explicitly exported contract | Installation dependency and grant closure | Dependencies contribute their own capability requirements. Installation shows the transitive closure and records which release requested each grant. An upgrade that broadens that closure requires renewed approval. ## Server and client execution boundaries The server remains authoritative for identity, authorization, secrets, privileged network access, large dataset scans, and durable writes. Deterministic client expressions may run over rows already available to the installed application. Optimistic client operations become authoritative only after server acceptance. WASM has three separate maturity boundaries: - A feature-gated server request-handler host is implemented with local unary, streaming, and WebSocket fixtures. Production routing does not currently select it. - The deployed dataflow executor provides a default-on, capability-limited Wasmtime UDF tier with fuel, memory, and wall-time bounds and no WASI. Its other callable tiers are built-in operations, trusted native batch transforms, and Firecracker isolation for opted-in untrusted native/Python workloads. The backend is implemented; the first WASM route remains staged for publication. - The portable Rust/WASM runtime verifies strict installed bundles, binds durable canonical-CBOR state to the installation/tenant/user/site identity, queues and replays CBOR entity operations through Capacitor Preferences, preserves state across a verified release rebind, hydrates exact entities in batches, and sends causal metadata to the descriptor-bound server merge path. Custom client transforms and arbitrary descriptor-generated subscriptions remain planned. The authenticated service response supplies the registry verifier key. The runtime pins that key with the durable bundle and refuses replacement or sequence rollback. Offline use therefore inherits the trust of the previous authenticated exchange. Persisting the key beside the bundle cannot defend against an attacker who can replace the complete local storage record; a native hardware-backed trust anchor would be a separate host integration. Registry signing-key rotation retains receipt continuity. Atomically replace the existing `DATA_ENGINE_SIGNING_KEY_FILE` contents with one 64-hex seed per line: the new current seed first, followed by every retained prior seed. The optional `DATA_ENGINE_SIGNING_KEYRING_FILE` can hold additional retired seeds. Keep an old seed available while any installed release receipt names its public key; installation refresh and lifecycle updates fail closed when that exact key is unavailable. These paths may share artifact and ABI primitives. Their deployment status and capability sets remain explicit. ## Data sharing Application sharing and dataset sharing solve different problems: - catalog visibility lets a principal discover release metadata; - installation permission lets a workspace pin and run a release; - dataset grants let principals read selected application data; - write authority remains a separate scoped grant and server policy; - public data visibility does not imply public application publication, and a public application does not imply public user data. The existing append-only dataset-share record, grant id, catalog review verdict, and soft revocation provide the starting primitives for shared app data. Application discovery and installation grants are implemented separately from dataset access, so sharing an app never grants its data implicitly. ## Publication gates A release is eligible for managed publication only when: 1. its wire bytes contain no unknown schema fields or tags and reproduce the claimed package digest; 2. its authored source bytes or source hash bind to the exact normalized manifest and resolved release graph; 3. every artifact is available under its declared hash; 4. every pipeline parses, lowers, and resolves exactly; 5. every schema reference and binding type-checks; 6. every requested capability is declared and reviewable; 7. dependencies are exact, acyclic, and compatible; 8. migrations are additive or carry an approved explicit procedure; 9. the golden application conformance suite passes for the affected contract; 10. the release has a supported client/runtime compatibility range; 11. the catalog audience and revocation policy are set; 12. the publisher attestation verifies against the package digest and signer identity; 13. the verifier returns the opaque receipt bound to all of this evidence. A local unsigned build cannot produce that receipt by itself. The managed publication path issues it after the registry-backed checks pass; public self-service publication remains future work. The first public proof is the [collaborative board](/develop/pipeline-apps/collaborative-board). Return to the [Pipeline Apps mental model](/develop/pipeline-apps/overview) for the artifact overview. --- # Incident Triage Source: https://docs.redgold.ai/develop/pipeline-apps/incident-triage Incident Triage packages a small incident register without a dedicated host page, renderer component or application-specific runtime branch. Its source is `apps/incident-triage/app.toml`; the native record remains in `crates/shared/schema/app-incident-triage/src/lib.rs`. ## Supported workflow The Incidents page starts empty. Create an incident with a title, severity and owner; impact and summary are optional text. Open a row to edit its full record. Severity is free text, with `sev1` through `sev4` suggested by the form. New incidents have status `open`. Resolve and reopen update only `status`, so they preserve title, owner, severity, impact and summary. The list hides resolved records by default; open **Filters** and uncheck **Hide resolved incidents** to open them again. Long impact and summary values remain intact when selecting and editing a row. The app uses the same durable entity queue and explicit installation grants as the [collaborative board](/develop/pipeline-apps/collaborative-board). An online, visible installation requests bounded foreground snapshots with a minimum 15-second interval and failure backoff. Reconnect and settled actions also request refresh. Unsaved form values and the selected detail are preserved; reopen a record from the refreshed list to see another client's changes. ## One package, existing host | Package declaration | Shared implementation | | --- | --- | | Native `Incident` schema and seven signed fields | Descriptor validation, typed CBOR records and per-field merge | | `incident-list` pipeline | Authorized dataset read, complete-row filters, deterministic sort and projection | | Form and list bindings | Rust/WASM binding interpreter and the generic Vue renderer | | Create/edit/resolve/reopen actions | Durable entity operations, optimistic projection and explicit field masks | | Fixed `all` collection group | The same grouped collection hydration used by board comments | | `foreground_snapshot_v1` | The installed host's bounded foreground refresh scheduler | The release requests read and write access only to `app_incident_triage.Incident` and invocation only of `incident-list`. Timeline, hypothesis and next-action records have existing native examples but are outside this release. No network, secret, notification or infrastructure capability is requested. ## Author, build and install ```bash rac app validate apps/incident-triage/app.toml rac app build apps/incident-triage/app.toml rac des spec publish --manifest apps/incident-triage/pipelines/incident-list.toml rac app publish apps/incident-triage/app.toml rac app install incident-triage --version 0.1.2 \ --installation-id incident-triage-example \ --grant incident-read,incident-write,incident-pipelines ``` Publication requires authenticated managed-registry authority and exact pipeline and descriptor references. A local build is an unsigned candidate; it does not authorize installation. Follow the [release lifecycle](/develop/pipeline-apps/release-lifecycle) for publication and grant review. Add the workspace's tenant identifier only for tenant scope; omit it for personal scope. The installation opens through the shared `/apps//run` route. Agent documentation travels with the release and is available through `rac app docs `. ## Bounds and authoring lessons The signed read returns at most 200 complete incidents, sorted by status, severity, title and id. Open records sort before resolved records. Each list page shows 25 records; this is local pagination over that snapshot, not server-side history pagination. Pending local operations merge into the same fixed group, whose shared runtime limit is 256 items. This release does not claim a complete incident history, arbitrary subscriptions or conflict-free text editing. The previous example sorted on `updated_at_ms`, which the native record does not define, and rendered a seeded incident without durable hydration. This version uses only declared fields and empty initial state. Its incomplete next-action prototype is excluded from the published graph. These repairs belong in the app package; the existing host already provides the required primitives. Desktop and mobile browser checks exercise the shared web host. They do not establish Android or iOS device conformance. Notifications, on-call rotations, timeline editing and infrastructure actions remain outside this app's scope. --- # App layout and authoring previews Source: https://docs.redgold.ai/develop/pipeline-apps/presentation App layout is authored independently of stored entity schemas. The engine owns typed actions, permissions, synchronization, durable records and server business rules. The presentation compiler gives authors flex/grid composition, typography, spacing, themes and responsive containers within that existing contract. ## Author a page Keep actions, entities, pipelines and capabilities in `app.toml`. A page declares exactly one of the existing `root` tree, an embedded `template`, or a relative `ui` file. Referenced files are embedded into the authored snapshot before signing, so publication can reproduce the tree without the author's filesystem. ```toml [app] # Other identity/version fields remain required. minimum_runtime_version = "1.2.0" [[views]] id = "main" name = "Main" initial_page = "home" [views.theme] accent = "#176b61" background = "#f4f3ee" surface = "#ffffff" text = "#203633" muted = "#667873" border = "#dbe1da" font = "Inter, system-ui, sans-serif" [[views.pages]] id = "home" route = "/" title = "Committees" sites = ["web"] ui = "ui/home.vue" ``` ```html ``` `choose_committee` must be a declared action. A select stores the chosen scalar identity in `action_input.values.committee_id` and carries the complete option record in `action_input.item`. String and numeric identities retain their types. Use entity hydration to populate options; people choose record names, not raw foreign keys. A select belongs inside a form even when its change action is independent of submission. Options are bounded to 500 unique identities. ## Supported template subset This is a declarative source format, not a Vue runtime. Quote attribute values and close every element, including void controls (``). Bare boolean attributes such as `required`, `disabled` and `submit` mean `true`. XML character references such as `&` and numeric references are accepted. | Source | Native behavior | | --- | --- | | `div`, `section`, `header`, `footer`, `aside`, `article`, `main`, `nav`, `ul`, `ol`, `figure` | Semantic `box` containers | | `h1`–`h4`, `p`, `span`, `strong`, `em`, `small`, `li`, `label`, `figcaption`, `blockquote` | Text leaves; inline boxes when they hold elements or several interpolations | | `img`, `textarea`, `a href="/page"` | `image`, multiline `input`, `navigation` | | Existing portable component names | Existing typed components | | `:prop="$state.path"` | Read binding to local state | | `$item.path`, `$item`, `$index` inside list templates | Read the current record/index | | `{{ $state.path }}` in text | Interpolation; any number per element, mixed with inline elements | | `@click="action"`, `@submit="action"`, `@change="action"` | Declared button/form/select actions | | `v-if="$state.ready"`, `v-show` | Render only when the bound value is boolean `true` | | `v-if="!$state.ready"`, `v-else` | Render unless the value is `true`; `v-else` negates the previous sibling's condition | | `v-for="(row, i) in $state.rows"` | A plain list whose rows join the parent's flex/grid; `row.x` reads `$item.x` | | `aria-label="..."` on containers | Accessible name for a landmark or region | | `tab-label="Overview"` | Label a direct child of tabs | Rich text works as it does on a web page: `

Due {{ row.due }} · {{ row.budget }}

` compiles into inline spans that keep the authored spacing. Labels of buttons, badges and links take one interpolation without surrounding text. `v-for` renders up to 100 rows per page. A loop's `v-if` filters rows when it reads the loop alias. When it reads other state, it guards the whole loop. A nested loop reads only its own alias. `:key` is accepted and ignored. No scripts, imports, arbitrary expressions, event handlers, transforms, DTDs or processing instructions execute through this source. `v-else-if`, `v-model`, `v-html`, `:class` and `:style` are rejected with a hint. Derive display state in action flows and choose between variants with `v-if`/`v-else`. There is one root and optionally one `