You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 320ea31
Browse filesBrowse the repository at this point in the historyBrowse files
| Gateway deployment, Helm, runtime drivers, or health checks |`debug-openshell-cluster`, `helm-dev-environment`|
48
-
| Inference providers, native model endpoints, or migration from `inference.local`|`debug-inference`, `openshell-cli`, `generate-sandbox-policy`|
48
+
| Inference providers, native model endpoints, or migration from the retired managed endpoint|`debug-inference`, `openshell-cli`, `generate-sandbox-policy`|
49
49
| TUI architecture, navigation, data fetching, or UX |`tui-development`|
50
50
| Release artifacts or post-publish smoke coverage |`test-release-canary`|
51
51
| GitHub Actions workflows, required checks, or CI diagnostics |`watch-github-actions`; also `test-release-canary` for release smoke coverage |
Phase 2: WatchSandbox(follow_logs: true) → live tail → send via Event::LogLines
171
171
```
172
172
173
-
**Sandboxes**: Fetched via `ListSandboxes` in a background collection-refresh task scheduled from the 2-second tick, scoped to the current workspace (or all workspaces). Follow `next_page_token` until empty so the dashboard reflects the complete collection.
173
+
**Sandboxes**: Fetched via `ListSandboxes` in a background collection-refresh task scheduled from the 2-second tick, scoped to the current workspace (or all workspaces). Follow `next_page_token` until empty so the dashboard reflects the complete collection. The NOTES column summarizes active `ConfigurationInvalid` readiness conditions as `Invalid config` before port forwards and clears the note on refresh after repair. Full diagnostics remain available through `openshell sandbox get <name> -o json`. Timed-out provisioning attempts show `Provisioning timed out` with cleanup pending or compute reclaimed, preserving port forwards. The sandbox detail pane wraps the full configuration error in its Notes field.
174
174
175
175
**Providers**: Fetched via `ListProviders` in the background collection-refresh task. Provider profiles are fetched per-workspace via `ListProviderProfiles` and cached in a `ProviderProfileCache` keyed by `(workspace, profile_id)`. Follow each list RPC's `next_page_token` until empty.
|`debug-openshell-cluster`| Diagnose gateway deployment and health issues |
83
-
|`debug-inference`| Diagnose attached-provider inference, native endpoints, and migration from `inference.local`|
83
+
|`debug-inference`| Diagnose attached-provider inference, native endpoints, and migration from the retired managed endpoint|
84
84
|`generate-sandbox-policy`| Generate YAML sandbox policies from requirements or API documentation |
85
85
86
86
Public skills use `openshell --help` for installed command syntax and published OpenShell documentation for product concepts and configuration. They must not depend on repository-relative source or documentation files.
> **OpenShell 0.1.0 is coming soon.**[Track progress in the 0.1.0 milestone](https://github.com/NVIDIA/OpenShell/milestone/10), [read the prerelease documentation](https://docs.nvidia.com/openshell/dev/index.html), or [install a prerelease](#prerelease-and-development-builds).
19
+
17
20
OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments that protect your data, credentials, and infrastructure — governed by declarative YAML policies that prevent unauthorized file access, data exfiltration, and uncontrolled network activity.
18
21
19
22
OpenShell is built agent-first. It ships public agent skills for using and operating OpenShell, plus separate repository-aware workflows for contributors and maintainers.
@@ -27,21 +30,15 @@ OpenShell is built agent-first. It ships public agent skills for using and opera
27
30
28
31
### Install
29
32
30
-
**Binary (recommended):**
33
+
**Local installation:**
31
34
32
35
```bash
33
36
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
34
37
```
35
38
36
-
The installer installs the latest stable release by default. To install a specific version, set `OPENSHELL_VERSION`. A [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) is also available that tracks the latest commit on `main`.
37
-
38
-
The `openshell` package on PyPI provides the Python SDK only. It does not install the `openshell` CLI. Add the SDK to a Python project with [uv](https://docs.astral.sh/uv/):
39
-
40
-
```bash
41
-
uv add openshell
42
-
```
39
+
The installer installs the latest stable release by default. See [Prerelease and development builds](#prerelease-and-development-builds) to install an upcoming release or the latest commit on `main`.
43
40
44
-
**Helm chart:**
41
+
**Kubernetes installation:**
45
42
46
43
> **Experimental** — the Kubernetes deployment path is under active development. Expect rough edges and breaking changes.
47
44
@@ -104,6 +101,44 @@ See the [full walkthrough](examples/sandbox-policy-quickstart/) or run the autom
104
101
bash examples/sandbox-policy-quickstart/demo.sh
105
102
```
106
103
104
+
## SDKs
105
+
106
+
OpenShell provides client SDKs for Python, TypeScript, Go, and Rust. SDK packages connect applications to an OpenShell gateway; they do not install the `openshell` CLI. Use the SDK and gateway from the same OpenShell release when possible.
107
+
108
+
### Python
109
+
110
+
The [Python SDK](python/openshell/) is published to [PyPI](https://pypi.org/project/openshell/):
111
+
112
+
```shell
113
+
uv add openshell
114
+
```
115
+
116
+
### TypeScript
117
+
118
+
The [TypeScript SDK](sdk/typescript/README.md) is published to GitHub Packages as `@nvidia/openshell-sdk`. Configure the `@nvidia` npm scope for `https://npm.pkg.github.com`, authenticate with a token that has `read:packages`, and install it:
119
+
120
+
```shell
121
+
npm install @nvidia/openshell-sdk
122
+
```
123
+
124
+
### Go
125
+
126
+
Add the [Go SDK](sdk/go/README.md) to a Go module:
127
+
128
+
```shell
129
+
go get github.com/NVIDIA/OpenShell/sdk/go@latest
130
+
```
131
+
132
+
### Rust
133
+
134
+
The [Rust SDK](crates/openshell-sdk/README.md) is currently consumed from source. Pin the Git dependency to the same OpenShell release as the gateway:
135
+
136
+
```shell
137
+
cargo add openshell-sdk \
138
+
--git https://github.com/NVIDIA/OpenShell \
139
+
--tag <release-tag>
140
+
```
141
+
107
142
## How It Works
108
143
109
144
OpenShell isolates each sandbox in its own container with policy-enforced egress routing. A lightweight gateway coordinates sandbox lifecycle, and every outbound connection is intercepted by the policy engine, which does one of three things:
@@ -136,7 +171,9 @@ Policies are declarative YAML files. Static sections (filesystem, process) are l
136
171
137
172
## Providers
138
173
139
-
Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. The CLI auto-discovers credentials for recognized agents (Claude, Codex, OpenCode, Copilot) from your shell environment, or you can create providers explicitly with `openshell provider create`. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime.
174
+
Agents need credentials — API keys, tokens, service accounts. OpenShell manages these as **providers**: named credential bundles that are injected into sandboxes at creation. Credentials never leak into the sandbox filesystem; they are injected as environment variables at runtime.
175
+
176
+
A provider is created from a **provider profile**, which declares the credentials, endpoints, and client binaries the provider needs. Profiles are import-only: a gateway serves exactly the profiles you imported with `openshell provider profile import`, and ships none of its own. The [`providers/`](providers/) directory holds reviewable examples to copy and adapt. Once a profile is imported, the CLI can auto-discover credentials for its provider from your shell environment, or you can create providers explicitly with `openshell provider create`.
140
177
141
178
Inference access uses the same provider workflow. Attach an inference-capable provider to a sandbox, call the provider's native endpoint, and select the model in the client. Provider profiles contribute the endpoint policy and bind credential placeholders to the authorized destination.
142
179
@@ -255,6 +292,43 @@ Agent implementation is human-directed: a user may request a phase directly, or
255
292
-[Brev Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg) — try OpenShell on cloud compute without local setup
256
293
-[Agent Instructions](AGENTS.md) — system prompt and workflow documentation for agent contributors
257
294
295
+
## Prerelease and development builds
296
+
297
+
Use a prerelease candidate to evaluate an upcoming release, or use the rolling development build to test the latest commit on `main`. These builds may change before the next stable release. The matching documentation is published in the [development channel](https://docs.nvidia.com/openshell/dev/index.html).
298
+
299
+
Prerelease packages are retained as GitHub Actions artifacts for 90 days and require an authenticated [GitHub CLI](https://cli.github.com/) session. The `pre` alias installs the latest prerelease:
The installer downloads only the artifact for the current platform and rejects expired candidates during discovery. Installed packages retain the candidate's exact version, such as `0.1.0-pre.3`. Prerelease tags do not create entries on the GitHub Releases page.
308
+
309
+
The rolling [`dev` release](https://github.com/NVIDIA/OpenShell/releases/tag/dev) does not require GitHub authentication:
For Kubernetes, select the corresponding Helm chart version. Helm chart versions omit the leading `v` from release tags:
317
+
318
+
```shell
319
+
# Pin an exact candidate
320
+
helm upgrade --install openshell \
321
+
oci://ghcr.io/nvidia/openshell/helm-chart \
322
+
--version 0.1.0-pre.3
323
+
324
+
# Rolling development build
325
+
helm upgrade --install openshell \
326
+
oci://ghcr.io/nvidia/openshell/helm-chart \
327
+
--version 0.0.0-dev
328
+
```
329
+
330
+
Prerelease charts use exact `<version>-pre.N` versions. Development charts are also published as immutable `0.0.0-dev.<commit-sha>` versions when you need to pin a specific commit. See the [Helm chart documentation](deploy/helm/openshell/README.md#available-versions) for version and configuration details.
331
+
258
332
## Contributing
259
333
260
334
OpenShell is built agent-first. Issues should include a user story, problem statement, impact, and acceptance criteria. The impact should explain the consequences of the current behavior and why existing workarounds are insufficient. Feature requests also require a workflow-level proposed design and alternatives; bug reports add reproduction steps, environment details, and relevant logs. Once work is authorized through the project workflow or a direct request, contributors should use the skills in `.agents/skills/` to investigate the current code and behavior, implement the change, and verify it. If an issue contains earlier diagnostics, verify them rather than relying on them. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full agent skills table, contribution workflow, and development setup.
0 commit comments