OpenShell/CONTRIBUTING.md

Contributing to OpenShell

Prerequisites

Install mise. This is used to set up the development environment.

# Install mise (macOS/Linux)
curl https://mise.run | sh

After installing mise, activate it with mise activate or add it to your shell.

Shell setup examples:

# Fish
echo '~/.local/bin/mise activate fish | source' >> ~/.config/fish/config.fish

# Zsh
echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc

Project requirements:

• Rust 1.88+
• Python 3.12+
• Docker (running)

Getting Started

# One-time trust
mise trust

# Launch a sandbox (deploys a cluster if one isn't running)
mise run sandbox

Building the openshell CLI

Inside this repository, openshell is a local shortcut script at scripts/bin/openshell. The script will

1. Build openshell-cli if needed.
2. Run the local debug CLI binary under target/debug/openshell.

Because mise adds scripts/bin to PATH for this project, you can run openshell directly from the repo.

openshell --help
openshell sandbox create -- codex

Cluster debugging helpers

Two additional scripts in scripts/bin/ provide gateway-aware wrappers for cluster debugging:

Script	What it does
kubectl	Runs kubectl inside the active gateway's k3s container via openshell doctor exec
k9s	Runs k9s inside the active gateway's k3s container via openshell doctor exec

These work for both local and remote gateways (SSH is handled automatically). Examples:

kubectl get pods -A
kubectl logs -n openshell statefulset/openshell
k9s
k9s -n openshell

Main Tasks

These are the primary mise tasks for day-to-day development:

Task	Purpose
mise run cluster	Bootstrap or incremental deploy
mise run sandbox	Create a sandbox on the running cluster
mise run test	Default test suite
mise run e2e	Default end-to-end test lane
mise run ci	Full local CI checks (lint, compile/type checks, tests)
mise run docs	Build and serve documentation locally
mise run clean	Clean build artifacts

Project Structure

Path	Purpose
crates/	Rust crates
python/	Python SDK and bindings
proto/	Protocol buffer definitions
tasks/	mise task definitions and build scripts
deploy/	Dockerfiles, Helm chart, Kubernetes manifests
architecture/	Architecture docs and plans

Pull Requests

1. Create a feature branch from main
2. Make your changes with tests
3. Run mise run ci to verify
4. Open a PR with a clear description

Commit Messages

This project uses Conventional Commits. All commit messages must follow the format:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation only
• chore - Maintenance tasks (dependencies, build config)
• refactor - Code change that neither fixes a bug nor adds a feature
• test - Adding or updating tests
• ci - CI/CD changes
• perf - Performance improvements

Examples:

feat(cli): add --verbose flag to openshell run
fix(sandbox): handle timeout errors gracefully
docs: update installation instructions
chore(deps): bump tokio to 1.40

DCO

All contributions must include a Signed-off-by line in each commit message. This certifies you have the right to submit the work under the project license. See the Developer Certificate of Origin.

git commit -s -m "feat(sandbox): add new capability"

Use the create-github-pr skill to help with opening your pull request.