OpenShell MCP for OpenWork

An MCP tool to use NVIDIA OpenShell with OpenWork agents. Includes a custom agent for OpenWork with no network access by default, forcing it to route all network access through an OpenShell sandbox.

Agents get an isolated sandbox environment with zero network egress by default. This MCP allows users to use OpenShell sandboxes through natural language prompting with the custom agent automatically reaching for a sandbox to do tasks that require network access. All policy changes are gated by native OS approval dialogs for security.

Expanding on test MCPs from openwork-demo-test

Intended for use with OpenShell deployed on OpenShift. For detailed setup instructions including deploying OpenShell on OpenShift see the detailed guide here.

How it works

• Default-deny: Sandboxes start with zero network egress. Web requests and package installs fail until the user approves access.
• Approval dialogs: apply_policy, destroy_sandbox, and sandbox-creation-with-policy trigger a native OS dialog (osascript on macOS, zenity/tkinter on Linux) listing exactly what the policy grants. Denials hit a cooldown (default 60s) so the agent can't spam retries.
• Hot-reload: Network rules are applied, the sandbox keeps running, nothing is destroyed.
• Agent-written policies: The agent can draft policy YAML in the workspace or apply existing policies; use list_policies to see available policies, or the agent can search for a suitable policy and/or create one. Nothing is applied without manual approval via dialog.
• Binary-aware enforcement: The gateway runs with process_binary_aware_network_policy = true, so every policy entry lists the binaries allowed to use an endpoint (e.g. curl).

Deploying the MCP

Prerequisites: OpenShift cluster up and logged in with OpenShell deployed and gateway configured.

For more detailed instructions including deploying OpenShell on OpenShift, see DEPLOYMENT.md

1. Port-forward the gateway

If it's not already running from deploying OpenShell, start/restart the port-forward.

oc -n openshell port-forward svc/openshell 8080:8080

2. Start the MCP server

cd /your/path/to/openshell-mcp

source .venv/bin/activate

export OPENSHELL_GATEWAY=openshift # this should match the name of your openshell gateway
export POLICIES_DIR=./policies
export WORKSPACE_DIR=/path/to/your/openwork/workspace

python3 server.py

Listens on http://0.0.0.0:8765/mcp. To kill it, use Ctrl+C or kill $(lsof -ti:8765).

3. Verify OpenWork connects

For first-time deployment, you need to register the MCP with OpenWork.

• Navigate via UI to Settings > Extensions > Add Custom App
• Supply the url: http://localhost:8765/mcp and a name: openshell-mcp.
• The MCP should show as green. Verify by using a simple tool (e.g. ask the agent to "list my sandboxes").

From then on, OpenWork should auto-connect to the MCP server. To check:

• Settings → MCP Servers → openshell-mcp shows green
• You can call openshell-mcp_list_sandboxes from a chat

Optionally, the MCP can be registered via opencode.jsonc: "mcp": { "openshell-mcp": { "type": "remote", "url": "http://localhost:8765/mcp", "enabled": true } }

The sandbox agent

The sandbox-agent agent makes it so the sandbox is the only way the agent can execute anything. All native tools are denied except for basic read/write file permissions within the workspace. This way the agent cannot access the web without going through a sandbox.

Tool	Permission	Why
bash / websearch / webfetch	deny	Execution and web must go through the sandbox
task	deny	Subagents may have unrestricted tools
browser_*, openwork_browser_*	deny	Built-in browser = uncontrolled web access
openwork-cloud_*	deny	OpenWork Cloud MCP (Gmail/Drive/Calendar)
openwork_extension_*	deny	Extension actions
openwork_session_*	deny	Cross-session history
list_mcp_resource*, read_mcp_resource	deny	MCP resource access
read / edit / write	allow	File work happens normally outside the sandbox
openshell-mcp_*	allow	The sandbox is the only execution path

Installing/Using the agent

By placing agent files in an agents or agent directory, they are auto-discovered at OpenWork startup.

• Copy agents/sandbox-agent.md to <your-workspace>/.opencode/agents/sandbox-agent.md.
• To pick up your changes, restart OpenWork.
• To use the custom agent, choose Sandbox-agent from the dropdown menu at the bottom of your input box in a chat.

Environment variables

OPENSHELL_GATEWAY, POLICIES_DIR, AND WORKSPACE-DIR should be specified when deploying (as outlined above.) This is because they are likely different for everyone. Values like CLI_TIMEOUT, USER_APPROVAL_TIMEOUT, and DENIAL_COOLDOWN_SECONDS are populated with reasonable default values, but can be customised as needed.

Variable	Default	Description
OPENSHELL_GATEWAY	openshell-mcp	Gateway name from ~/.openshell/config.yaml
POLICIES_DIR	/app/policies	Directory with policy YAML files
WORKSPACE_DIR	~	Workspace root; agent-created policies in <WORKSPACE_DIR>/policies are auto-discovered
CLI_TIMEOUT	60	Seconds before openshell CLI calls time out
USER_APPROVAL_TIMEOUT	300	Seconds before the approval dialog auto-dismisses
DENIAL_COOLDOWN_SECONDS	60	Seconds before a denied tool+target can ask again

Policy files

Policy files are YAML files with network_policies, aka rules about what your agent can and cannot access. This repo has a policies directory with samples. Even if they are not useful for your specific use-case, by pointing your agent to them (by specifying the POLICIES_DIR) it will learn how to create its own policies to fit your needs. Agent-created policies will be saved within your workspace (WORKSPACE_DIR) and can be applied like any other policy, with a native OS approval dialog for security. For more details about policy files and creating your own, visit the OpenShell documentation

Troubleshooting

• If web requests are still blocked after applying a policy, check than binaries have been specified. The gateway requires binaries: entries, make sure the binary you're using (e.g. /usr/bin/curl/) is included.
• Gateway connection issues/gateway connection refused: check that the port forward is still running. It may need to be restarted (oc -n openshell port-forward svc/openshell 8080:8080)
• If changes are not picked up/agent shows as unavailable, OpenWork/MCP may need a restart. Agent updates/changes are only discovered on restart, so quit and reopen OpenWork. For changes to server.py, kill the process (ctrl + c or kill $(lsof -ti:8765) and restart it (python3 server.py).
• Custom policy apply fails (usually with something like "missing field version"): the agent may have made an incorrect assumption about the format of a policy file. With the context of the sample policy files and the error message it should be able to self-resolve, but if not, use the default agent to point it to the NVIDIA OpenShell docs (such as the policy scheme reference here) or provide it with a schema outline in chat to resolve without switching agents.