I have recently been exploring NVIDIA OpenShell. When building enterprise Agent applications, file permissions, access to external services and API key management always need attention. Teams have often had to assemble their own solutions. OpenShell brings these capabilities into the Agent runtime, making it worth trying in practice.
So I worked through the official Run Your First Agent guide: starting OpenCode inside an OpenShell sandbox and calling a Nemotron model through OpenRouter.
The official flow is short: configure a provider → choose an image → create a sandbox and launch OpenCode. My computer runs Windows, so I used WSL2 + Docker Desktop. What actually took time was the networking configuration and sandbox startup compatibility in this environment.
Here are the two most important settings from this run, before we look at what each one addressed:
| Where | Setting used in this run | Issue addressed |
|---|---|---|
| Docker Desktop | Turn on Enable host networking | Support the supervisor’s Host network mode in this run and verify container access to the gateway |
.wslconfig in the Windows user directory |
Change networkingMode=mirrored to nat |
A seccomp initialization error in this environment; after the change and a full restart, the sandbox started successfully |
These are settings at two different levels. After enabling Docker Desktop host networking, we confirmed connectivity, but the sandbox still exited. Only after capturing the seccomp logs and changing WSL’s networking mode did we reach OpenCode.
Test environment: WSL2, Docker Desktop 4.46.0 / Engine 28.4.0, OpenShell 0.1.5. This article starts after OpenShell installation and records the results in this particular environment. NAT was an effective workaround here; this does not mean every version requires NAT.
Before starting: connect WSL to Docker Desktop
In Docker Desktop, go to Settings → Resources → WSL Integration and confirm that integration is enabled for the Linux distribution you are using. This lets the Docker client in WSL use the Docker Desktop engine. [1]
Check the following in WSL:
ps -p 1 -o comm=
docker version
openshell status
Confirm that PID 1 is systemd, Docker shows both Client and Server, and OpenShell reports Connected.
The gateway may need ten or more seconds to initialize after starting. If an immediate check returns Connection refused, wait briefly and try again. If it keeps failing, check the service logs.
Configure the provider and create the sandbox
Follow the official procedure first. The errors described later all occurred after sandbox creation was initiated.
Set your own OpenRouter key in the current WSL terminal:
read -rsp "OpenRouter API Key: " OPENROUTER_API_KEY
echo
export OPENROUTER_API_KEY
Then import the profile and create the provider as shown in the official example:
openshell profile import \
--url https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/openrouter.yaml
openshell provider create \
--name openrouter \
--type openrouter \
--from-existing
We also missed the key at this stage and received no existing local credentials/config found. Once the credentials were available in the current WSL environment, provider creation succeeded. Importing a profile does not generate an API key for you.
Next, create the sandbox using the OpenCode image specified in the official guide:
openshell sandbox create \
--name my-agent \
--from ghcr.io/anomalyco/opencode:latest \
--provider openrouter \
-- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free
We expected to enter OpenCode, but instead stopped here:
ControlSupervisorStartFailed:
Docker sandbox exited before supervisor became ready
The image had been pulled successfully, but the Agent had not started. There was no need to adjust model parameters yet; Docker Desktop and WSL were the next things to investigate.
First issue: enable Docker Desktop host networking separately
Inspect the gateway logs:
journalctl -b _SYSTEMD_USER_UNIT=openshell-gateway.service \
-n 150 --no-pager -o cat
They show the network mode and gateway address used by the supervisor in this run:
network_mode=Host
endpoint=https://127.0.0.1:17670
This is easy to overlook: being able to reach the gateway from a WSL terminal does not mean a Docker Desktop container can reach it too. WSL Integration lets you use Docker, but it is a separate setting from host networking.
In Docker Desktop, go to:
Settings → Resources → Network → select Enable host networking → Apply and restart.
Docker Desktop has supported this feature since version 4.34, and it must be enabled in settings. This run used 4.46.0. [2]
After applying the setting, test from inside a container:
docker run --rm --network host curlimages/curl:latest \
--noproxy '*' -vk --connect-timeout 5 --max-time 10 \
https://127.0.0.1:17670/
This time, the TLS handshake succeeded and returned:
HTTP/2 404
A 404 is acceptable here: there is no resource at the gateway’s root path, but the request has reached the service. The command uses -k for connection troubleshooting only; this does not establish that certificate validation or application authentication has passed.
At this point, we had confirmed the path from the container to the gateway. But recreating the sandbox still produced the same startup failure. Connectivity checks alone were not enough; we needed to find out why the container was exiting.
Second issue: sandbox startup stalled at seccomp in WSL mirrored mode
We then tried docker ps -a to find the failed container, but it was already gone. It had been cleaned up after exiting, so checking its logs afterwards was too late.
The solution was to open two terminals and capture the logs in advance.
Terminal A: listen for container start events and immediately follow the logs:
docker events --filter type=container --filter event=start \
--format '{{.Actor.ID}} {{index .Actor.Attributes "name"}}' |
while read -r cid cname; do
case "$cname" in
openshell-*)
(
printf '\n--- %s ---\n' "$cname"
docker logs --timestamps --follow "$cid" 2>&1
) &
;;
esac
done
Terminal B: run the earlier creation command again, changing the name to an unused my-agent-debug.
This time, we captured the specific error:
seccomp notification probe
Resource busy (os error 16)
The problem was not an unreachable gateway. The workload was exiting during sandbox isolation initialization.
WSL was configured with networkingMode=mirrored. We found OpenShell issue #3842, which described a similar seccomp error and recovery after switching to NAT. We tested that approach.
Edit .wslconfig on Windows
The file is located at:
C:\Users\<your-Windows-username>\.wslconfig
Keep existing memory, CPU and other settings. Change only the networking mode under [wsl2]:
[wsl2]
networkingMode=nat
This is .wslconfig in the Windows user directory, not /etc/wsl.conf in Linux. If a [wsl2] section already exists, edit the corresponding setting there.
Save your work and quit Docker Desktop, then run the following in Windows PowerShell:
wsl --shutdown
This stops the running WSL instances. Restart Docker Desktop, open WSL again, and confirm that openshell status returns Connected.
Recreate the sandbox and enter OpenCode
Run the creation command again with the new name my-agent-nat, leaving the other arguments unchanged:
openshell sandbox create \
--name my-agent-nat \
--from ghcr.io/anomalyco/opencode:latest \
--provider openrouter \
-- opencode -m openrouter/nvidia/nemotron-3.5-lightning:free
This time, the OpenCode interface appeared normally. The sandbox startup hurdle was finally cleared.
The surprising part is that a setting called “networking mode” resolved the seccomp initialization error in this run. The earlier curl check had already confirmed gateway reachability, so these two fixes should not both be reduced to “the network was down.”
If you also use mirrored mode and see the same seccomp error in the logs, this workaround may be useful. After switching to NAT, also check whether your existing Windows proxy or other access methods that depend on mirrored mode still work.
After startup: verify model authentication separately
Once inside OpenCode, our first message, “你好” (“Hello”), produced another error:
Missing Authentication header
This was now a model authentication issue and needed to be investigated separately from the earlier WSL startup failure.
Checking openshell provider list -o yaml can confirm that credential fields exist, but it cannot prove that the saved key is valid. Seeing a placeholder key inside the sandbox is also normal: in this mechanism, OpenShell resolves and substitutes credentials in HTTP requests that meet the policy. [3]
After rechecking and configuring the correct OpenRouter key, the model returned a normal reply in Chinese. To update an existing provider, set the new key in WSL and run:
openshell provider update openrouter --from-existing
Then start a new Agent client process so that it picks up the updated credential reference. Changing only the current shell’s environment variables does not automatically update the saved provider.
Checks to take away from this run
In the end, the official example reached both sandbox startup and a model conversation. Looking back, the key distinction in this WSL + Docker Desktop environment is between three settings:
| Setting | Purpose |
|---|---|
| WSL Integration | Let the current WSL distribution use Docker Desktop |
| Enable host networking | Support the Host network connection used by the supervisor in this run |
| WSL networkingMode=nat | Work around the seccomp startup error encountered in mirrored mode in this run |
After enabling host networking and verifying gateway reachability, the sandbox still failed to start. Only after switching to NAT and fully restarting did we enter OpenCode. That sequence is more useful than simply remembering to “turn on a switch.”
Tool execution, permission enforcement and extended start/stop testing have not yet been completed. Next, we will bring our own Agent workflows into the environment to verify internal service access and permission configuration.
If your team is also deploying Agent prototypes into real environments, we welcome a conversation with CHNEUR AB about your specific scenario.
