---
title: 'Git Storage'
---

This document defines the local code-hosting target for Clawdie.

## Decision

Use a dedicated shared FreeBSD jail named `git` by default for local code
storage. Operators may override the jail name with `GIT_JAIL_NAME`, but it is no
longer derived from `ASSISTANT_NAME`.

Initial scope:

- bare repositories by default
- optional later Forgejo Web UI on the same jail role
- no CI
- no public exposure by default

This keeps code storage simple and reduces dependence on external remotes during
bootstrap, maintenance, and recovery.

## Why

- lower operational complexity than introducing a forge immediately
- easy to mirror from Codeberg without changing public workflow
- fits the current service-jail design
- clean separation from:
  - the host orchestrator
  - PostgreSQL (`DB_RUNTIME=host` or optional `db` jail)
  - `cms` content stack

## Jail Shape

- jail name: `git` by default; override with `GIT_JAIL_NAME`
- hostname: `git.<agent>.home.arpa`
- role: persistent internal Git Service
- preferred storage path: `/srv/git`
- registry/default slot: `<subnet>.2`

`infra/jails.yaml` defines the default git slot as `.2`. A live install may
override the actual address through `.env` with `WARDEN_GIT_IP`; live state and
`.env` win when answering what is running now.

The installer stores this as:

- `CODE_HOSTING_MODE=external|git|gitea`
- `REMOTE_GIT_URL=...`
- `FEATURE_GIT=true|false`
- `FEATURE_GITEA=true|false`
- `WARDEN_GIT_IP`
- `GIT_JAIL_NAME`

Mode meanings:

- `external` = bootstrap from a remote git URL only
- `git` = plain local git storage in the `git` jail
- `gitea` = local git plus the optional Forgejo application layer

Recommended default:

- current installs default to `git`

## First Bootstrap Goal

The first supported target is:

1. create the `git` jail
2. install `git`
3. create `/srv/git`
4. create one or more bare repositories
5. allow local clone/push from host and future worker/cms tooling

This stage does not require nginx, a public UI, or a separate database.

## Recommended Workflow

Keep public and local remotes separate.

- `origin` = Codeberg
- `git` = local bare repository in the `git` jail

If `CODE_HOSTING_MODE=external`, keep the bootstrap path simple:

- `origin` = `REMOTE_GIT_URL`

If `CODE_HOSTING_MODE=git`, use:

- `origin` = Codeberg
- `git` = local git jail

If `CODE_HOSTING_MODE=gitea`, use:

- `origin` = Codeberg
- `git` or `forgejo` = local Forgejo-backed remote

That allows:

- local-first clone/push inside the host
- later push or mirror upstream when wanted
- reduced dependence on external network availability

When `CODE_HOSTING_MODE=external`, the installer also captures
`REMOTE_GIT_URL` for bootstrap and clone operations.

## Non-Goals

Not part of the first bootstrap implementation:

- Forgejo provisioning by default
- full Codeberg-like forge
- public HTTP UI
- SSH key management for the git jail
- automatic mirroring

Those can be layered on later if the plain git jail proves useful. The first
bootstrap target remains plain git storage.

## First Repository Layout

The first useful filesystem shape inside the `git` jail is:

```text
/srv/git/
  Clawdie-AI.git
```

The repository should be:

- bare
- internal-first
- mirrored from the current repo or the configured upstream remote
- clonable from host-side tooling and future jailed workflows

Recommended first command shape after bootstrap:

```bash
git clone --mirror https://codeberg.org/Clawdie/Clawdie-AI.git /srv/git/Clawdie-AI.git
```

## Related Files

- [setup/git.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/git.ts) — git jail provisioning
- [setup/forgejo.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/forgejo.ts) — optional Forgejo layer
- [setup/install.ts](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/setup/install.ts) — install orchestrator
- [git-jail-bootstrap.yaml](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/infra/ansible/playbooks/git-jail-bootstrap.yaml)
- [ansible-freebsd skill](https://codeberg.org/Clawdie/Clawdie-AI/src/branch/main/.agent/skills/ansible-freebsd/SKILL.md)