Run Your First Agent

OpenShell can run an AI agent or another autonomous command when its executable is available in the sandbox image. The image, provider profile, and policy define what the workload can execute and access. OpenShell does not require the agent to use a specific framework or model API.

Prepare the Workload

An agent needs three pieces:

Build and maintain an OCI image for each workload. Install the agent, shell, development tools, CA certificates, and language runtimes that the workload needs. Use pinned versions so you can review and reproduce image updates.

docker build -t registry.example.com/team/agent:1.0 .
docker push registry.example.com/team/agent:1.0
openshell sandbox create --from registry.example.com/team/agent:1.0

The --from option also accepts a local rootfs archive. It does not build a Dockerfile or directory. Refer to Custom Containers for image and runtime details. The fallback image contains no agent or development toolchain, so pass your image explicitly for agent workloads.

Prepare Provider Access

A provider profile defines the credentials and endpoints an agent uses. The gateway serves only profiles that an administrator or user has imported. Review a profile before importing it, especially its executable paths and network endpoints.

curl -LsSfO https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/claude-code.yaml
openshell profile import -f claude-code.yaml --global
ANTHROPIC_API_KEY=<your-key> \
  openshell provider create --name my-claude --type claude-code --from-existing

The repository includes example profiles in providers/. Copy and adapt an example when the agent binary is installed at another path or uses a different service endpoint. Refer to Profiles for the profile schema and import workflow.

Launch the Agent

Pass the agent command after -- and attach the provider instances it needs. For example, this command starts Claude Code from an image your team built with the claude executable installed:

openshell sandbox create \
  --from registry.example.com/team/claude-code:1.0 \
  --provider my-claude \
  -- claude

The command before -- configures the sandbox. The command after -- becomes the sandbox’s main process. OpenShell keeps the sandbox after that process exits unless you pass --no-keep.

Use --detach for an unattended or long-running agent:

openshell sandbox create \
  --name worker \
  --detach \
  --from my-registry.example.com/team/agent:latest \
  --provider model-provider \
  -- ./worker

Use a profile-backed provider for credentials that the agent should not read directly. Plain values passed with --env are visible to the agent process.

Build an Agent Image

Prepare each agent as part of your normal container build and release process:

1. Select a trusted base image and install the agent executable and tools.
2. Create or adapt provider profiles for every external service the agent uses.
3. Add policy rules for required files, child processes, package registries, tool servers, and other network destinations.
4. Build, scan, sign, and publish the image to a registry the gateway can pull.
5. Launch the executable as the sandbox’s main process.

Provider profiles can contribute endpoint and executable rules to the effective policy. They do not grant unrelated network or filesystem access. Use Customize Sandbox Policies when the agent needs access beyond its attached providers.

Verify and Troubleshoot

Inspect the sandbox, effective policy, provider attachments, and logs:

openshell sandbox list
openshell policy get my-sandbox --full
openshell sandbox provider list my-sandbox
openshell logs my-sandbox --tail

If the executable is missing, change the sandbox image. If a provider request is denied, confirm that the profile names the actual endpoint and executable path. For another denied network or filesystem operation, update the sandbox policy after reviewing the requested access.

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.