OSAC Project

Development workspace for the Open Sovereign AI Cloud (OSAC) project. This repo provides a meta-workspace that bootstraps all OSAC components for cross-component development and testing, with AI-assisted workflows for Claude Code, Cursor, and Gemini CLI.

Prerequisites

Choose one of the two development setups:

Option A: Distrobox (recommended)

All dev tools are packaged in a container — no need to install toolchains on your host.

• git
• make
• podman and distrobox

See Distrobox Dev Environment to get started.

Option B: Local toolchain

Install tools directly on your host.

• git
• gh CLI: Install and authenticate with gh auth login (required for fork workflow; use --no-fork if you only need read-only access)
• Go, Node.js, buf, kubectl, kind, jira CLI (see Setup for details)

Getting Started

# Clone the workspace
git clone https://github.com/osac-project/osac-workspace.git
cd osac-workspace

# Bootstrap all component repos with fork setup (requires gh CLI)
./bootstrap.sh

# Or clone read-only without forking
./bootstrap.sh --no-fork

The bootstrap script clones all OSAC repos into the workspace. Each repo is an independent Git repository on its main branch with remotes configured as:

• origin = osac-project (upstream source, PR target)
• fork = your GitHub fork (push target for feature branches)

Use --no-fork if you only need read-only access or are running in CI.

Components

Repository	Description
fulfillment-service	gRPC/REST API server with PostgreSQL backend — manages VirtualNetworks, Subnets, SecurityGroups, ComputeInstances
osac-operator	Kubernetes operator for deploying OpenShift clusters via Hosted Control Planes
osac-aap	Ansible Automation Platform roles and playbooks for VM and network provisioning
osac-installer	Installation manifests, prerequisites, and demo scripts
osac-test-infra	Integration testing infrastructure
osac-ui	OSAC UI web console for managing cloud resources
enhancement-proposals	Design documents and enhancement proposals
docs1	Architecture documentation, diagrams, and design guides
host-management-openstack	Bare metal host management via OpenStack
bare-metal-fulfillment-operator	Kubernetes operator for bare metal fulfillment

What's Included

This workspace provides a pre-configured AI-assisted development environment:

File	Purpose
bootstrap.sh	Clones or updates all component repos, installs ai-workflows, and wires agent skill symlinks — re-run anytime to sync
osac-helpers.sh	Developer shell helpers — source to get worktree and workflow utilities
AGENTS.md	Tool-agnostic project instructions (Claude, Cursor, Gemini, Copilot) — build commands, architecture; bootstrap-linked skills for Claude/Cursor/Gemini; Copilot reads this file for conventions only
CLAUDE.md	Thin wrapper that loads AGENTS.md plus Claude-specific command syntax
tools/link-agent-skills.sh	Links .claude/skills, .cursor/skills, and .gemini/skills to canonical skills/
.claude/settings.json	Pre-approved shell commands (git, ls, cat, etc.) so Claude doesn't prompt for routine operations
AI-assisted-development-workflow.md	AI-assisted development workflow: Feature → PRD → Design → Jira sync → Implement
skills/	Canonical OSAC skill definitions (Jira, PRs, design review, release, demos) plus bootstrap-managed ai-workflows symlinks
.gitignore	Ignores cloned repos, .planning/, .claude/, .cursor/, .gemini/, credentials, editor files, and build artifacts

Distrobox Dev Environment

A containerized development environment is provided via distrobox, packaging all required tools (Go, Node.js, buf, kubectl, kind, gh, jira, Claude Code) in a Fedora 42-based container. This gives you a reproducible environment without installing toolchains on your host.

# Build the image and enter the distrobox
make enter

# Or run Claude Code directly inside the distrobox
make claude

# Pass flags to Claude Code
make claude ARGS="--resume"

# Check status of image and distrobox
make status

# Rebuild from scratch
make rebuild

The distrobox shares your home directory by default (override with HOME_DIR). All host files, SSH keys, and credentials are available inside the container.

Target	Description
make image	Build the container image
make enter	Enter the distrobox (creates on first run)
make claude	Run Claude Code inside the distrobox
make stop	Stop the running container
make rm	Remove the distrobox
make rebuild	Rebuild image from scratch and enter
make status	Show image and distrobox status

Setup

After running ./bootstrap.sh to clone all repos:

1. kubeconfig: Place your cluster kubeconfig at ./kubeconfig (gitignored)
2. Tools: buf, grpcurl, kubectl, jq, rg
3. Jira CLI: go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest (or brew install ankitpokhrel/jira-cli/jira-cli) To update all repos to latest main at any time, simply re-run:

./bootstrap.sh

Developer Helpers

osac-helpers.sh provides shell functions for common development workflows. Source it in your terminal to make them available:

source osac-helpers.sh

osac-new-worktree <branch-name>

Creates an isolated git worktree for development:

osac-new-worktree feat/storage-qos
osac-new-worktree fix/login-bug
osac-new-worktree OSAC-1234

This will:

1. Create a new branch with the given name
2. Set up a worktree at ../osac-workspace-<basename> (e.g., ../osac-workspace-storage-qos)
3. Switch into the new directory
4. Run bootstrap.sh to clone all component repos
5. If the branch name contains an OSAC Jira ticket (e.g., OSAC-1234), fetch the ticket summary and append it to .claude/CLAUDE.md

Each worktree is a fully independent workspace — you can work on multiple features in parallel without stashing or switching branches.

Clean up when you're done (run from the original osac-workspace directory):

# First, exit the worktree if you're still in it
cd ~/path/to/original/osac-workspace
git worktree remove ../osac-workspace-storage-qos

Note: Git will refuse to remove a worktree with uncommitted changes. Commit or stash your work first, or use git worktree remove --force if you're certain you want to discard the changes.

Tip: Add source /path/to/osac-workspace/osac-helpers.sh to your ~/.bashrc or ~/.zshrc so the helpers are always available.

Quick Reference

# Build and test fulfillment-service
cd fulfillment-service
go build
ginkgo run -r

# Test API against a running cluster
export KUBECONFIG=./kubeconfig
export NAMESPACE=<your-namespace>
ROUTE=$(kubectl get route -n $NAMESPACE fulfillment-api -o jsonpath='{.spec.host}')
TOKEN=$(kubectl create token -n $NAMESPACE admin)

# List resources via REST
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/virtual_networks" | jq
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/subnets" | jq
curl -sk -H "Authorization: Bearer $TOKEN" "https://$ROUTE/api/fulfillment/v1/compute_instances" | jq

# List resources via gRPC
grpcurl -insecure -H "Authorization: Bearer $TOKEN" $ROUTE:443 osac.public.v1.VirtualNetworks/List

AI-Assisted Development Workflow

See AI-assisted-development-workflow.md for the full workflow: Feature → PRD → Design → Jira sync → Implement.

Prerequisites: ./bootstrap.sh (installs ai-workflows and links agent skill directories), gh (authenticated), jira CLI, rg

After bootstrap, OSAC repo-local skills and ai-workflows (bugfix, implement, prd, design, e2e) are discoverable via .claude/skills/, .cursor/skills/, and .gemini/skills/ (each symlinked to skills/). See AGENTS.md for agent-specific paths and the full skill list.

See AGENTS.md and CLAUDE.md for detailed development instructions and conventions.

Footnotes

1. Cloned into a subdirectory as osac-docs ↩