> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/openshell/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/openshell/_mcp/server.

# Run Your First Agent

> Prepare a sandbox image, provider profile, and policy for an AI agent or another autonomous workload.

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:

| Requirement      | Purpose                                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Sandbox image    | Contains the agent executable and its runtime dependencies.                                                             |
| Provider profile | Declares credential fields, service endpoints, and the executable paths allowed to use them.                            |
| Sandbox policy   | Controls filesystem access, process behavior, and network destinations beyond access contributed by attached providers. |

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.

```shell
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](/sandboxes/manage-sandboxes#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.

```shell
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/`](https://github.com/NVIDIA/OpenShell/tree/main/providers). Copy
and adapt an example when the agent binary is installed at another path or uses
a different service endpoint. Refer to [Profiles](/providers/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:

```shell
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:

```shell
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](/sandboxes/policies) when the agent needs access
beyond its attached providers.

## Verify and Troubleshoot

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

```shell
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](/sandboxes/manage-sandboxes).
* For the restrictive fallback policy, refer to
  [Default Policy](/reference/default-policy).
* For operating-system and runtime requirements, refer to the
  [Support Matrix](/reference/support-matrix).