Contributing
The Ambient Code Platform is open source. Whether you are fixing a bug, adding a feature, or improving documentation, contributions are welcome.
Prerequisites
Section titled “Prerequisites”| Tool | Version | Purpose |
|---|---|---|
| Go | 1.24+ | Backend, operator, public API |
| Node.js | 20+ | Frontend |
| Python | 3.11+ | Runner |
| Docker | Latest | Container builds |
| kubectl | Latest | Cluster access |
| Kind | Latest | Local Kubernetes cluster |
Local setup
Section titled “Local setup”# Start a local Kind cluster with all componentsmake kind-upOnce the cluster is running, access the platform at http://localhost:8080. Open a workspace and configure your API key in Project Settings before creating sessions.
Components
Section titled “Components”Each component has its own README with build instructions, test commands, and development tips.
| Component | Technology | README |
|---|---|---|
| Backend | Go + Gin | components/backend/ |
| Frontend | NextJS + Shadcn | components/frontend/ |
| Operator | Go + controller-runtime | components/operator/ |
| Runner | Python | components/runners/ambient-runner/ |
| Public API | Go + Gin | components/public-api/ |
Developer docs
Section titled “Developer docs”Internal developer documentation lives alongside these docs in docs/internal/:
| Section | What’s there |
|---|---|
| Architecture | System diagrams, component structure, session lifecycle |
| ADRs | Architectural Decision Records (Kubernetes-native, user token auth, language choices, etc.) |
| Design | Technical design docs (session reconciliation, runner-operator contract, status redesign) |
| Deployment | OpenShift deployment, OAuth, git authentication, S3 storage |
| Integrations | GitHub App, GitLab, Google Workspace setup |
| Local dev | Kind, CRC, and hybrid development setup |
| Testing | E2E testing guide, test overview |
| Observability | Langfuse, operator metrics, Grafana dashboards |
Contribution guidelines
Section titled “Contribution guidelines”See CONTRIBUTING.md for the full contribution workflow — branching strategy, pull request conventions, code standards, and commit message format.