> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akua.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Agents and installation repositories
> How AI agents read, prepare, and review changes to Akua installations through their git repositories
Every installation on Akua lives in its own git repository. That repository is the surface AI agents work against: clone it for context, fork it to prepare a change, and review the result before it reaches the deployed branch. The same primitives a human operator uses through `git` are what an agent uses through code.
Repository change requests are the review boundary for agent-authored source or configuration changes. Agents can inspect existing work, create a fork-backed change request, push scoped commits, and ask a human or policy gate to accept it.
## Why a repository is the right surface for agents
An installation's repository is a small, well-typed world:
* **`inputs.yaml`**: what the customer chose. Read-only context for an agent debugging a deploy.
* **`package.k`**: the composition logic. The exact lever for "add a sidecar", "patch a field", "swap an image registry".
* **`manifests/`**: the rendered output. Diffable against any previous deploy.
* **`upstream/`**: the pinned source. Stable across renders.
Agents don't need a custom API for "edit this deployment". They need git. Every modern coding agent already knows how to clone, edit, branch, and submit a diff. Akua makes the deployment look like a normal repository so those skills transfer directly.
## Repository access
### Read installation context
Mint a [read-only token](/apis/authentication) for your workspace and clone any installation's repository. The token can fetch but cannot push, so an agent reading context can't accidentally modify the deployment.
```bash theme={null}
# Mint a read-only token via the dashboard, then:
git clone https://:@git.akua.dev//.git
cd
# Agent reads the relevant files
cat inputs.yaml
cat package.k
ls manifests/
```
This is the foundation for any agent that diagnoses a deployment, summarizes a configuration, or compares two installations. The tokens enforce the boundary: a leaked read-token cannot push, regardless of how it ends up misused.
### Prepare reviewable changes
When an agent needs to change a deployment, it should create a repository change request instead of pushing to the deployed branch. The change request creates or references a fork repository, exposes a scoped token for that fork, and keeps the review lifecycle in the API.
### The shape
A repository change request is a typed object on Akua that wraps a git fork:
* **`parent_repository_id`**: points at the parent installation's repository
* **`fork_repository_id`**: points at the fork that contains the proposed commits
* **`expires_at`**: a deadline; abandoned change requests are reaped by policy
* **`change_type`**: what flavour of change: `manifest_patch`, `inputs_change`, or `package_change`
* **A reviewer-facing diff**: rendered in the dashboard for human review
An agent or human creates a repository change request, pushes commits to its fork, and the dashboard renders the diff. A human with accept rights accepts; Akua validates the fork, updates the parent repository, renders the installation, and deploys the result. Rejections close the change request; expired change requests are garbage-collected.
### Why three change types
Different changes carry different blast radius, so they get different review surfaces:
| Change type | What changes | Review surface |
| ---------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `manifest_patch` | A targeted patch to one or more rendered resources, expressed as a structured patch (not free-form YAML). | Side-by-side patch + affected-resources list. |
| `inputs_change` | A diff in `inputs.yaml`. The reviewer sees both the input diff and the resulting manifest diff. | "Before" + "after" rendered manifests with field-level highlights. |
| `package_change` | A diff in `package.k` (composition logic). | Full source diff + render of both versions. |
The three change types let Akua gate review tooling appropriately: an inputs change is usually safer than a composition change, and the UI can lead with that distinction.
### Manifest-path protection
Repository change requests never touch `manifests/` directly. They edit the source (`inputs.yaml`, `package.k`) and Akua re-renders. This keeps the rendered tree authoritative and prevents an agent from sneaking changes that the source files don't reflect: every byte your cluster applies is reproducible from the repository's source.
### Per-repo token scoping
Repository change request tokens are scoped to the fork repository and a requested access level. A token an agent uses to push to a fork should only push to that fork, not to the deployed branch and not to any other installation repository.
## Designing agents against this model
If you're building an agent that integrates with Akua, design for repository change requests:
1. **Default to read-only.** Mint a read scope token unless you have a clear reason for write. It's the smallest surface and the easiest to revoke.
2. **Compute diffs, don't write to the deployed branch.** Push to the repository change request fork and let a human or policy gate review it.
3. **Stay in the source files.** Edits to `inputs.yaml` and `package.k` survive re-renders and updates. Edits to `manifests/` get clobbered on the next render.
4. **Hash before you push.** Akua skips no-op deploys based on the manifest hash, so equivalent edits produce no churn (but only if your changes don't pull in irrelevant whitespace or ordering noise).
5. **Time-box your work.** Repository change requests carry `expires_at`, and abandoned drafts are reaped. Build agent loops that close their own change requests on completion or failure.
## Related topics
The git-backed model behind every installation.
Edit inputs, patch resources, and review repository changes.
Endpoints, parameters, try-it playground.
Mint API tokens for agent access.