# Overview

Writ is an open-source control plane for OpenTofu that you host yourself. You point `writ serve` at a Git repository of stacks. It plans the commits you or your CI job send it, waits for the approvals your rules require, and applies the plan it kept. Your CI jobs and laptops never hold a cloud credential or a state key.

Writ is at version 0. [Status and limits](/docs/status) lists what's built, how it's tested, and what's missing. Read it before you rely on Writ.

## Start here

New to Writ? Follow the [quick start](/docs/quick-start). You'll plan and apply a stack on your own machine, with no cloud account, then set Writ up for a team.

| If you want to | Read |
| --- | --- |
| Try Writ on your machine | [Quick start](/docs/quick-start) |
| Get the `writ` binary or the container image | [Install](/docs/install) |
| Run it for your team | [Run a control plane](/docs/run), then the [server config](/docs/config) |
| Plan and apply from CI | [Set up GitLab CI](/docs/set-up-gitlab-ci) |
| Know what it can't do yet | [Status and limits](/docs/status) |
| Compare it with what you use today | [Other control planes](/docs/compare), or [OpenTofu in plain GitLab CI](/docs/compare-gitlab-ci) |

## Concepts

How Writ works, and why it's built that way.

- [How the control plane works](/docs/serve): how `writ serve` plans a commit, runs OpenTofu apart from its keys, keeps state, checks drift, and decides who can do what.
- [Repositories](/docs/repos): how the control plane reads your code by commit.
- [Approvals](/docs/approvals): approval rules, who can approve, stale plans, and what each run records.
- [Secrets and the mask](/docs/secrets): how secrets stay out of everything `writ serve` stores or shows, and the cases the mask can't catch.
- [Policy](/docs/policy): Rego policies that check each plan when it's created and again before its apply.

## Guides

One task each, step by step.

- [Run a control plane](/docs/run): `writ serve --dev` for you, and a team's `writ serve`.
- [Sign in](/docs/sign-in): `writ login` and the control UI.
- [Add a repository](/docs/add-repository): a local repository or a GitLab project.
- [Set up GitLab CI](/docs/set-up-gitlab-ci): the plan, approve, and apply jobs.
- [Approve and apply a plan](/docs/apply): by id, after a merge, and with an override.
- [Adopt a state](/docs/adopt-state): bring in a state Writ didn't write.
- [Write and test a policy](/docs/write-a-policy): Rego, `conftest`, and the examples.
- [Import many objects](/docs/import-bulk): write code for objects you already run, in one pass.
- [Use Writ with an agent](/docs/agents): the skill `writ agent init` installs, and `writ mcp`.

## Reference

Exact values, flags, routes, and messages.

- [Commands](/docs/commands): every command, flag, and exit code.
- [Server config](/docs/config): every setting of the `writ serve` config.
- [API](/docs/api): every route, token checks, and limits.
- [Errors](/docs/errors): each error class, its exit code and status, and what to do.
- [JSON output](/docs/json-output): the contract for every `--json` document.
- [Control database](/docs/database): what `writ serve` keeps.
- [Policy input and built-ins](/docs/policy-reference): what a policy reads and can call.
- [Reference for agents](/docs/agent-reference): the tools of `writ mcp`, and how to recover from each refusal.
- [Glossary](/docs/glossary): the terms these pages use.

## Contribute

- [Development](/docs/development): how to build and test Writ.
- [Architecture](/docs/architecture): the package map, and the decisions behind it.
- [Writing style](https://github.com/mr-karan/writ/blob/main/docs/style.md): the voice and terms these pages follow.
