mirror of
https://github.com/NVIDIA/OpenShell.git
synced 2026-10-20 06:00:06 +08:00
Fede Kamelhar
71440b28f4
* fix(policy): refresh pending proposals when the sandbox policy changes Approving, removing, or undoing a rule, or updating the sandbox policy, changes the inputs every other pending proposal was evaluated against. Only proposals the new policy covered were reconciled; the rest kept their old prover result and review token. The review surface (GetDraftPolicy) therefore showed a stale evaluation, and the first approval of the next proposal refreshed it and failed with FAILED_PRECONDITION, so approving proposals one after another always failed once. Re-evaluate the remaining pending proposals at each policy change, reusing the cached prover result unless the proposal's inputs changed. Approval still rejects a review token that does not match the stored evaluation, so a reviewer holding a pre-refresh evaluation must still refetch it. When a refresh does happen at approval time (inputs changed between fetch and approve), the CLI now explains that the rule was re-evaluated and how to review it, instead of printing the raw gRPC status. Closes #3884 Signed-off-by: fede-kamel <fkamelhar@gmail.com> * fix(policy): make pending proposal refresh race-safe and bounded Store refreshed evaluations with a compare-and-swap: the store re-reads the proposal, refuses when its rule name, proposed rule, or review token changed since the evaluation read it, copies only the evaluation fields onto the stored record, and updates only if the payload is still the one it read. A refresh can no longer revert a concurrent edit or observation, and the edit path uses the same guard against a concurrent refresh. Bound each refresh to the 32 newest pending proposals; the rest keep the approval-time recheck, which still refuses a stale review token. Operator decisions (approve, approve-all, remove, undo) refresh before responding. UpdateConfig, which holds the gateway-wide sandbox sync guard, and agent-driven auto-approval refresh in a background task instead, one per sandbox with later changes coalesced into a single rerun. Refs #3884 Signed-off-by: fede-kamel <fkamelhar@gmail.com> * docs(policy): describe proposal rechecks after approvals and approve-all Explain that approving, removing, or undoing a rule rechecks the other pending proposals so they can be approved one after another, when the recheck is deferred or bounded, and what rule approve reports when a proposal changed after it was listed. Show rule approve-all in Run Your First Agent with its security-flag behavior. Refs #3884 Signed-off-by: fede-kamel <fkamelhar@gmail.com> * fix(policy): refresh pending proposals after a full policy replacement A full policy UpdateConfig (openshell policy set) re-reads the latest revision after its atomic write, finds the revision it just committed, and returns before reaching the pending-proposal refresh at the end of the handler. Pending proposals kept their stale evaluation, so rule get showed the old candidate and the next approval failed with the refresh precondition. Schedule the background refresh right after the commit. Refs #3884 Signed-off-by: fede-kamel <fkamelhar@gmail.com> --------- Signed-off-by: fede-kamel <fkamelhar@gmail.com>
127 lines
4.6 KiB
Plaintext
127 lines
4.6 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."
|
|
```
|
|
|
|
Approving a proposal rechecks the other pending proposals against the updated
|
|
policy, so you can list them again and approve them one after another. To
|
|
approve every pending proposal in one step, run:
|
|
|
|
```shell
|
|
openshell rule approve-all my-agent
|
|
```
|
|
|
|
`rule approve-all` skips proposals with a security flag unless you add
|
|
`--include-security-flagged`, and it reports how many it skipped.
|
|
|
|
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 with OpenRouter](/tutorials/run-pi-with-openrouter).
|
|
The tutorial builds a Pi image, configures narrowly scoped OpenRouter 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).
|