Skip to content
Clawdie

Git Storage

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

Decision

Section titled “Decision”

Use a dedicated FreeBSD jail named {agent}-git for local code storage.

Initial scope:

  • bare repositories only
  • optional later Gitea upgrade 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

Section titled “Why”
  • lower operational complexity than introducing Gitea immediately
  • easy to mirror from Codeberg without changing public workflow
  • fits the existing jail-per-role design
  • clean separation from:
    • the host orchestrator
    • db PostgreSQL
    • cms content stack

Jail Shape

Section titled “Jail Shape”
  • jail name: {agent}-git
  • hostname: git.<agent>.home.arpa
  • role: persistent internal service
  • preferred storage path: /srv/git

IP address is assigned dynamically via WARDEN_GIT_IP — there is no fixed slot for the git jail in the current layout (.4 is cms, .5 is llama-cpp).

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

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 Gitea application layer

Recommended default:

  • all current-main installs default to git

First Bootstrap Goal

Section titled “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.

Section titled “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 gitea = local Gitea-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

Section titled “Non-Goals”

Not part of the first bootstrap implementation:

  • Gitea provisioning
  • 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 installer may already expose Local Gitea as a future mode, but the first bootstrap target remains plain git storage.

First Repository Layout

Section titled “First Repository Layout”

The first useful filesystem shape inside the git jail is:

/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:

Terminal window
git clone --mirror https://codeberg.org/Clawdie/Clawdie-AI.git /srv/git/Clawdie-AI.git
Section titled “Related Files”