mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-26 06:52:57 +08:00
Drew NewberryandPiotr Mlocek
73a181d32f
* docs(readme): streamline README and move reference detail to docs Restructure the README as a short path from overview to quickstart to further reading. Move prerelease install steps into the installation guide and telemetry build flags into a new observability page. Fix broken docs links and outdated runtime and credential descriptions. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(readme): describe 0.1.0 as adding new isolation primitives Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): add policy prover as a gateway component Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs: describe OpenShell as a runtime for fleets of autonomous AI agents Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): describe policy prover as formal verification Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): name OpenShell Sandbox in component table Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): fold isolation backend into supervisor row Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(architecture): mention formal verification in overview Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): use the published OpenCode image in the first-agent guide Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(inference): correct provider examples and readiness Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(providers): correct Google binding and provider selection Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> * docs(readme): sharpen value prop, how it works, and explore further Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): use example Anthropic profile and add policy advisor step Import the example Anthropic profile, which now allows OpenCode, instead of editing it with sed. Add a step that shows how to review and approve mechanistic policy proposals as the agent needs more access. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * feat(providers): add OpenRouter example for OpenCode Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(run-agent): run OpenCode against OpenRouter with a free model Add an example OpenRouter provider profile scoped to OpenCode and switch the first-agent guide to it, using a free Nemotron model so readers do not need OpenRouter credits. Revert the OpenCode binary added to the example Anthropic profile. Signed-off-by: Drew Newberry <anewberry@nvidia.com> * docs(readme): link first-agent guide and add agent skills section Signed-off-by: Drew Newberry <anewberry@nvidia.com> --------- Signed-off-by: Drew Newberry <anewberry@nvidia.com> Signed-off-by: Piotr Mlocek <pmlocek@nvidia.com> Co-authored-by: Piotr Mlocek <pmlocek@nvidia.com>
116 lines
4.2 KiB
Plaintext
116 lines
4.2 KiB
Plaintext
---
|
|
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
|
|
# SPDX-License-Identifier: Apache-2.0
|
|
title: "Run Your First Agent"
|
|
sidebar-title: "Run Your First Agent"
|
|
description: "Configure a provider, image, and policy to run an AI agent in an OpenShell sandbox."
|
|
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Provider Profiles, Policies, Custom Images"
|
|
position: 4
|
|
---
|
|
|
|
OpenShell can run any agent that is available in a sandbox image. Configure the
|
|
agent's external services, choose its image and policy, then create the sandbox
|
|
with the agent as its main process.
|
|
|
|
**1. Configure what the agent has access to.**
|
|
|
|
A [provider profile](/how-it-works/providers/profiles) defines the credentials, service
|
|
endpoints, and executable paths an agent may use.
|
|
|
|
This example runs OpenCode
|
|
against OpenRouter. Review the
|
|
[example profile](https://github.com/NVIDIA/OpenShell/blob/main/providers/openrouter.yaml),
|
|
which allows `/usr/local/bin/opencode` to reach `openrouter.ai`, then import
|
|
it and [create a provider](/how-it-works/providers/overview#create-a-provider)
|
|
that stores its credentials.
|
|
|
|
```shell
|
|
openshell profile import \
|
|
--url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml
|
|
|
|
openshell provider create \
|
|
--name openrouter \
|
|
--type openrouter \
|
|
--from-existing
|
|
```
|
|
|
|
Set `OPENROUTER_API_KEY` before creating the provider. OpenShell stores its
|
|
value in the credential store and sends it only to `openrouter.ai`.
|
|
|
|
**2. Choose the sandbox image.**
|
|
|
|
Use any [sandbox image](/how-it-works/sandboxes/overview#sandbox-images) that
|
|
contains the agent and every tool it needs.
|
|
|
|
In this example, the OpenCode image installs `opencode` at `/usr/local/bin/opencode`.
|
|
|
|
Create a custom [sandbox policy](/how-it-works/policies/overview) when the
|
|
agent needs more filesystem access, package registries, source hosts, tool
|
|
servers, or other destinations.
|
|
|
|
**3. Create the sandbox.**
|
|
|
|
[Create the sandbox](/how-it-works/sandboxes/overview#create-a-sandbox), attach the
|
|
provider, and pass the agent command after `--`:
|
|
|
|
```shell
|
|
openshell sandbox create \
|
|
--name my-agent \
|
|
--from ghcr.io/anomalyco/opencode:latest \
|
|
--provider openrouter \
|
|
-- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free
|
|
```
|
|
|
|
OpenCode detects the OpenRouter credential and starts with the model passed to
|
|
`-m`. This example uses a free model, so it works without OpenRouter credits.
|
|
Choose any model from `opencode models openrouter`.
|
|
|
|
For more control over what the agent can access, refer to
|
|
[Policies](/how-it-works/policies/overview).
|
|
|
|
**4. Grant more access as the agent needs it.**
|
|
|
|
When the agent reaches a destination that policy does not allow, OpenShell
|
|
denies the request and drafts a rule for it. The
|
|
[policy advisor](/how-it-works/policies/advisor)'s mechanistic mapper groups
|
|
recent denials by host, port, and calling program, then submits a narrow
|
|
proposal to the gateway. The gateway checks each proposal with the
|
|
[policy prover](/how-it-works/policies/prover) before you review it.
|
|
|
|
List pending proposals from the host:
|
|
|
|
```shell
|
|
openshell rule get my-agent --status pending
|
|
```
|
|
|
|
Approve a proposal when its rule matches the access you intend to grant, or
|
|
reject it with a reason:
|
|
|
|
```shell
|
|
openshell rule approve my-agent --chunk-id <chunk-id>
|
|
|
|
openshell rule reject my-agent \
|
|
--chunk-id <chunk-id> \
|
|
--reason "Not needed for this task."
|
|
```
|
|
|
|
Approved rules hot-reload into the running sandbox without a restart, so the
|
|
agent can retry the request. To let the agent propose its own narrower rules,
|
|
or to approve proposals automatically when the prover finds no new risk, refer
|
|
to [Policy Advisor](/how-it-works/policies/advisor).
|
|
|
|
## Examples
|
|
|
|
For a complete worked example, follow [Run Pi in OpenShell](/tutorials/run-pi).
|
|
The tutorial builds a Pi image, configures narrowly scoped Anthropic access,
|
|
uploads a project, and starts the agent inside the sandbox boundary.
|
|
|
|
## Next Steps
|
|
|
|
- For sandbox lifecycle, resources, templates, files, and connectivity, refer
|
|
to [Sandboxes](/how-it-works/sandboxes/overview).
|
|
- For the restrictive fallback policy, refer to
|
|
[Default Policy](/how-it-works/policies/default-policy).
|
|
- For operating-system and runtime requirements, refer to the
|
|
[Support Matrix](/about/support-matrix).
|