Run Your First Agent

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 defines the credentials, service endpoints, and executable paths an agent may use.

This example runs OpenCode against OpenRouter. Review the example profile, which allows /usr/local/bin/opencode to reach openrouter.ai, then import it and create a provider that stores its credentials.

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 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 when the agent needs more filesystem access, package registries, source hosts, tool servers, or other destinations.

3. Create the sandbox.

Create the sandbox, attach the provider, and pass the agent command after --:

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.

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’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 before you review it.

List pending proposals from the host:

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:

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.

Examples

For a complete worked example, follow Run Pi in OpenShell. 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.
• For the restrictive fallback policy, refer to Default Policy.
• For operating-system and runtime requirements, refer to the Support Matrix.