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.
Choose one of the two development setups:
All dev tools are packaged in a container — no need to install toolchains on your host.
See Distrobox Dev Environment to get started.
Install tools directly on your host.
- git
- gh CLI: Install and authenticate with
gh auth login(required for fork workflow; use--no-forkif you only need read-only access) - Go, Node.js, buf, kubectl, kind, jira CLI (see Setup for details)
# 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-forkThe bootstrap script clones all OSAC repos into the workspace. Each repo is an independent Git repository on its main branch. By default, remotes are named origin (upstream) and fork (push target). Use --fork-name <name> to choose a different push remote name (e.g., --fork-name origin for the conventional layout where origin is your fork and upstream is the project repo).
tools/resolve-remotes.sh detects remotes by URL, so all skills and hooks work regardless of naming.
Use --no-fork if you only need read-only access or are running in CI. To override fork repo names (e.g., if your fork of docs is named osac-docs), copy fork-overrides.sh.example to fork-overrides.sh and edit it.
| Component | Description |
|---|---|
| osac | Mono-repo: fulfillment-service + osac-operator + osac-aap + osac-installer + bare-metal-fulfillment-operator + osac-csi-driver (see subdirectories below) |
osac/fulfillment-service |
gRPC/REST API server with PostgreSQL backend — manages VirtualNetworks, Subnets, SecurityGroups, ComputeInstances |
osac/osac-operator |
Kubernetes operator for deploying OpenShift clusters via Hosted Control Planes |
osac/osac-aap |
Ansible Automation Platform roles and playbooks for VM and network provisioning |
osac/osac-installer |
Installation manifests, prerequisites, and demo scripts |
osac/bare-metal-fulfillment-operator |
Kubernetes operator for bare metal fulfillment |
osac/osac-csi-driver |
CSI storage driver, routes to vendor backends via fulfillment-service storage tiers |
| 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 |
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 |
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 rebuildThe 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 |
After running ./bootstrap.sh to clone all repos:
- kubeconfig: Place your cluster kubeconfig at
./kubeconfig(gitignored) - Tools:
buf,grpcurl,kubectl,jq,rg - Jira CLI:
go install github.com/ankitpokhrel/jira-cli/cmd/jira@latest(orbrew install ankitpokhrel/jira-cli/jira-cli) To update all repos to latestmainat any time, simply re-run:
./bootstrap.shosac-helpers.sh provides shell functions for common development workflows. Source it in your terminal to make them available:
source osac-helpers.shCreates an isolated git worktree for development:
osac-new-worktree feat/storage-qos
osac-new-worktree fix/login-bug
osac-new-worktree OSAC-1234This will:
- Create a new branch with the given name
- Set up a worktree at
../osac-workspace-<basename>(e.g.,../osac-workspace-storage-qos) - Switch into the new directory
- Run
bootstrap.shto clone all component repos - 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-qosNote: 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.
# Build and test fulfillment-service
cd osac/fulfillment-service
go build ./...
ginkgo run -r internal
# 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/ListSee 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
-
Cloned into a subdirectory as
osac-docs↩