# A Git-backed control plane for runtime configuration
Software behavior is controlled by code and configuration.
Code usually gets disciplined release mechanics: review, tests, CI, history,
rollback, and ownership. Runtime configuration often enters the system through
weaker paths: environment variables, dashboard edits, database rows, JSON blobs,
or one-off operational overrides.
That split is manageable while configuration is only static data. It becomes a
production risk when configuration changes behavior: which code path runs, which
limit applies, which account class receives different handling, which model an
agent uses, or what message a user sees during an incident.
At that point the configuration is no longer just data. It is production logic.
It needs a place where the whole decision can be reviewed, validated, tested,
released, loaded by applications, refreshed safely, and explained later.
rototo is that control plane for application runtime configuration. It stores
runtime configuration in a Git-backed workspace, keeps Git as the source of
truth, and gives applications a way to resolve named values by environment and
runtime context.
## Install rototo
The CLI is the first tool in the control loop because it lets engineers and CI
inspect, lint, and resolve the same workspace files that applications later load
through the SDK.
Install rototo with Cargo:
```sh
cargo install rototo
```
This release expects a current stable Rust toolchain. Verify the installed CLI:
```sh
rototo --version
rototo docs -p quickstart
```
## The production problem
The same application-facing value can have more than one correct answer:
- `dev`, `stage`, and `prod` may need different defaults.
- A reviewed account condition may need a different value.
- A structured value must match what application code expects.
- A running service may need to pick up a reviewed change without redeploying.
- An operator may need to know why one request received one value and another
request received a different value.
If those answers are split across application branches, deploy manifests,
feature flag rules, config tables, and undocumented exceptions, the final
behavior is hard to audit. The value may be visible, but the reason it was
selected is scattered. Validation may happen after the application has already
loaded bad configuration. Rollback may depend on knowing which system supplied
the answer.
rototo addresses that failure mode by making runtime configuration a workspace
that the CLI, CI, agents, and SDK can all inspect and evaluate in the same way.
## The control-plane boundary
A rototo workspace is a directory tree rooted at `rototo-workspace.toml`.
Configuration authors change files in that workspace, review them in Git, and
run lint and representative resolutions before release.
The workspace model is intentionally small:
- Environments name the runtime lanes where values are resolved.
- Context is the JSON object an application supplies with request-time facts.
- Qualifiers turn those facts into named reusable conditions.
- Variables are the named configuration values application code asks for.
- Schemas validate context and structured values before code depends on them.
Those concepts keep the boundary clear. Application code does not reimplement
configuration rules or read workspace files directly. It asks rototo for a
variable in an environment with a runtime context, and rototo evaluates that
request against the loaded workspace.
## How applications use it
The production loop is:
```text
review workspace change in Git
|
v
lint and test representative resolutions
|
v
release the workspace source
|
v
application loads the workspace at startup
|
v
application resolves variables with environment + runtime context
|
v
long-running service refreshes from the same workspace source
```
Successful refreshes affect future resolutions. Failed refreshes keep the last
successfully loaded workspace active, so a transient source failure does not
erase known-good configuration. Immutable commit refs are reproducible, but they
do not produce new refresh results because the ref itself does not move.
## One runtime decision
Suppose an application asks for `llm-agent-config` in `prod`.
The application supplies runtime context:
```json
{
"account": {
"plan": "enterprise",
"seats": 250
},
"request": {
"country": "DE"
}
}
```
rototo validates that context, evaluates qualifiers such as
`enterprise-accounts`, checks the `prod` rules for `llm-agent-config`, selects
the matching value, validates the selected JSON shape, and returns the value to
the application.
The important part is not only the returned value. The workspace records which
environment block was used, which condition matched, which value key was
selected, and what schema protected the application boundary.
## What changes
With this model:
- Runtime configuration changes move through Git review instead of ad hoc
mutation.
- Environment defaults and runtime exceptions live in one reviewed workspace.
- Structured values are validated before application code consumes them.
- Named conditions can be reused across variables.
- Representative resolutions can run before merge.
- Long-running services can refresh while preserving last-known-good behavior.
- Operators can investigate why a value was selected for a given environment and
context.
## Where to go next
Read [Why rototo](why-rototo.html) for the production failure modes that led to
this model.
Read [Quickstart](quickstart.html) to create a small local workspace, lint it,
and resolve one variable.
Read [Production workflow](production-workflow.html) for the Git-backed workflow:
schemas, qualifiers, variables, tests, application loading, refresh, and
observability.
Read [The rototo model](rototo-model.html) when you need the full vocabulary and
resolution flow.
Use the bundled CLI docs when working from a terminal:
```sh
rototo docs
rototo docs -p quickstart
rototo docs -p production-workflow
rototo docs -s refresh
```