diff --git a/.gitignore b/.gitignore index 32610f714..d51c6e8d4 100644 --- a/.gitignore +++ b/.gitignore @@ -197,3 +197,4 @@ architecture/plans .claude/settings.local.json.claude/worktrees/ .claude/worktrees/ rfc.md +.worktrees diff --git a/fern/assets/NVIDIA_dark.svg b/fern/assets/NVIDIA_dark.svg new file mode 100644 index 000000000..04850d9d6 --- /dev/null +++ b/fern/assets/NVIDIA_dark.svg @@ -0,0 +1,35 @@ + + + + + + + + + + + + + + + + + + + diff --git a/fern/assets/NVIDIA_light.svg b/fern/assets/NVIDIA_light.svg new file mode 100644 index 000000000..9ee045c3e --- /dev/null +++ b/fern/assets/NVIDIA_light.svg @@ -0,0 +1,34 @@ + + + + + + + + + + + + + + + + + + + diff --git a/fern/assets/NVIDIA_symbol.svg b/fern/assets/NVIDIA_symbol.svg new file mode 100644 index 000000000..c0507afe0 --- /dev/null +++ b/fern/assets/NVIDIA_symbol.svg @@ -0,0 +1,22 @@ + + + + + + + + + + + + + + + diff --git a/fern/assets/images/architecture.svg b/fern/assets/images/architecture.svg new file mode 100644 index 000000000..b0bcd4d5d --- /dev/null +++ b/fern/assets/images/architecture.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/fern/assets/images/openshell-terminal.png b/fern/assets/images/openshell-terminal.png new file mode 100644 index 000000000..09fe2b768 Binary files /dev/null and b/fern/assets/images/openshell-terminal.png differ diff --git a/fern/assets/openshell-terminal.png b/fern/assets/openshell-terminal.png new file mode 100644 index 000000000..09fe2b768 Binary files /dev/null and b/fern/assets/openshell-terminal.png differ diff --git a/fern/components/BadgeLinks.tsx b/fern/components/BadgeLinks.tsx new file mode 100644 index 000000000..cc9753034 --- /dev/null +++ b/fern/components/BadgeLinks.tsx @@ -0,0 +1,26 @@ +/** + * Badge links for GitHub, License, PyPI, etc. + * Uses a flex wrapper to display badges horizontally and hides Fern's + * external-link icon that otherwise stacks under each badge image. + * Requires the `.badge-links` CSS rule from main.css. + */ +export type BadgeItem = { + href: string; + src: string; + alt: string; +}; + +export function BadgeLinks({ badges = [] }: { badges?: BadgeItem[] }) { + if (badges.length === 0) { + return null; + } + return ( +
+ {badges.map((b) => ( + + {b.alt} + + ))} +
+ ); +} diff --git a/fern/components/CustomFooter.tsx b/fern/components/CustomFooter.tsx new file mode 100644 index 000000000..fab392c40 --- /dev/null +++ b/fern/components/CustomFooter.tsx @@ -0,0 +1,91 @@ +/** + * Custom footer for NVIDIA docs (Fern native header/footer). + * Markup and class names match the original custom-app footer 1:1 so that + * fern/main.css (footer + Built with Fern styles) applies correctly: + * dark mode logo, responsive layout, and Built with Fern tooltip. + */ +export default function CustomFooter() { + const currentYear = new Date().getFullYear(); + const logoUrl = + "https://fern-image-hosting.s3.us-east-1.amazonaws.com/nvidia/NVIDIA_Logo_0.svg"; + + return ( + + ); +} diff --git a/fern/docs.yml b/fern/docs.yml new file mode 100644 index 000000000..46710cc4f --- /dev/null +++ b/fern/docs.yml @@ -0,0 +1,83 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# Fern site config — merged with skills/convert-to-fern/assets/theme/nvidia/docs-theme.yml pattern +# Production: https://docs.nvidia.com/openshell/ — preview + custom-domain share path prefix `openshell`. +# Internal MDX links use /latest/...; basepath-aware resolves them under /openshell/ on production. +instances: + - url: openshell.docs.buildwithfern.com/openshell + custom-domain: docs.nvidia.com/openshell + +title: NVIDIA OpenShell + +announcement: + message: "🔔 NVIDIA OpenShell is alpha software. APIs and behavior may change without notice. Do not use in production." + +footer: ./components/CustomFooter.tsx + +layout: + searchbar-placement: header + page-width: 1376px + sidebar-width: 248px + content-width: 812px + tabs-placement: header + hide-feedback: true + +colors: + accentPrimary: + dark: "#76B900" + light: "#76B900" + background: + light: "#FFFFFF" + dark: "#000000" + +theme: + page-actions: toolbar + footer-nav: minimal + +logo: + dark: ./assets/NVIDIA_dark.svg + light: ./assets/NVIDIA_light.svg + height: 20 + href: /openshell/latest + right-text: OpenShell + +favicon: ./assets/NVIDIA_symbol.svg + +js: + - url: https://assets.adobedtm.com/5d4962a43b79/c1061d2c5e7b/launch-191c2462b890.min.js + strategy: beforeInteractive + +css: + - ./main.css + +navbar-links: + - type: github + value: https://github.com/NVIDIA/OpenShell + +experimental: + mdx-components: + - ./components + basepath-aware: true + +versions: + - display-name: Latest + path: versions/latest.yml + slug: latest + +redirects: + # Paths are relative to the site root; subpath prefix matches instances + custom-domain. + # https://www.buildwithfern.com/learn/docs/configuration/site-level-settings#redirects-configuration + - source: "/openshell/index.html" + destination: "/openshell/latest" + - source: "/openshell/index" + destination: "/openshell/latest" + - source: "/openshell/observability" + destination: "/openshell/observability/index" + - source: "/openshell/latest/:path*/index.html" + destination: "/openshell/latest/:path*" + - source: "/openshell/latest/observability" + destination: "/openshell/latest/observability/index" + - source: "/openshell/:path*/index.html" + destination: "/openshell/:path*" + - source: "/openshell/:path*.html" + destination: "/openshell/:path*" diff --git a/fern/fern.config.json b/fern/fern.config.json new file mode 100644 index 000000000..3d47d15e3 --- /dev/null +++ b/fern/fern.config.json @@ -0,0 +1,4 @@ +{ + "organization": "nvidia", + "version": "4.62.4" +} diff --git a/fern/main.css b/fern/main.css new file mode 100644 index 000000000..eff5dd495 --- /dev/null +++ b/fern/main.css @@ -0,0 +1,1037 @@ +/*! + * SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + * SPDX-License-Identifier: LicenseRef-NvidiaProprietary + * + * NVIDIA CORPORATION, its affiliates and licensors retain all intellectual + * property and proprietary rights in and to this material, related + * documentation and any modifications thereto. Any use, reproduction, + * disclosure or distribution of this material and related documentation + * without an express license agreement from NVIDIA CORPORATION or + * its affiliates is strictly prohibited. + */ + +/* Color themes for light and dark modes */ +:root { + /* Brand Colors */ + --nv-color-green: #74B900; + --nv-color-green-2: #004B31; + --nv-color-black: #000000; + --nv-color-white: #FFFFFF; + + /* Grey Scale - Light */ + --nv-light-grey-1: #f7f7f7; + --nv-light-grey-2: #EEEEEE; + --nv-light-grey-3: #DDDDDD; + --nv-light-grey-4: #CCCCCC; + --nv-light-grey-5: #999999; + + /* Grey Scale - Dark */ + --nv-dark-grey-1: #111111; + --nv-dark-grey-2: #1A1A1A; + --nv-dark-grey-3: #222222; + --nv-dark-grey-4: #333333; + --nv-dark-grey-5: #666666; + + /* Colors by Usage */ + --nv-color-text: #000000; + --nv-color-bg-default: #FFFFFF; + --nv-color-bg-alt: #f7f7f7; + --nv-color-success: #76B900; + --nv-color-error: #f44336; + + /* Theme-independent settings */ + --rounded: 999px; +} +main { + min-height: calc(100vh - 200px); + } +/* Typography - Headers */ +h1 { + font-size: 36px; + font-weight: 700; + line-height: 1.25em; /* 45px */ +} + +h2 { + font-size: 28px; + font-weight: 700; + line-height: 1.25em; /* 35px */ +} + +h3 { + font-size: 24px; + font-weight: 700; + line-height: 1.25em; /* 30px */ +} + +h4 { + font-size: 20px; + font-weight: 700; + line-height: 1.25em; /* 25px */ +} + +/* Typography - Paragraphs */ +.prose{ + color: var(--nv-dark-grey-2) !important; +} +.dark .prose{ + color: var(--nv-light-grey-2) !important; +} +p { + text-decoration-thickness: 3px; +} +.fern-mdx-link { + color: var(--tw-prose-body); + text-decoration-color: var(--accent); + font-weight: var(--font-weight-normal); +} + +/* Badge links: hide redundant external-link icon (badges already indicate links) */ +.badge-links { + display: flex; + gap: 8px; + flex-wrap: wrap; + align-items: center; + line-height: 0; + margin: 0.25rem 0 0.75rem; +} + +.badge-links a { + display: inline-flex; + align-items: center; +} + +.badge-links img { + display: block; + margin: 0 !important; +} + +.badge-links .fern-mdx-link svg { + display: none; +} + +.badge-links + p { + margin-top: 0 !important; +} + +/* Opt-in tab panels for content that should read as a contained variant block. */ +.boxed-tabs { + margin-top: 0.75rem; + margin-bottom: 1.25rem; +} + +.boxed-tabs [role="tabpanel"] { + margin-top: 0.2rem; + padding: 0.625rem 0.875rem 0.875rem; + border: 1px solid var(--border, var(--grayscale-a5)); + border-radius: 14px; + background-color: #fcfcfa; + box-shadow: 0 1px 2px rgba(0, 0, 0, 0.04); +} + +.boxed-tabs [role="tabpanel"] > :first-child { + margin-top: 0 !important; +} + +.boxed-tabs [role="tabpanel"] > :last-child { + margin-bottom: 0 !important; +} + +.boxed-tabs [role="tabpanel"] > .not-prose { + margin-top: 0.5rem !important; + margin-bottom: 0.75rem !important; +} + +.dark .boxed-tabs [role="tabpanel"], +html[data-theme=dark] .boxed-tabs [role="tabpanel"] { + background-color: var(--nv-dark-grey-2); + box-shadow: none; +} + +/* Light theme (default) */ +html:not([data-theme]),html[data-theme=light] { + --pst-color-background: #fff; + --pst-color-on-background: #fff; + --pst-color-shadow: #ccc; + --pst-color-heading: #000; + --pst-color-text-base: #1a1a1a; + --pst-color-text-muted: #666; + --pst-color-surface: #f7f7f7; + --pst-color-on-surface: #333; + --pst-color-primary: var(--nv-color-green-2); + --pst-color-table-row-hover-bg: var(--nv-color-green); + --pst-color-link: var(--pst-color-text-base); + --pst-color-link-hover: var(--pst-color-text-base); + --pst-color-inline-code: var(--pst-color-primary); + --pst-color-inline-code-links: var(--pst-color-primary); + --pst-color-secondary: var(--pst-color-primary); + --pst-color-secondary-bg: var(--nv-color-green); + --pst-color-accent: var(--nv-color-green); +} + +/* Dark theme */ +html[data-theme=dark] { + --pst-color-background: #111; + --pst-color-on-background: #000; + --pst-color-shadow: #000; + --pst-color-heading: #fff; + --pst-color-text-base: #eee; + --pst-color-text-muted: #999; + --pst-color-surface: #1a1a1a; + --pst-color-on-surface: #ddd; + --pst-color-primary: var(--nv-color-green); + --pst-color-table-row-hover-bg: var(--nv-color-green-2); + --pst-color-link: var(--pst-color-text-base); + --pst-color-link-hover: var(--pst-color-text-base); + --pst-color-inline-code: var(--pst-color-primary); + --pst-color-inline-code-links: var(--pst-color-primary); + --pst-color-secondary: var(--pst-color-primary); + --pst-color-secondary-bg: var(--nv-color-green-2); + --pst-color-accent: var(--nv-color-green); +} + +/* Product and verion selector styling */ + +.fern-product-selector { + border-radius: 8px; + pointer-events: none !important; + padding-right: 2px; +} + +.product-dropdown-trigger svg{ + display: none !important; +} + +.fern-product-selector .product-dropdown-trigger p{ + font-weight: bold !important; +} +.fern-product-selector-radio-group { + display: grid; + grid-template-columns: repeat(3, 1fr); + gap: 8px; + max-width: 1000px; +} + +@media (max-width: 768px) { + .fern-product-selector-radio-group { + grid-template-columns: repeat(2, 1fr); + } +} +.fern-version-selector { + transform: translateY(-1px); +} + +.fern-version-selector .version-dropdown-trigger{ + outline: 1px solid var(--border, var(--grayscale-a5)) !important; + border-radius: 5px; + transition: box-shadow 0.3s ease, outline 0.3s ease; +} +.product-dropdown-trigger{ + padding-left: 0px !important; +} + +.product-dropdown-trigger, .version-dropdown-trigger{ + background-color: transparent !important; +} +.product-dropdown-trigger svg:hover{ + stroke: var(--nv-color-green) !important; +} +.version-dropdown-trigger:hover{ + box-shadow: 0 0 0 1px var(--nv-color-green) !important; +} +.version-dropdown-trigger svg:hover{ + stroke: var(--nv-color-green) !important; +} +/* Sidebar styling */ +#fern-sidebar { + border-right: 1px solid var(--border, var(--grayscale-a5)) !important; + height: 100vh !important; +} +.fern-sidebar-link:not(:hover){ + background-color: transparent !important; +} +.fern-sidebar-link { + padding-left: 1rem !important; + padding-right: 1rem !important; + padding-top: 0.5rem !important; + padding-bottom: 0.5rem !important; + border-radius: 0px !important; + &.nested { + padding-left: 1rem !important; + } +} +/* Section-level sidebar links (pages that have children) should match sidebar heading padding */ +.fern-sidebar-group > li > .fern-sidebar-link:has(+ .fern-sidebar-group) { + padding-left: 0.25rem !important; +} +.fern-sidebar-group{ + padding: 0 !important +} +#fern-sidebar-scroll-area{ + padding-right: 0 !important +} + +/* header styling */ +.fern-header-content{ + padding-left: 18.5px; + margin-top: -5px; + margin-bottom: -5px; +} +#fern-header { + border-color: var(--border, var(--grayscale-a5)) !important; +} +@keyframes header-background-fade { + 0% { + background-color: transparent; + } + 100% { + background-color: var(--header-background); + } + } + +[data-theme=default]#fern-header { +animation: header-background-fade linear; +animation-timeline: scroll(); +animation-range: 0 50px; +} +.fern-header-navbar-links .fern-button{ + background-color: transparent !important; +} +.fern-header-navbar-links > button{ + background-color: transparent !important; +} +.fern-header-logo-container > div > div > a > img{ + padding-right: 0.5rem; +} +.fern-header-logo-container .font-heading{ + font-size: 16px !important; + font-weight: bold !important; + color: var(--grayscale-a12) !important; + border-inline: 1px solid var(--border, var(--grayscale-a5)); + padding: 15px 1rem; + margin: -20px 0.5rem; +} +@media (max-width: 1024px) { + .fern-header-logo-container .font-heading{ + display: none !important; + } +} +/* Search bar styling */ +#fern-search-button{ + background-color: transparent !important; + border-radius: var(--rounded); + transition: box-shadow 0.3s ease, outline 0.3s ease; +} +#fern-search-button:hover{ + box-shadow: 0 0 0 1px var(--nv-color-green) !important; +} +#fern-search-button .fern-kbd{ + display: none; +} + +.fern-layout-footer-toolbar button{ + background-color: transparent !important; + border-color: transparent !important; + padding-inline: 0px !important; +} + +/* ========== Custom footer (native React component) – 1:1 with original ========== */ +.bd-footer { + border-top: 1px solid var(--border, var(--grayscale-a5)) !important; + font-family: NVIDIA, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif !important; + font-size: 0.875rem; + padding: 2rem 0; + width: 100%; +} +.bd-footer * { + font-family: inherit; +} +.bd-footer__inner { + padding: 0 2rem; +} +.footer-items__start { + display: flex; + flex-direction: column; + gap: 1.5rem; +} +.footer-logos-container { + display: flex; + align-items: center; + justify-content: space-between; + width: 100%; + gap: 1rem; +} +.footer-brand { + display: inline-block; + text-decoration: none; +} +.footer-brand .logo__image { + height: 24px; + width: auto; + transition: opacity 0.2s ease; +} +.footer-brand:hover .logo__image { + opacity: 0.8; +} +.footer-brand-fern { + display: flex; + align-items: center; + margin-left: auto; +} +/* Logo theme visibility – .dark is on ancestor in Fern */ +.only-light { + display: block; + filter: invert(1); +} +.only-dark { + display: none; +} +.dark .only-light { + display: none; +} +.dark .only-dark { + display: block; + filter: none; +} +.footer-links { + display: flex; + flex-wrap: wrap; + gap: 0.25rem 0.5rem; + line-height: 1.65; + margin: 0; + padding: 0; +} +.footer-links a { + color: var(--grayscale-a11); + text-decoration: none; + transition: color 0.2s ease; + white-space: nowrap; +} +.pipe-separator { + color: var(--grayscale-a11); + white-space: nowrap; +} +.copyright { + color: var(--grayscale-a11); + font-size: 0.875rem; + line-height: 1.65; + margin: 0; +} +@media (max-width: 768px) { + .bd-footer { padding: 1.5rem 0; } + .bd-footer__inner { padding: 0 1.5rem; } + .footer-items__start { gap: 1rem; } + .footer-links { flex-direction: row; gap: 0.5rem 0.75rem; } + .footer-links a { white-space: normal; word-break: break-word; } +} +@media (max-width: 480px) { + .footer-links { gap: 0.5rem; } + .footer-links a { font-size: 0.8125rem; } + .copyright { font-size: 0.8125rem; } +} +/* Built with Fern link + tooltip */ +.built-with-fern-link { + display: flex; + align-items: baseline; + gap: 0.25rem; + text-decoration: none; + position: relative; +} +.built-with-fern-logo { + height: 1rem; + margin: 0; + transition: filter 150ms ease; +} +.built-with-fern-logo path { fill: var(--grayscale-a12); } +.built-with-fern-link:hover .built-with-fern-logo { filter: saturate(1) opacity(1); } +.built-with-fern-link:hover .built-with-fern-logo path:nth-child(2) { fill: #51C233; } +.built-with-fern-tooltip { + position: absolute; + top: 50%; + right: calc(100%); + bottom: auto; + left: auto; + transform: translateY(-50%); + margin: 0; + margin-right: 0.5rem; + padding: 0.5rem 0.75rem; + background-color: #FFFFFF; + color: #000000; + font-size: 0.85rem; + border-radius: 0.375rem; + border: 1px solid var(--grayscale-a5); + white-space: nowrap; + pointer-events: none; + opacity: 0; + transition: opacity 150ms ease; + transition-delay: 0s; + z-index: 50; + box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); + width: max-content; +} +.built-with-fern-link:hover .built-with-fern-tooltip { + opacity: 1; + transition-delay: 0.75s; +} +.dark .built-with-fern-tooltip { + background-color: #000000; + color: #FFFFFF; +} +.built-with-fern-logo-dark { display: none; } +.dark .built-with-fern-logo-light { display: none; } +.dark .built-with-fern-logo-dark { display: block; } +@media (prefers-color-scheme: dark) { + .built-with-fern-logo-light { display: none; } + .built-with-fern-logo-dark { display: block; } +} + +/* Footer styling */ +.fern-footer-nav{ + border-radius: var(--rounded); + background-color: transparent !important; + transition: box-shadow 0.3s ease, outline 0.3s ease; +} +.fern-footer-prev h4, .fern-footer-next h4{ + font-size: inherit !important; +} +.fern-sidebar-link.nested[data-state="active"]:before { + left: -0px !important; + bottom: -0px !important; + top: -0px !important; + width: 2px !important; +} +.fern-sidebar-link[data-state="active"] { + color: unset !important; +} + +.fern-selection-item .fern-selection-item-icon{ + border-color: transparent !important; +} +/* Button styling */ +.fern-button{ + border-radius: var(--rounded); + font-weight: bold; +} +.fern-button.filled.primary{ + color: var(--nv-color-black); +} +.dark .fern-button.filled.primary{ + background-color: var(--nv-color-white); +} +.dark .fern-button.filled.primary:hover{ + background-color: var(--nv-light-grey-2); +} +.fern-button.outlined.normal{ + background-color: transparent; + --tw-ring-color: transparent; + color: var(--nv-color-black); +} +.fern-button.outlined.normal:hover{ + color: var(--nv-color-green) +} +.dark .fern-button.outlined.normal{ + color: var(--nv-color-white); +} +.dark .fern-button.outlined.normal:hover{ + color: var(--nv-color-green); +} +/* Card styling */ +.fern-card{ + transition: box-shadow 0.3s ease, outline 0.3s ease; +} +svg.card-icon{ + height: 24px !important; + width: 24px !important; +} +.card-icon{ + background-color: transparent !important; +} +.fern-card:hover{ + box-shadow: 0 0 0 1px var(--nv-color-green) !important; +} +.fern-docs-badge{ + border-radius: var(--rounded); +} +.fern-page-actions button:hover{ + background-color: transparent !important; +} +.fern-page-actions a:hover{ + background-color: transparent !important; +} +/* Moving logo to footer */ +#builtwithfern, #builtwithfern * { + display: none !important; +} + +/* Landing Page Gradients */ +/* Top: Simple radial gradient (no mask, responsive) */ +.landing-gradient-top { + position: absolute; + top: 0; + left: 0; + right: 0; + height: 800px; + background: radial-gradient(ellipse 100% 100% at 50% 10%, + rgba(191, 242, 48, 0.15) 0%, + rgba(158, 228, 179, 0.12) 30%, + rgba(124, 215, 254, 0.12) 50%, + rgba(124, 215, 254, 0.06) 75%, + transparent 100%); + pointer-events: none; + z-index: 0; +} + +/* Bottom: Masked gradient for organic transition */ +.landing-gradient-bottom { + position: absolute; + bottom: -282px; + left: 0; + right: 0; + height: 1232px; + background: linear-gradient(85deg, #BFF230 41.98%, #7CD7FE 99.52%); + opacity: 0.05; + pointer-events: none; + z-index: 5; + mask-image: url('https://www.figma.com/api/mcp/asset/27509afa-9c16-46bb-8415-4395e2e5a347'); + mask-repeat: no-repeat; + mask-position: 0% -17px; + mask-size: 100% auto; + -webkit-mask-image: url('https://www.figma.com/api/mcp/asset/27509afa-9c16-46bb-8415-4395e2e5a347'); + -webkit-mask-repeat: no-repeat; + -webkit-mask-position: 0% -17px; + -webkit-mask-size: 100% auto; +} + +/* Landing Page Gradients Wrapper */ +.landing-page-gradients { + position: relative; + width: 100%; + margin-top: -100px; + padding-top: 100px; + overflow: visible; + background: #181818; +} + +/* Hero Section (Landing page only) */ +.hero-section { + position: relative; + width: 100%; + padding: 3rem 6rem; + margin: 0 auto; + overflow: visible; + display: flex; + flex-direction: column; + align-items: center; + z-index: 10; +} + +/* Hero Section Content - constrain width */ +.hero-section > * { + position: relative; + z-index: 100; + max-width: 1440px; + width: 100%; +} + +/* Tablet and Mobile: fix spacing and layout */ +@media (max-width: 1024px) { + /* Extend dark background behind header */ + .landing-page body, .landing-page html, .landing-page main { + background: #181818 !important; + } + + .landing-page-gradients { + margin-top: -100px; + padding-top: 100px; + } + + .hero-section { + padding: 2rem 2rem; + } + + .hero-section > * { + max-width: none; + } + + .hero-content-grid { + grid-template-columns: 1fr; + gap: 2rem; + } + + .hero-heading { + font-size: 36px; + } + + .hero-subtitle { + font-size: 16px; + } + + .hero-title-section { + margin-bottom: 2rem; + } +} + +/* Small mobile only */ +@media (max-width: 600px) { + .hero-heading { + font-size: 28px; + } + + .hero-section { + padding: 1.5rem 1.5rem; + } +} + +.hero-section h1, +.hero-section h2, +.hero-section h3, +.hero-section h4, +.hero-section h5, +.hero-section h6 { + pointer-events: none !important; +} +/* Hero Title Section */ +.hero-title-section { + text-align: center; + margin-bottom: 4rem; + position: relative; + z-index: 100; +} + +.hero-heading { + font-size: 48px; + font-weight: 700; + line-height: 1.2; + margin: 0 0 1rem 0; + color: var(--nv-color-white); +} + +.hero-subtitle { + font-size: 18px; + line-height: 1.5; + margin: 0; + color: var(--nv-color-white); +} + +/* Hero Content Grid */ +.hero-content-grid { + display: grid; + grid-template-columns: repeat(2, 1fr); + gap: 3rem; + align-items: start; + position: relative; + z-index: 100; +} + +.hero-column { + display: flex; + flex-direction: column; + gap: 1rem; +} + +.hero-column-title { + font-size: 24px; + font-weight: 700; + margin: 0; + color: var(--nv-color-white); +} + +.hero-column-subtitle { + font-size: 16px; + margin: 0 0 1rem 0; + color: var(--nv-color-white); +} + +/* Hero Card Container (Left Column) */ +.hero-card-container { + display: flex; + flex-direction: column; + border-radius: 8px; + overflow: hidden; + border: 1px solid var(--border, var(--grayscale-a5)); + margin-top: 1.5rem !important; + background: rgba(26, 26, 26, 0.2); + backdrop-filter: blur(6px); +} + +.hero-card-image { + width: 100%; + height: auto; + display: block; +} + +.hero-card-content { + padding: 1.5rem; + display: flex; + flex-direction: row; + gap: 1rem; + align-items: center; + justify-content: space-between; + background: rgba(26, 26, 26, 0.2); + backdrop-filter: blur(6px); +} + +.hero-card-text-wrapper { + flex: 1; +} + +.hero-card-text { + margin: 0; + font-size: 14px; + line-height: 1.5; + color: var(--nv-color-white); +} + +.hero-card-button-wrapper { + flex-shrink: 0; +} +.hero-card-button-wrapper .fern-mdx-link{ + text-decoration: none !important; +} + +.hero-card-button { + white-space: nowrap; +} + +/* Hero Cards */ + +.hero-column .fern-card { + padding: 9px 17px; + background-color: rgba(26, 26, 26, 0.2) !important; + backdrop-filter: blur(6px); +} + +.hero-section .fern-card{ + color: white !important; +} + +.hero-column .card-icon { + font-size: 64px !important; + width: 64px !important; + height: 64px !important; +} + +.hero-column .card-icon svg, +.hero-column .card-icon i { + font-size: 64px !important; + width: 64px !important; + height: 64px !important; +} + +.hero-column .fern-card-title { + font-size: 16px; + font-weight: 500; + line-height: 24px; +} + +.hero-column .fern-card p { + font-size: 14px; + line-height: 20px; + color: white !important; +} + +/* Body Section */ +.body-section { + display: flex; + padding: 4rem 16rem; + flex-direction: column; + justify-content: center; + align-items: center; + gap: 4rem; + align-self: stretch; + position: relative; + z-index: 1; + background: #181818; +} + +/* Body Section Content - constrain width */ +.body-section > * { + max-width: 1440px; + width: 100%; + position: relative; + z-index: 10; +} + +.code-block .fern-code-link{ + text-decoration: underline !important; + text-decoration-color: var(--accent) !important; + text-underline-offset: 1px !important; + text-decoration-style: underline !important; +} + +/* Global alpha announcement banner */ +header[role="banner"] > div[class*="bg-(color:--accent)"][class*="text-(color:--accent-contrast)"] { + background: #005b3c; +} + +header[role="banner"] > div[class*="bg-(color:--accent)"][class*="text-(color:--accent-contrast)"] > div { + min-height: 3rem; + padding-top: 0.25rem; + padding-bottom: 0.25rem; +} + +header[role="banner"] > div[class*="bg-(color:--accent)"][class*="text-(color:--accent-contrast)"] .max-w-page-width { + text-align: left; +} + +header[role="banner"] > div[class*="bg-(color:--accent)"][class*="text-(color:--accent-contrast)"] p { + font-size: 1rem; + line-height: 1.4; +} + +/* Mobile Styles */ +@media (max-width: 768px) { + .hero-section { + padding: 2rem 1.5rem; + } + + .hero-title-section { + margin-bottom: 2rem; + } + + .hero-heading { + font-size: 32px; + } + + .hero-subtitle { + font-size: 16px; + } + + .hero-content-grid { + grid-template-columns: 1fr; + gap: 2rem; + } + + .hero-column-title { + font-size: 20px; + } + + .hero-column-subtitle { + font-size: 14px; + } + + .hero-card-content { + flex-direction: column; + align-items: flex-start; + } + + .hero-card-button-wrapper { + align-self: flex-start; + } + + .hero-column .card-icon, + .hero-column .card-icon svg, + .hero-column .card-icon i { + font-size: 40px !important; + width: 40px !important; + height: 40px !important; + } + + .hero-column .fern-card-title { + font-size: 14px; + } + + .hero-column .fern-card p { + font-size: 11px; + } + + .body-section { + padding: 2rem 1.5rem; + } + + .fern-selection-item-icon.use-icon { + display: none !important; + } +} + +/* OpenShell landing: terminal demo */ +.nc-term { + background: #1a1a2e; + border-radius: 8px; + overflow: hidden; + margin: 1.5em 0; + box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25); + font-family: "SFMono-Regular", Menlo, Monaco, Consolas, "Liberation Mono", monospace; + font-size: 0.875em; + line-height: 1.8; +} +.nc-term-bar { + background: #252545; + padding: 10px 14px; + display: flex; + gap: 7px; + align-items: center; +} +.nc-term-dot { + width: 12px; + height: 12px; + border-radius: 50%; +} +.nc-term-dot-r { + background: #ff5f56; +} +.nc-term-dot-y { + background: #ffbd2e; +} +.nc-term-dot-g { + background: #27c93f; +} +.nc-term-body { + padding: 16px 20px; + color: #d4d4d8; +} +.nc-term-body .nc-ps { + color: #76b900; + user-select: none; +} +.nc-swap { + display: inline-grid; + vertical-align: baseline; +} +.nc-swap > span { + grid-area: 1 / 1; + white-space: nowrap; + opacity: 0; + animation: nc-cycle 12s ease-in-out infinite; +} +.nc-swap > span:nth-child(2) { + animation-delay: 3s; +} +.nc-swap > span:nth-child(3) { + animation-delay: 6s; +} +.nc-swap > span:nth-child(4) { + animation-delay: 9s; +} +@keyframes nc-cycle { + 0%, + 3% { + opacity: 0; + } + 5%, + 20% { + opacity: 1; + } + 25%, + 100% { + opacity: 0; + } +} +.nc-hl { + color: #76b900; + font-weight: 600; +} +.nc-cursor { + display: inline-block; + width: 2px; + height: 1.1em; + background: #d4d4d8; + vertical-align: text-bottom; + margin-left: 1px; + animation: nc-blink 1s step-end infinite; +} +@keyframes nc-blink { + 50% { + opacity: 0; + } +} diff --git a/fern/versions/_nav_order.yml b/fern/versions/_nav_order.yml new file mode 100644 index 000000000..5207b5bc7 --- /dev/null +++ b/fern/versions/_nav_order.yml @@ -0,0 +1,28 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +# Page ordering derived from toctree (use with add_frontmatter.py --nav-order) +"./versions/latest/pages/about/overview.mdx": 1 +"./versions/latest/pages/get-started/quickstart.mdx": 1 +"./versions/latest/pages/index.mdx": 1 +"./versions/latest/pages/inference/index.mdx": 1 +"./versions/latest/pages/observability/index.mdx": 1 +"./versions/latest/pages/reference/gateway-auth.mdx": 1 +"./versions/latest/pages/resources/license.mdx": 1 +"./versions/latest/pages/sandboxes/index.mdx": 1 +"./versions/latest/pages/security/best-practices.mdx": 1 +"./versions/latest/pages/about/architecture.mdx": 2 +"./versions/latest/pages/inference/configure.mdx": 2 +"./versions/latest/pages/observability/logging.mdx": 2 +"./versions/latest/pages/reference/default-policy.mdx": 2 +"./versions/latest/pages/sandboxes/manage-sandboxes.mdx": 2 +"./versions/latest/pages/tutorials/index.mdx": 2 +"./versions/latest/pages/about/supported-agents.mdx": 3 +"./versions/latest/pages/reference/policy-schema.mdx": 3 +"./versions/latest/pages/observability/accessing-logs.mdx": 3 +"./versions/latest/pages/sandboxes/manage-gateways.mdx": 3 +"./versions/latest/pages/about/release-notes.mdx": 4 +"./versions/latest/pages/reference/support-matrix.mdx": 4 +"./versions/latest/pages/observability/ocsf-json-export.mdx": 4 +"./versions/latest/pages/sandboxes/manage-providers.mdx": 4 +"./versions/latest/pages/sandboxes/policies.mdx": 5 +"./versions/latest/pages/sandboxes/community-sandboxes.mdx": 6 diff --git a/fern/versions/latest.yml b/fern/versions/latest.yml new file mode 100644 index 000000000..1b62c64b4 --- /dev/null +++ b/fern/versions/latest.yml @@ -0,0 +1,102 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +navigation: + - section: "Getting Started" + slug: get-started + contents: + - page: "Home" + path: ./latest/pages/index.mdx + - page: "Quickstart" + slug: quickstart + path: ./latest/pages/get-started/quickstart.mdx + - section: "About NVIDIA OpenShell" + slug: about + contents: + - page: "Overview" + slug: overview + path: ./latest/pages/about/overview.mdx + - page: "How It Works" + slug: architecture + path: ./latest/pages/about/architecture.mdx + - page: "Supported Agents" + slug: supported-agents + path: ./latest/pages/about/supported-agents.mdx + - page: "Release Notes" + slug: release-notes + path: ./latest/pages/about/release-notes.mdx + - section: "Tutorials" + slug: tutorials + contents: + - page: "Tutorials" + slug: index + hidden: true + path: ./latest/pages/tutorials/index.mdx + - page: "First Network Policy" + slug: first-network-policy + path: ./latest/pages/tutorials/first-network-policy.mdx + - page: "GitHub Push Access" + slug: github-sandbox + path: ./latest/pages/tutorials/github-sandbox.mdx + - page: "Inference with Ollama" + slug: inference-ollama + path: ./latest/pages/tutorials/inference-ollama.mdx + - page: "Local Inference with LM Studio" + slug: local-inference-lmstudio + path: ./latest/pages/tutorials/local-inference-lmstudio.mdx + - section: "Gateways and Sandboxes" + slug: sandboxes + contents: + - page: "About Gateways and Sandboxes" + slug: about + path: ./latest/pages/sandboxes/index.mdx + - page: "Sandboxes" + slug: manage-sandboxes + path: ./latest/pages/sandboxes/manage-sandboxes.mdx + - page: "Gateways" + slug: manage-gateways + path: ./latest/pages/sandboxes/manage-gateways.mdx + - page: "Providers" + slug: manage-providers + path: ./latest/pages/sandboxes/manage-providers.mdx + - page: "Policies" + slug: policies + path: ./latest/pages/sandboxes/policies.mdx + - page: "Community Sandboxes" + slug: community-sandboxes + path: ./latest/pages/sandboxes/community-sandboxes.mdx + - section: "Inference Routing" + slug: inference + contents: + - page: "About Inference Routing" + slug: about + path: ./latest/pages/inference/index.mdx + - page: "Configure Inference Routing" + slug: configure + path: ./latest/pages/inference/configure.mdx + - section: "Observability" + slug: observability + contents: + - page: "Overview" + slug: index + path: ./latest/pages/observability/index.mdx + - page: "Logging" + slug: logging + path: ./latest/pages/observability/logging.mdx + - page: "Accessing Logs" + slug: accessing-logs + path: ./latest/pages/observability/accessing-logs.mdx + - page: "OCSF JSON Export" + slug: ocsf-json-export + path: ./latest/pages/observability/ocsf-json-export.mdx + - folder: ./latest/pages/reference + title: "Reference" + title-source: frontmatter + - section: "Security" + slug: security + contents: + - page: "Security Best Practices" + slug: best-practices + path: ./latest/pages/security/best-practices.mdx + - folder: ./latest/pages/resources + title: "Resources" + title-source: frontmatter diff --git a/fern/versions/latest/pages/CONTRIBUTING.mdx b/fern/versions/latest/pages/CONTRIBUTING.mdx new file mode 100644 index 000000000..cd4f2a8f1 --- /dev/null +++ b/fern/versions/latest/pages/CONTRIBUTING.mdx @@ -0,0 +1,165 @@ +--- +title: "Contributing to NVIDIA OpenShell Documentation" +description: "" +--- +This guide covers how to write, edit, and review documentation for NVIDIA OpenShell. If you change code that affects user-facing behavior, update the relevant docs in the same PR. + +## Use the Agent Skills + +If you use an AI coding agent (Cursor, Claude Code, Codex, etc.), the repo includes skills that automate doc work. Use them before writing from scratch. + +| Skill | What it does | When to use | +|---|---|---| +| `update-docs` | Scans recent commits for user-facing changes and drafts doc updates. | After landing features, before a release, or to find doc gaps. | +| `build-from-issue` | Plans and implements work from a GitHub issue, including doc updates. | When working from an issue that has doc impact. | + +The skills live in `.agents/skills/` and follow the style guide below automatically. To use one, ask your agent to run it (e.g., "catch up the docs for everything merged since v0.2.0"). + +## When to Update Docs + +Update documentation when your change: + +- Adds, removes, or renames a CLI command or flag. +- Changes default behavior or configuration. +- Adds a new feature that users interact with. +- Fixes a bug that the docs describe incorrectly. +- Changes an API, protocol, or policy schema. + +## Building Docs Locally + +Verify the docs are built correctly by building them and checking the output. + +To build the docs, run: + +```shell +mise run docs +``` + +To serve the docs locally and automatically rebuild on changes, run: + +```shell +mise run docs:serve +``` + +## Writing Conventions + +### Format + +- Docs use [MyST Markdown](https://myst-parser.readthedocs.io/), a Sphinx-compatible superset of CommonMark. +- Every page starts with YAML frontmatter (title, description, topics, tags, content type). +- Include the SPDX license header after frontmatter: + ``` + {/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + ``` + +### Frontmatter Template + +```yaml +--- +title: "page: Page Title" + nav: Short Nav Title +description: One-sentence summary of the page. +topics: +- Generative AI +- Cybersecurity +tags: +- Relevant +- Tags +content: + type: concept | how_to | get_started | tutorial | reference + difficulty: technical_beginner | technical_intermediate | technical_advanced + audience: + - engineer + - data_scientist +--- +``` + +### Page Structure + +1. H1 heading matching the `title.page` value. +2. A one- or two-sentence introduction stating what the page covers. +3. Sections organized by task or concept, using H2 and H3. Start each section with an introductory sentence that orients the reader. +4. A "Next Steps" section at the bottom linking to related pages. + +## Style Guide + +Write like you are explaining something to a colleague. Be direct, specific, and concise. + +### Voice and Tone + +- Use active voice. "The CLI creates a gateway" not "A gateway is created by the CLI." +- Use second person ("you") when addressing the reader. +- Use present tense. "The command returns an error" not "The command will return an error." +- State facts. Do not hedge with "simply," "just," "easily," or "of course." + +### Things to Avoid + +These patterns are common in LLM-generated text and erode trust with technical readers. Remove them during review. + +| Pattern | Problem | Fix | +|---|---|---| +| Unnecessary bold | "This is a **critical** step" on routine instructions. | Reserve bold for UI labels, parameter names, and genuine warnings. | +| Em dashes everywhere | "The gateway — which runs in Docker — creates sandboxes." | Use commas or split into two sentences. Em dashes are fine sparingly but should not appear multiple times per paragraph. | +| Superlatives | "OpenShell provides a powerful, robust, seamless experience." | Say what it does, not how great it is. | +| Hedge words | "Simply run the command" or "You can easily configure..." | Drop the adverb. "Run the command." | +| Emoji in prose | "🚀 Let's get started!" | No emoji in documentation prose. | +| Rhetorical questions | "Want to secure your agents? Look no further!" | State the purpose directly. | + +### Formatting Rules + +- End every sentence with a period. +- Use `code` formatting for CLI commands, file paths, flags, parameter names, and values. +- Use code blocks with the `console` language for CLI examples. Prefix commands with `$`: + ```shell + openshell gateway start + ``` +- Use tables for structured comparisons. Keep tables simple (no nested formatting). +- Use MyST admonitions (`:::{tip}`, `:::{note}`, `:::{warning}`) for callouts, not bold text. +- Avoid nested admonitions. +- Do not number section titles. Write "Deploy a Gateway" not "Section 1: Deploy a Gateway" or "Step 3: Verify." +- Do not use colons in titles. Write "Deploy and Manage Gateways" not "Gateways: Deploy and Manage." +- Use colons only to introduce a list. Do not use colons as general-purpose punctuation between clauses. + +### Word List + +Use these consistently: + +| Use | Do not use | +|---|---| +| gateway | Gateway (unless starting a sentence) | +| sandbox | Sandbox (unless starting a sentence) | +| CLI | cli, Cli | +| API key | api key, API Key | +| NVIDIA | Nvidia, nvidia | +| OpenShell | Open Shell, openShell, Openshell, openshell | +| mTLS | MTLS, mtls | +| YAML | yaml, Yaml | + +## Submitting Doc Changes + +1. Create a branch following the project convention: `docs/-/`. +2. Make your changes. +3. Build locally with `mise run docs` and verify the output. +4. Run `mise run pre-commit` to catch formatting issues. +5. Open a PR with `docs:` as the conventional commit type. + +``` +docs: update gateway deployment instructions +``` + +If your doc change accompanies a code change, include both in the same PR and use the code change's commit type: + +``` +feat(cli): add --gpu flag to gateway start +``` + +## Reviewing Doc PRs + +When reviewing documentation: + +- Check that the style guide rules above are followed. +- Watch for LLM-generated patterns (excessive bold, em dashes, filler). +- Verify code examples are accurate and runnable. +- Confirm cross-references and links are not broken. +- Build locally to check rendering. diff --git a/fern/versions/latest/pages/about/architecture.mdx b/fern/versions/latest/pages/about/architecture.mdx new file mode 100644 index 000000000..8f2c7bb39 --- /dev/null +++ b/fern/versions/latest/pages/about/architecture.mdx @@ -0,0 +1,57 @@ +--- +title: "How OpenShell Works" +description: "OpenShell architecture overview covering the gateway, sandbox, policy engine, and privacy router." +position: 2 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +OpenShell runs inside a Docker container. Each sandbox is an isolated environment managed through the gateway. Four components work together to keep agents secure. + +```{figure} architecture.svg +``` + +## Components + +The following table describes each component and its role in the system: + +| Component | Role | +|---|---| +| **Gateway** | Control-plane API that coordinates sandbox lifecycle and state, acts as the auth boundary, and brokers requests across the platform. | +| **Sandbox** | Isolated runtime that includes container supervision and policy-enforced egress routing. | +| **Policy Engine** | Policy definition and enforcement layer for filesystem, network, and process constraints. Defense in depth enforces policies from the application layer down to infrastructure and kernel layers. | +| **Privacy Router** | Privacy-aware LLM routing layer that keeps sensitive context on sandbox compute and routes based on cost and privacy policy. | + +## How a Request Flows + +Every outbound connection from agent code passes through the same decision path: + +1. The agent process opens an outbound connection (API call, package install, git clone, and so on). +2. The proxy inside the sandbox intercepts the connection and identifies which binary opened it. +3. If the target is `https://inference.local`, the proxy handles it as managed inference before policy evaluation. OpenShell strips sandbox-supplied credentials, injects the configured backend credentials, and forwards the request to the managed model endpoint. +4. For every other destination, the proxy queries the policy engine with the destination, port, and calling binary. +5. The policy engine returns one of two decisions: + - **Allow** - the destination and binary match a policy block. Traffic flows directly to the external service. + - **Deny** - no policy block matched. The connection is blocked and logged. + +For REST endpoints with TLS termination enabled, the proxy also decrypts TLS and checks each HTTP request against per-method, per-path rules before allowing it through. + +## Deployment Modes + +OpenShell can run locally, on a remote host, or behind a cloud proxy. The architecture is identical in all cases — only the Docker container location and authentication mode change. + +| Mode | Description | Command | +|---|---|---| +| **Local** | The gateway runs inside Docker on your workstation. The CLI provisions it automatically on first use. | `openshell gateway start` | +| **Remote** | The gateway runs on a remote host via SSH. Only Docker is required on the remote machine. | `openshell gateway start --remote user@host` | +| **Cloud** | A gateway already running behind a reverse proxy (e.g. Cloudflare Access). Register and authenticate via browser. | `openshell gateway add https://gateway.example.com` | + +You can register multiple gateways and switch between them with `openshell gateway select`. For the full deployment and management workflow, refer to the [Gateways](/sandboxes/manage-gateways) section. + +## Next Steps + +Continue with one of the following: + +- To deploy or register a gateway, refer to [Gateways](/sandboxes/manage-gateways). +- To create your first sandbox, refer to the [Quickstart](/get-started/quickstart). +- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/about). diff --git a/fern/versions/latest/pages/about/overview.mdx b/fern/versions/latest/pages/about/overview.mdx new file mode 100644 index 000000000..c8a668d7f --- /dev/null +++ b/fern/versions/latest/pages/about/overview.mdx @@ -0,0 +1,58 @@ +--- +title: "Overview of NVIDIA OpenShell" +description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure." +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +NVIDIA OpenShell is an open-source runtime for executing autonomous AI agents in sandboxed environments with kernel-level isolation. It combines sandbox runtime controls and a declarative YAML policy so teams can run agents without giving them unrestricted access to local files, credentials, and external networks. + +## Why OpenShell Exists + +AI agents are most useful when they can read files, install packages, call APIs, and use credentials. That same access can create material risk. OpenShell is designed for this tradeoff: preserve agent capability while enforcing explicit controls over what the agent can access. + +## Common Risks and Controls + +The table below summarizes common failure modes and how OpenShell mitigates them. + +| Threat | Without controls | With OpenShell | +|---|---|---| +| Data exfiltration | Agent uploads source code or internal files to unauthorized endpoints. | Network policies allow only approved destinations; other outbound traffic is denied. | +| Credential theft | Agent reads local secrets such as SSH keys or cloud credentials. | Filesystem restrictions (Landlock) confine access to declared paths only. | +| Unauthorized API usage | Agent sends prompts or data to unapproved model providers. | Privacy routing and network policies control where inference traffic can go. | +| Privilege escalation | Agent attempts `sudo`, setuid paths, or dangerous syscall behavior. | Unprivileged process identity and seccomp restrictions block escalation paths. | + +## Protection Layers at a Glance + +OpenShell applies defense in depth across the following policy domains. + +| Layer | What it protects | When it applies | +|---|---|---| +| Filesystem | Prevents reads/writes outside allowed paths. | Locked at sandbox creation. | +| Network | Blocks unauthorized outbound connections. | Hot-reloadable at runtime. | +| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. | +| Inference | Reroutes model API calls to controlled backends. | Hot-reloadable at runtime. | + +For details, refer to [Sandbox Policies](/sandboxes/about#sandbox-policies) and [Customize Sandbox Policies](/sandboxes/policies). + +## Common Use Cases + +OpenShell supports a range of agent deployment patterns. + +| Use Case | Description | +|-----------------------------|----------------------------------------------------------------------------------------------------------| +| Secure coding agents | Run Claude Code, OpenCode, or OpenClaw with constrained file and network access. | +| Private enterprise development | Route inference to self-hosted or private backends while keeping sensitive context under your control. | +| Compliance and audit | Treat policy YAML as version-controlled security controls that can be reviewed and audited. | +| Reusable environments | Use community sandbox images or bring your own containerized runtime. | + +--- + +## Next Steps + +Explore these topics to go deeper: + +- To understand the components that make up the OpenShell runtime, refer to the [Architecture Overview](/about/architecture). +- To install the CLI and create your first sandbox, refer to the [Quickstart](/get-started/quickstart). +- To learn how OpenShell enforces isolation across all protection layers, refer to [Sandboxes](/sandboxes/about). diff --git a/fern/versions/latest/pages/about/release-notes.mdx b/fern/versions/latest/pages/about/release-notes.mdx new file mode 100644 index 000000000..516336201 --- /dev/null +++ b/fern/versions/latest/pages/about/release-notes.mdx @@ -0,0 +1,16 @@ +--- +title: "NVIDIA OpenShell Release Notes" +description: "Track the latest changes and improvements to NVIDIA OpenShell." +position: 4 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +NVIDIA OpenShell follows a frequent release cadence. Use the following GitHub resources directly. + +| Resource | Description | +|---|---| +| [Releases](https://github.com/NVIDIA/OpenShell/releases) | Versioned release notes and downloadable assets. | +| [Release comparison](https://github.com/NVIDIA/OpenShell/compare) | Diff between any two tags or branches. | +| [Merged pull requests](https://github.com/NVIDIA/OpenShell/pulls?q=is%3Apr+is%3Amerged) | Individual changes with review discussion. | +| [Commit history](https://github.com/NVIDIA/OpenShell/commits/main) | Full commit log on `main`. | diff --git a/fern/versions/latest/pages/about/supported-agents.mdx b/fern/versions/latest/pages/about/supported-agents.mdx new file mode 100644 index 000000000..0aa06e3be --- /dev/null +++ b/fern/versions/latest/pages/about/supported-agents.mdx @@ -0,0 +1,19 @@ +--- +title: "Supported Agents" +description: "" +position: 3 +--- +The following table summarizes the agents that run in OpenShell sandboxes. All agent sandbox images are maintained in the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) repository. Agents in the base image are auto-configured when passed as the trailing command to `openshell sandbox create`. + +| Agent | Source | Default Policy | Notes | +|---|---|---|---| +| [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Full coverage | Works out of the box. Requires `ANTHROPIC_API_KEY`. | +| [OpenCode](https://opencode.ai/) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Partial coverage | Pre-installed. Add `opencode.ai` endpoint and OpenCode binary paths to the policy for full functionality. | +| [Codex](https://developers.openai.com/codex) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | No coverage | Pre-installed. Requires a custom policy with OpenAI endpoints and Codex binary paths. Requires `OPENAI_API_KEY`. | +| [GitHub Copilot CLI](https://docs.github.com/en/copilot/github-copilot-in-the-cli) | [`base`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/base) | Full coverage | Pre-installed. Works out of the box. Requires `GITHUB_TOKEN` or `COPILOT_GITHUB_TOKEN`. | +| [OpenClaw](https://openclaw.ai/) | [`openclaw`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/openclaw) | Bundled | Agent orchestration layer. Launch with `openshell sandbox create --from openclaw`. | +| [Ollama](https://ollama.com/) | [`ollama`](https://github.com/NVIDIA/OpenShell-Community/tree/main/sandboxes/ollama) | Bundled | Run cloud and local models. Includes Claude Code, Codex, and OpenCode. Launch with `openshell sandbox create --from ollama`. | + +More community agent sandboxes are available in the [Community Sandboxes](/sandboxes/community-sandboxes) catalog. + +For a complete support matrix, refer to the [Support Matrix](/reference/support-matrix) page. diff --git a/fern/versions/latest/pages/get-started/quickstart.mdx b/fern/versions/latest/pages/get-started/quickstart.mdx new file mode 100644 index 000000000..c53f1ddf0 --- /dev/null +++ b/fern/versions/latest/pages/get-started/quickstart.mdx @@ -0,0 +1,154 @@ +--- +title: "Quickstart" +description: "Install the OpenShell CLI and create your first sandboxed AI agent in two commands." +position: 1 +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + +This page gets you from zero to a running, policy-enforced sandbox in two commands. + +## Prerequisites + +Before you begin, make sure you have: + +- Docker Desktop running on your machine. + +For a complete list of requirements, refer to [Support Matrix](/reference/support-matrix). + +## Install the OpenShell CLI + +Run the install script: + +```shell +curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh +``` + +If you prefer [uv](https://docs.astral.sh/uv/): + +```shell +uv tool install -U openshell +``` + +After installing the CLI, run `openshell --help` in your terminal to see the full CLI reference, including all commands and flags. + + +You can also clone the [NVIDIA OpenShell GitHub repository](https://github.com/NVIDIA/OpenShell) and use the `/openshell-cli` skill to load the CLI reference into your agent. + + + +## Create Your First OpenShell Sandbox + +Create a sandbox and launch an agent inside it. +Choose the tab that matches your agent: + + + + +Run the following command to create a sandbox with Claude Code: + +```shell +openshell sandbox create -- claude +``` + +The CLI prompts you to create a provider from local credentials. +Type `yes` to continue. +If `ANTHROPIC_API_KEY` is set in your environment, the CLI picks it up automatically. +If not, you can configure it from inside the sandbox after it launches. + + + + +Run the following command to create a sandbox with OpenCode: + +```shell +openshell sandbox create -- opencode +``` + +The CLI prompts you to create a provider from local credentials. +Type `yes` to continue. +If `OPENAI_API_KEY` or `OPENROUTER_API_KEY` is set in your environment, the CLI picks it up automatically. +If not, you can configure it from inside the sandbox after it launches. + + + + +Run the following command to create a sandbox with Codex: + +```shell +openshell sandbox create -- codex +``` + +The CLI prompts you to create a provider from local credentials. +Type `yes` to continue. +If `OPENAI_API_KEY` is set in your environment, the CLI picks it up automatically. +If not, you can configure it from inside the sandbox after it launches. + + + + +Run the following command to create a sandbox with OpenClaw: + +```shell +openshell sandbox create --from openclaw +``` + +The `--from` flag pulls a pre-built sandbox definition from the [OpenShell Community](https://github.com/NVIDIA/OpenShell-Community) catalog. +Each definition bundles a container image, a tailored policy, and optional skills into a single package. + + + + +Use the `--from` flag to pull other OpenShell sandbox images from the [NVIDIA Container Registry](https://registry.nvidia.com/). +For example, to pull the `base` image, run the following command: + +```shell +openshell sandbox create --from base +``` + + + + + +## Deploy a Gateway (Optional) + +Running `openshell sandbox create` without a gateway auto-bootstraps a local one. +To start the gateway explicitly or deploy to a remote host, choose the tab that matches your setup. + + + + + +Deploy an OpenShell gateway on Brev by clicking **Deploy** on the [OpenShell Launchable](https://brev.nvidia.com/launchable/deploy/now?launchableID=env-3Ap3tL55zq4a8kew1AuW0FpSLsg). + + + +After the instance starts running, find the gateway URL in the Brev console under **Using Secure Links**. +Copy the shareable URL for **port 8080**, which is the gateway endpoint. + +```shell +openshell gateway add https://.brevlab.com +openshell status +``` + + + + + + +Set up your Spark with NVIDIA Sync first, or make sure SSH access is configured (such as SSH keys added to the host). + + + +Deploy to a DGX Spark machine over SSH: + +```shell +openshell gateway start --remote @.local +openshell status +``` + +After `openshell status` shows the gateway as healthy, all subsequent commands route through the SSH tunnel. + + + + diff --git a/fern/versions/latest/pages/index.mdx b/fern/versions/latest/pages/index.mdx new file mode 100644 index 000000000..2ce01eb37 --- /dev/null +++ b/fern/versions/latest/pages/index.mdx @@ -0,0 +1,141 @@ +--- +title: "NVIDIA OpenShell Developer Guide" +description: "OpenShell is the safe, private runtime for autonomous AI agents. Run agents in sandboxed environments that protect your data, credentials, and infrastructure." +position: 1 +--- + +import { BadgeLinks } from "@/components/BadgeLinks"; + +{/* SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. + SPDX-License-Identifier: Apache-2.0 */} + + + +NVIDIA OpenShell is the safe, private runtime for autonomous AI agents. It provides sandboxed execution environments +that protect your data, credentials, and infrastructure. Agents run with exactly the permissions they need and +nothing more, governed by declarative policies that prevent unauthorized file access, data exfiltration, and +uncontrolled network activity. + +## Get Started + +Install the CLI and create your first sandbox in two commands. + +{/* Terminal demo styles live in fern/main.css — inline