Skip to content

docs: enrich CLAUDE.md with quickstart, conventions, architecture #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ashsolei wants to merge 1 commit into
base: main
Choose a base branch
from
+69 −1
Open

docs: enrich CLAUDE.md with quickstart, conventions, architecture #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 69 additions & 1 deletion CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,73 @@
@AGENTS.md
# CLAUDE.md — OpenShell (AiFeatures fork)

Upstream: NVIDIA/OpenShell — safe, private runtime for autonomous AI agents with sandboxed execution and declarative YAML policies. Built agent-first in Rust. See AGENTS.md for the full agent instruction surface.

## Quick Start

```bash
# Install binary (recommended)
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh

# Or via PyPI (requires uv)
uv tool install -U openshell

# Create a sandbox for Claude (Docker must be running)
openshell sandbox create -- claude
```

## Development

```bash
# Full local CI (lint + compile + tests) — run before opening a PR
mise run ci

# Unit tests only
mise run test

# End-to-end (requires running cluster)
mise run e2e

# Pre-commit checks (lint, format, license headers)
mise run pre-commit
```

Always use `uv` for Python commands. Always prefer `mise` commands over direct docker/cargo invocations.

## Architecture

Rust workspace with crates in `crates/`:

| Crate | Purpose |
| --- | --- |
| `openshell-cli` | User-facing CLI binary |
| `openshell-server` | Control-plane API, sandbox lifecycle, auth boundary |
| `openshell-sandbox` | Container supervision, policy-enforced egress routing |
| `openshell-policy` | Filesystem, network, process, and inference constraints |
| `openshell-router` | Privacy-aware LLM routing |
| `openshell-ocsf` | OCSF v1.7.0 structured logging (security events) |
| `openshell-bootstrap` | K3s cluster setup, image loading, mTLS PKI |
| `openshell-core` | Common types, config, error handling |

Additional: `python/openshell/` (Python SDK + PyPI packaging), `proto/` (gRPC contracts), `deploy/` (Docker, Helm, K8s manifests).

## Conventions

- Conventional commits: `feat(scope):`, `fix:`, `docs:`, `chore:`, `ci:`, `perf:`
- Never mention Claude or AI agents in commit messages
- Scope changes to the issue at hand — no unrelated changes in a branch
- Security findings: dual-emit OCSF events (domain event + DetectionFinding)
- Never log secrets or query parameters in OCSF messages

## Shared Resources

| Resource | Location |
| --- | --- |
| Reusable CI workflows | `Ai-road-4-You/enterprise-ci-cd` |
| Agent skills | `.agents/skills/` |
| AgentHub | `~/AgentHub/` (central hub, 12 MCP servers) |

## AgentHub

- Central hub: `~/AgentHub/`
- Skills: `.agents/skills/` (symlinked to AgentHub shared skills)
- MCP: 12 servers synced across all agents
Expand Down
Loading