Skip to content

Commit f9f538d

Browse files
authored
1 parent b2233e8 commit f9f538d

79 files changed

Lines changed: 7741 additions & 915 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/create-github-issue/SKILL.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,21 @@ This project uses YAML form issue templates. When creating issues, match the tem
1717

1818
### Bug Reports
1919

20-
Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. Apply area or topic labels only when they are clearly known.
20+
Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. The diagnostic must identify the OpenShell version tested, whether the latest release or known fixes were checked, and whether possible duplicate issues were searched. If the agent cannot verify the latest release or search existing issues, say so explicitly instead of guessing. Apply area or topic labels only when they are clearly known.
2121

2222
```bash
2323
gh issue create \
2424
--title "bug: <concise description>" \
2525
--body "$(cat <<'EOF'
2626
## Agent Diagnostic
2727
28-
<Paste the output from the agent's investigation. What skills were loaded?
29-
What was found? What was tried?>
28+
- Skills loaded: <skills used during investigation>
29+
- OpenShell version tested: <version from openshell --version or other source>
30+
- Latest release checked: <version checked, or unable to verify>
31+
- Known fixes reviewed: <release notes / merged PRs checked, or unable to verify>
32+
- Possible duplicates reviewed: <existing issues searched, or unable to verify>
33+
- Findings: <what the agent found and tried>
34+
- Remaining reason for filing: <why this still appears to be a bug>
3035
3136
## Description
3237
@@ -44,6 +49,8 @@ What was found? What was tried?>
4449
- OS: <os>
4550
- Docker: <version>
4651
- OpenShell: <version>
52+
- Latest release checked: <yes/no and reason>
53+
- Possible duplicates checked: <yes/no and reason>
4754
4855
## Logs
4956

‎.agents/skills/debug-openshell-cluster/SKILL.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -268,6 +268,57 @@ kubectl -n openshell get configmap openshell-config -o jsonpath='{.data.gateway\
268268
kubectl -n <sandbox-namespace> get sandbox <sandbox-name> -o jsonpath='{.spec.template.spec.serviceAccountName}{"\n"}'
269269
```
270270

271+
If `topology = "sidecar"` is rendered under `[openshell.drivers.kubernetes]`,
272+
sandbox pods should have an `openshell-network-init` init container running
273+
`--mode=network-init`, an `agent` container running
274+
`openshell-sandbox --mode=process`, and an `openshell-supervisor-network`
275+
container running `--mode=network`. The init container owns nftables setup and
276+
should be the only sidecar topology container with `NET_ADMIN`. It also needs
277+
`CHOWN`/`FOWNER` to hand shared emptyDir state to the effective sidecar UID. The
278+
default binary-aware network sidecar runs as UID 0 with primary GID
279+
`sandbox_gid` and adds `SYS_PTRACE` plus `DAC_READ_SEARCH`. When
280+
`process_binary_aware_network_policy = false`, it runs as the configured
281+
non-root `proxy_uid` without those inspection capabilities. The pod `fsGroup`
282+
is set to `sandbox_gid` in both modes.
283+
284+
In sidecar topology only the network sidecar should mount the gateway bootstrap
285+
credentials (`openshell-sa-token` and `openshell-client-tls`). The process
286+
container should not receive `OPENSHELL_ENDPOINT`, gateway TLS env vars, the
287+
sandbox token file, or those credential mounts. Instead, the network sidecar
288+
serves policy and provider environment state over the Unix control socket from
289+
`OPENSHELL_SIDECAR_CONTROL_SOCKET` (`/run/openshell-sidecar/control.sock` by
290+
default). The process supervisor must be the first and only client. After
291+
validating its peer UID, GID, and PID, the sidecar unlinks the listener. If the
292+
connection later closes, the network sidecar exits non-zero so Kubernetes can
293+
restart it with a fresh listener. If the process supervisor fails before
294+
launching the workload,
295+
inspect both containers for control-socket bind, connect, bootstrap, or update
296+
errors. If new SSH/exec sessions do not pick up refreshed provider environment,
297+
inspect the network sidecar settings-poll logs and the process container logs
298+
for provider environment update handling; the process container should consume
299+
newer provider-env revisions without receiving gateway credentials.
300+
301+
The process container reports the workload entrypoint PID over the same control
302+
socket, and the network sidecar uses that PID for binary-scoped policy
303+
decisions through `/proc`. If rules with `policy.binaries` are unexpectedly
304+
denied, inspect the sidecar control logs and confirm the pod has
305+
`shareProcessNamespace: true`.
306+
The shared state directory should preserve `sandbox_gid` inheritance
307+
(`02775`). Sidecar SSH uses the Linux abstract socket
308+
`@openshell-sidecar-ssh`; the network sidecar verifies its peer PID before
309+
bridging gateway relay requests. No `ssh.sock` file should appear in the shared
310+
state directory.
311+
Inspect all three when sandbox registration or egress enforcement fails:
312+
313+
```bash
314+
kubectl -n openshell get configmap openshell-config -o jsonpath='{.data.gateway\.toml}' | grep -E '^\[openshell\.drivers\.kubernetes\]|^topology\s*='
315+
kubectl -n <sandbox-namespace> get pod <sandbox-pod> -o jsonpath='{range .spec.initContainers[*]}{.name}{" "}{.command}{"\n"}{end}'
316+
kubectl -n <sandbox-namespace> get pod <sandbox-pod> -o jsonpath='{range .spec.containers[*]}{.name}{" "}{.command}{"\n"}{end}'
317+
kubectl -n <sandbox-namespace> logs <sandbox-pod> -c openshell-network-init --tail=200
318+
kubectl -n <sandbox-namespace> logs <sandbox-pod> -c openshell-supervisor-network --tail=200
319+
kubectl -n <sandbox-namespace> logs <sandbox-pod> -c agent --tail=200
320+
```
321+
271322
### Step 6: Check VM-Backed Gateways
272323

273324
Use the VM driver logs and host diagnostics available in the user's environment. Verify:

‎.agents/skills/helm-dev-environment/SKILL.md‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -60,9 +60,25 @@ mise run helm:skaffold:dev
6060
mise run helm:skaffold:run
6161
```
6262

63+
**Supervisor sidecar topology** (build once and leave running):
64+
```bash
65+
mise run helm:skaffold:run:sidecar
66+
```
67+
68+
**Supervisor sidecar topology with TLS/mTLS enabled** (build once and leave running):
69+
```bash
70+
mise run helm:skaffold:run:sidecar-mtls
71+
```
72+
6373
Both commands build the `gateway` and `supervisor` images and deploy the OpenShell Helm
64-
chart. The `pkiInitJob` hook (a pre-install Job that runs `openshell-gateway generate-certs`)
65-
generates mTLS secrets on first install. Envoy Gateway opt-in; see the Optional Add-ons section below.
74+
chart. The sidecar profile renders an `openshell-network-init` init container for
75+
nftables setup and an `openshell-supervisor-network` runtime sidecar for proxying.
76+
Binary-aware policy mode runs that sidecar as UID 0 with `SYS_PTRACE` and
77+
`DAC_READ_SEARCH`; relaxed mode can run it as the configured proxy UID. The
78+
sidecar-mTLS profile reuses `ci/values-sidecar.yaml` and restores
79+
`server.disableTls=false` inline for Skaffold. The `pkiInitJob` hook (a pre-install
80+
Job that runs `openshell-gateway generate-certs`) generates mTLS secrets on first
81+
install. Envoy Gateway opt-in; see the Optional Add-ons section below.
6682

6783
The gateway Service uses ClusterIP. Access is via Envoy Gateway (port `8080`) or `kubectl port-forward`.
6884

@@ -74,7 +90,8 @@ create the Secret named `openshell-ha-pg` with a `uri` key, then run
7490
### TLS behaviour
7591

7692
`ci/values-skaffold.yaml` sets `server.disableTls: true`, so Skaffold-based deploys run
77-
plaintext by default. To test with TLS enabled, comment out that line and redeploy.
93+
plaintext by default. To test sidecar topology with TLS enabled, use
94+
`mise run helm:skaffold:run:sidecar-mtls`.
7895

7996
| Mode | `server.disableTls` | Gateway scheme |
8097
|------|---------------------|----------------|
@@ -126,6 +143,12 @@ openshell sandbox list --gateway-endpoint https://localhost:8090
126143
mise run helm:skaffold:delete
127144
```
128145

146+
For a sidecar-profile deployment:
147+
148+
```bash
149+
mise run helm:skaffold:delete:sidecar
150+
```
151+
129152
### Delete the cluster entirely
130153

131154
```bash
@@ -250,6 +273,7 @@ for dependencies still declared in `Chart.yaml`.
250273
| `deploy/helm/openshell/ci/values-gateway.yaml` | Envoy Gateway GRPCRoute + Gateway overlay |
251274
| `deploy/helm/openshell/ci/values-high-availability.yaml` | HA test overlay (`replicaCount: 2` with external PostgreSQL Secret) |
252275
| `deploy/helm/openshell/ci/values-keycloak.yaml` | Keycloak OIDC overlay |
276+
| `deploy/helm/openshell/ci/values-sidecar.yaml` | Supervisor sidecar topology overlay for Kubernetes e2e/dev |
253277
| `deploy/helm/openshell/ci/values-spire.yaml` | SPIFFE/SPIRE provider token grant overlay |
254278
| `deploy/helm/openshell/ci/values-spire-stack.yaml` | SPIRE hardened chart values for local dev |
255279
| `deploy/helm/openshell/ci/values-tls-disabled.yaml` | Lint-only: TLS + auth disabled (reverse-proxy edge termination) |

‎.agents/skills/triage-issue/SKILL.md‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ Query all open issues with the `state:triage-needed` label and process them in s
5151
gh issue list --label "state:triage-needed" --state open --json number,title --jq '.[].number'
5252
```
5353

54-
For each issue returned, run the full triage workflow (Steps 1-6). Report a summary at the end listing each issue and its classification.
54+
For each issue returned, run the full triage workflow (Steps 1-7). Report a summary at the end listing each issue and its classification.
5555

5656
## Step 1: Fetch the Issue
5757

@@ -89,7 +89,23 @@ Check whether the issue body contains a substantive agent diagnostic section. Lo
8989

9090
**If the diagnostic section is substantive**, proceed to Step 4.
9191

92-
## Step 4: Diagnose and Validate
92+
## Step 4: Check Reported Version and Known Fixes
93+
94+
Before deeper diagnosis, determine whether the report may already be fixed in a newer release.
95+
96+
1. Extract the reported OpenShell version from the issue body, Agent Diagnostic, environment section, logs, and comments. If no version is provided, record that as missing context and continue.
97+
2. Check current release information and known fixes when available:
98+
- `gh release list --limit 10`
99+
- `gh release view <tag>`
100+
- linked issues, merged PRs, release notes, and local git tags/history
101+
3. If network access or release metadata is unavailable, state the limitation in the triage comment instead of guessing.
102+
103+
If the issue targets an older OpenShell release and a newer release or merged PR appears to address the same behavior:
104+
105+
- If the reporter has already reproduced the issue on the fixed/current release, continue to Step 5.
106+
- If the reporter has not tested the fixed/current release, use the `fixed-in-release` classification in Step 6. Reference the fixing version and PR/issue when known, and ask for a fresh report or reopen if the issue still reproduces on that version.
107+
108+
## Step 5: Diagnose and Validate
93109

94110
Assess the report by investigating the codebase. Use the `principal-engineer-reviewer` sub-agent via the Task tool:
95111

@@ -114,20 +130,21 @@ Based on the sub-agent's analysis, also attempt to validate the report directly:
114130
- For inference and provider-topology issues: reference the `debug-inference` skill's known failure patterns
115131
- For CLI/usage issues: reference the `openshell-cli` skill's command reference
116132

117-
## Step 5: Classify
133+
## Step 6: Classify
118134

119135
Based on the investigation, classify the issue into one of these categories:
120136

121137
| Classification | Criteria | Action |
122138
|---------------|----------|--------|
123139
| **bug-confirmed** | Agent diagnostic and codebase analysis confirm a real defect | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Bug` issue type manually if needed |
124140
| **feature-valid** | Design proposal is sound, feasible given the architecture | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Feature` issue type manually if needed |
141+
| **fixed-in-release** | Report targets an older OpenShell release and a newer release or merged PR appears to address the behavior; no fixed/current-release reproduction is provided | Comment with the fixing version and PR/issue when known. Close as completed when the fix is clear, or request a retest if confirmation is still needed. Remove `state:triage-needed` when closing |
125142
| **duplicate** | An existing open issue covers this | Link the duplicate, close with comment |
126143
| **user-error** | The reported behavior is expected, or the issue is a misconfiguration | Comment with explanation and guidance, close |
127144
| **needs-more-info** | Report is substantive but missing critical reproduction details | Comment requesting specifics, keep `state:triage-needed` |
128145
| **needs-investigation** | Report appears valid but requires deeper analysis (spike candidate) | Label `spike`, remove `state:triage-needed` |
129146

130-
## Step 6: Post Triage Comment
147+
## Step 7: Post Triage Comment
131148

132149
Post a structured comment with the triage marker:
133150

@@ -136,7 +153,7 @@ Post a structured comment with the triage marker:
136153
>
137154
> ## Triage Assessment
138155
>
139-
> **Classification:** <classification from Step 5>
156+
> **Classification:** <classification from Step 6>
140157
>
141158
> ### Summary
142159
> <2-3 sentences: what was found, whether the report is valid>
@@ -148,7 +165,7 @@ Post a structured comment with the triage marker:
148165
> <Next steps: ready for spike, needs more info from reporter, can be closed, etc.>
149166
```
150167

151-
Apply the appropriate labels as determined in Step 5.
168+
Apply the appropriate labels as determined in Step 6.
152169

153170
**Do not apply `state:agent-ready`.** That is always a human decision.
154171

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,15 +9,20 @@ body:
99
1010
OpenShell is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`debug-openshell-cluster`, `debug-inference`, `openshell-cli`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md) for the full skills table.
1111
12+
Please also check the latest OpenShell release and search existing issues for possible duplicates before filing. If you cannot upgrade, retest, or search existing issues, explain why in the diagnostic.
13+
1214
- type: textarea
1315
id: agent-diagnostic
1416
attributes:
1517
label: Agent Diagnostic
1618
description: |
17-
Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try?
19+
Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try? Which OpenShell version did it test, and did it check the latest release, known fixes, and possible duplicates?
1820
placeholder: |
1921
Example:
2022
- Loaded `debug-inference` skill
23+
- Tested OpenShell v0.x.x
24+
- Checked latest release / known fixes: no matching fix found
25+
- Searched existing issues for duplicates: no matching issue found
2126
- Ran `openshell inference get` and `openshell provider get ollama`
2227
- Found `OPENAI_BASE_URL=http://127.0.0.1:11434/v1`, which is unreachable from the gateway
2328
- Updated the provider to use `host.openshell.internal`, but the issue persists because the gateway is remote
@@ -47,11 +52,13 @@ body:
4752
id: environment
4853
attributes:
4954
label: Environment
50-
description: OS, Docker version, OpenShell version, and any other relevant details.
55+
description: OS, Docker version, OpenShell version tested, whether the latest release and existing issues were checked, and any other relevant details.
5156
placeholder: |
5257
- OS: macOS 15.2 / Ubuntu 24.04 / Windows 11 + WSL2
5358
- Docker: Docker Desktop 4.x / Docker Engine 27.x
5459
- OpenShell: v0.x.x (output of `openshell --version`)
60+
- Latest release checked: yes / no, because ...
61+
- Possible duplicates checked: yes / no, because ...
5562
validations:
5663
required: true
5764

@@ -75,5 +82,9 @@ body:
7582
required: true
7683
- label: I loaded relevant skills (e.g., `debug-openshell-cluster`, `debug-inference`, `openshell-cli`)
7784
required: true
85+
- label: I checked the latest OpenShell release and either reproduced the issue there or explained why I cannot upgrade/test it
86+
required: true
87+
- label: I searched existing issues for possible duplicates or explained why I could not
88+
required: true
7889
- label: My agent could not resolve this — the diagnostic above explains why
7990
required: true

‎.github/workflows/branch-e2e.yml‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -121,16 +121,25 @@ jobs:
121121
include:
122122
- agent_sandbox_api: v1beta1
123123
agent_sandbox_version: v0.5.0
124+
topology: combined
125+
extra_helm_values: ""
124126
- agent_sandbox_api: v1alpha1
125127
agent_sandbox_version: v0.4.6
128+
topology: combined
129+
extra_helm_values: ""
130+
- agent_sandbox_api: v1beta1
131+
agent_sandbox_version: v0.5.0
132+
topology: sidecar
133+
extra_helm_values: deploy/helm/openshell/ci/values-sidecar.yaml
126134
permissions:
127135
contents: read
128136
packages: read
129137
uses: ./.github/workflows/e2e-kubernetes-test.yml
130138
with:
131139
image-tag: ${{ github.sha }}
132-
job-name: Kubernetes E2E (Rust smoke, Agent Sandbox ${{ matrix.agent_sandbox_api }})
140+
job-name: Kubernetes E2E (Rust smoke, ${{ matrix.topology }}, Agent Sandbox ${{ matrix.agent_sandbox_api }})
133141
agent-sandbox-version: ${{ matrix.agent_sandbox_version }}
142+
extra-helm-values: ${{ matrix.extra_helm_values }}
134143

135144
kubernetes-ha-e2e:
136145
needs: [pr_metadata, build-gateway, build-supervisor]

‎.github/workflows/sync-docs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ jobs:
9393
path: docs-website
9494

9595
- name: Install uv
96-
uses: astral-sh/setup-uv@d31148d669074a8d0a63714ba94f3201e7020bc3 # v8.3.0
96+
uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2
9797
with:
9898
version: "0.10.12"
9999

‎.packit.yaml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ jobs:
6666
trigger: commit
6767
branch: main
6868
owner: "maxamillion"
69-
project: "openshell"
69+
project: "nvidia-openshell"
7070
identifier: main-commit
7171
targets:
7272
- fedora-all
@@ -79,7 +79,7 @@ jobs:
7979
- job: copr_build
8080
trigger: release
8181
owner: "maxamillion"
82-
project: "openshell"
82+
project: "nvidia-openshell"
8383
targets:
8484
- fedora-all
8585
- epel-10

‎Cargo.lock‎

Lines changed: 3 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -258,6 +258,8 @@ Telemetry events are limited to anonymous operational categories and counts, suc
258258

259259
Opting out applies only to telemetry emitted by OpenShell. Third-party services, model providers, inference endpoints, agents, or tools that you configure and use with OpenShell may have their own terms and privacy practices.
260260

261+
We publish aggregate usage trends from this telemetry every two weeks. See the [community telemetry reports](telemetry/README.md) for the latest summary.
262+
261263
## Notice and Disclaimer
262264

263265
This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.

0 commit comments

Comments
 (0)