ns-hpc
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ns-hpc Create a new sandbox workspace for testing."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
ns-hpc MCP Server
HPC sandboxing via bubblewrap — an MCP server that manages sandbox instances and executes commands inside isolated bwrap containers.
pip install git+https://github.com/li-yq/namespaced-hpc-mcp.gitQuick Start
# Run diagnostics
ns-hpc doctor
# Create an instance and run a command
ns-hpc instance create my-inst
ns-hpc bwrap my-inst -- ls -la
# Interactive shell
ns-hpc instance enter my-inst
# Start the MCP server
ns-hpc run # stdio (default)
ns-hpc run --transport streamable-http # HTTP on :8000/mcp
ns-hpc run -t streamable-http --uds /tmp/ns-hpc.sock # Unix socketRelated MCP server: secure-cluster-mcp
Architecture
┌─────────────────────────────────────────────┐
│ MCP Client (LLM) │
└──────────────┬──────────────────────────────┘
│ stdio / streamable-http / SSE
┌──────────────▼──────────────────────────────┐
│ ns-hpc MCP Server │
│ │
│ ┌──────────────────────┐ ┌─────────────┐ │
│ │ submit_job / poll_job│ │ WebDAV /dav │ │
│ │ (bwrap exec) │ │ (GET/PUT) │ │
│ └──────────┬───────────┘ └──────┬──────┘ │
│ │ │ │
│ ┌──────────▼──────────────────────▼───────┐ │
│ │ bwrap sandbox │ │
│ │ ┌──────────────────────────────────┐ │ │
│ │ │ /workspace (rw, bind-mounted) │ │ │
│ │ │ /output (rw, bind-mounted) │ │ │
│ │ │ /usr /lib /bin /etc (ro) │ │ │
│ │ │ /proc /dev (virtual) │ │ │
│ │ │ /tmp (tmpfs) │ │ │
│ │ └──────────────────────────────────┘ │ │
│ └────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Instance: ~/.local/share/ns-hpc/ │ │
│ │ instances/{id}/ │ │
│ │ ├── workspace/ (rw host-side bind) │ │
│ │ ├── .ns_hpc_output/ (job outputs) │ │
│ │ ├── .ns_hpc_jobs/ (job state) │ │
│ │ ├── status/ (bwrap fd) │ │
│ │ ├── metadata.json │ │
│ │ └── audit.log (host-side only) │ │
│ └──────────────────────────────────────┘ │
└─────────────────────────────────────────────┘Key Design Decisions
Stateless bwrap: Every command creates a fresh sandbox. No persistent Linux namespaces. The kernel tears down the sandbox when the outer bwrap process exits.
Audit log on host: Written outside the sandbox — the sandbox cannot tamper with its own audit trail.
Shared network:
--share-netoverrides--unshare-all, so processes inside bwrap share the host network namespace. This enables WebDAV and proxied MCP servers to bind ports reachable from the host.
Configuration
Configuration merges three layers (highest priority last):
Built-in defaults
~/.config/ns-hpc/config.toml(XDG)NS_HPC_CONFIGenv var or--configCLI flag
See config/config.toml for the full reference.
# ~/.config/ns-hpc/config.toml
[namespace]
bwrap_command = [
"bwrap",
"--unshare-all", "--share-net",
"--proc", "/proc", "--dev", "/dev", "--tmpfs", "/tmp",
"--ro-bind", "/usr", "/usr",
"--ro-bind", "/lib", "/lib",
"--ro-bind", "/lib64", "/lib64",
"--ro-bind", "/bin", "/bin",
"--ro-bind", "/sbin", "/sbin",
"--ro-bind", "/etc", "/etc",
]
[jobs]
max_timeout = 3600
[jobs.local]
use_cgroups = true
cgroups_command = [
"systemd-run", "--user", "--scope",
"-p", "CPUQuota=400%",
"-p", "MemoryMax=8G",
"--",
]
[jobs.slurm]
sbatch_command = [
"sbatch",
"--partition", "cpu",
"--cpus-per-task={cpus}",
"--mem={memory}M",
]
[jobs.slurm.limit]
cpus = { default = 1, max = 8 }
memory = { default = 4096, max = 32768 }
# WebDAV file access (default: disabled)
[dav]
enabled = true
[dav.extras.external-data]
path = "/public5/home/t6s001890/data"
ro = true
[proxied_mcps.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/"]
# include = ["read_*", "list_*"]
# exclude = ["*_dangerous"]CLI Reference
Command | Description |
| Diagnose system prerequisites |
| Run command in raw bwrap sandbox |
| Start MCP server (stdio, streamable-http, sse, UDS) |
| Remove stale instances |
| Create a new sandbox instance |
| List all instances |
| List archived instances |
| Show instance metadata |
| Update description |
| Interactive bash in sandbox |
| Run command as an async job |
| Check job status |
| List tracked jobs |
| Cancel a running job |
| Archive instance (disables new jobs) |
MCP Tools
Instance Management
Tool | Description |
| Create a new sandbox instance |
| List all active instances |
| List all archived instances |
| Update instance metadata (description) |
| Archive an instance, disabling new jobs |
Job Execution
Tool | Description |
| Submit a command as an async job (local or Slurm) |
| Poll a running job, optionally wait for completion |
| List all tracked jobs for an instance |
| Cancel a running job and return final output |
File Access
Tool | Description |
| Read a file from the sandbox workspace |
| Write a file to the sandbox workspace |
| List directory contents |
| Additional proxied filesystem tools (search, move, etc.) |
The
filesystem__*tools are proxied from the@modelcontextprotocol/server-filesystemMCP server running inside bwrap. They can be filtered withinclude/excludepatterns in config.
WebDAV File Transfer
When [dav].enabled = true (and the server runs in HTTP mode), the WebDAV
endpoint at /dav/ provides direct file access from Finder, Windows
Explorer, rclone, or curl.
/dav/instances/{id}/workspace/... (read-write)
/dav/instances/{id}/output/... (read-write)
/dav/{extra_name}/... (config-controlled, defaults to ro)# Mount in Finder: ⌘K → http://127.0.0.1:8000/dav/
# Or with curl:
curl http://127.0.0.1:8000/dav/instances/my-inst/workspace/file.txt
curl -T data.csv http://127.0.0.1:8000/dav/instances/my-inst/workspace/data.csv
curl -X DELETE http://127.0.0.1:8000/dav/instances/my-inst/workspace/old.txtWrites (PUT, DELETE, MKCOL) are audited to the instance
audit.log.Archived instances return 404.
Path traversal (symlinks,
..) is blocked.Read-only extra mounts reject writes.
Remote HPC Setup
1. Install on the HPC node
pip install git+https://github.com/li-yq/namespaced-hpc-mcp.git
ns-hpc doctor2. Configure for your cluster
# ~/.config/ns-hpc/config.toml
[namespace]
bwrap_command = [
"bwrap",
"--unshare-all", "--share-net",
"--uid", "1000", "--gid", "1000",
"--ro-bind", "/home/user/.local/share/ns-hpc/rootfs", "/",
"--ro-bind", "/home/user/.local/share/ns-hpc/agent-tools", "/opt/agent-tools",
"--proc", "/proc", "--dev", "/dev",
"--tmpfs", "/run", "--tmpfs", "/tmp",
]
workspace_mount = "/home/agent"
output_mount = "/mnt/output"
shared_output_mount = "/mnt/shared-output"
[jobs.slurm]
sbatch_command = ["sbatch", "--partition", "compute", "--cpus-per-task={cpus}", "--mem={memory}M"]
[jobs.slurm.limit]
cpus = { default = 1, max = 32 }
memory = { default = 4096, max = 131072 }3. Start the server
# stdio (for SSH-based MCP clients)
ns-hpc run
# Streamable HTTP (recommended for direct HTTP)
ns-hpc run --transport streamable-http --port 8000
# With WebDAV
ns-hpc run --transport streamable-http --port 8000 # set [dav].enabled=true4. MCP client config
{
"mcpServers": {
"ns-hpc": {
"command": "ssh",
"args": ["user@hpc-login", "ns-hpc", "run"]
}
}
}Or for HTTP:
{
"mcpServers": {
"ns-hpc": {
"url": "http://hpc-login:8000/mcp"
}
}
}Development
uv sync
uv run pytest # Full test suite
uv run python -m ns_hpc doctor # Diagnostics
uv run python -m ns_hpc run # Start serverTests by tier:
Tier | Command |
Pure unit (no bwrap) |
|
Unit + bwrap |
|
Full Slurm integration |
|
Security
All commands run via
bwrap --unshare-all(user, PID, mount, IPC, UTS, CGROUP namespaces)System paths are read-only (
--ro-bind)/tmpis a fresh tmpfsWorkspace is the only writable bind mount
Audit log written host-side, never exposed to sandbox
Path traversal blocked in filesystem and WebDAV tools
ns-hpc doctorvalidates prerequisites
Requirements
Linux with user namespaces enabled
bwrap (bubblewrap) 0.11+
Python 3.12+
(Optional) Slurm: sbatch, squeue, sacct
(Optional for WebDAV) network access for Finder/rclone/curl clients
License
MIT
Available Tools
10 toolsarchive_instanceA
Archive a sandbox instance, disabling new job submissions.
Inputs: input (required).
cancel_jobA
Cancel a running job and return its final status and output tail.
Inputs: input (required).
create_instanceA
Create a new sandbox instance with a persistent workspace directory.
Inputs: input (required).
host_execA
Run a pre-configured host command or list available commands.
With no argument, returns the list of configured host commands and
their descriptions. With a command key, runs the matching
host command outside any sandbox (directly on the host).
Inputs: input (required).
list_archived_instancesARead-only
List all archived sandbox instances.
Inputs: input (required).
list_instancesARead-only
List all active (non-archived) sandbox instances.
Inputs: input (required).
list_jobsARead-only
List tracked jobs for an instance, newest first, with pagination.
Inputs: input (required).
poll_jobC
Poll a running job. Optionally wait for completion.
Inputs: input (required).
submit_jobA
Submit a command as an async (non-blocking) job.
Inputs: input (required).
update_instanceC
Update or get an instance's metadata (currently only description).
Inputs: input (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct resource and action: instance lifecycle, job lifecycle, and host commands are clearly separated. The only potential pairing, list_instances vs list_archived_instances, is explicitly disambiguated by 'archived' in both name and description.
Most tools follow a snake_case verb_noun pattern (create_instance, list_jobs, cancel_job). host_exec deviates slightly by placing the noun before the verb, though it remains readable and consistent in style.
Ten tools is well-scoped for an HPC sandbox service with instance management, asynchronous job execution, and host command access. Each tool covers a meaningful operation without unnecessary duplication.
The tool set covers the essential instance lifecycle (create, list, archive, update) and job lifecycle (submit, poll, list, cancel). Minor gaps exist, such as no direct single-instance getter, no unarchive/destroy operation, and limited job output retrieval outside poll/cancel.
Maintenance
Related MCP Connectors
Secure Linux sandboxes for AI agents, as MCP tools.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Linux microVM sandboxes for AI agents: run commands, files, processes, pause and wake.
Execution platform for AI agents on Firecracker microVMs in the EU. Interactive Linux sandboxes with root, templates for Python, Node.js, Go, Rust and a headless browser, public HTTPS URLs. Background jobs that outlive the connection, batches of up to 1,000 jobs with dependencies, hard cost caps reserved up front, execution receipts with SHA-256, log digests that fit the context. IPv4, dual-stack or IPv6-only with its own public address, allowlists or no network. WASI runtime for small tasks. Idle sandboxes sleep and keep their files. Also REST API, Python SDK and LangChain.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides a secure, constrained filesystem workspace for LLM agents to manage files, notes, and code artifacts via stdio or remote HTTP. It features granular access controls, including extension whitelisting, storage quotas, and immutable paths for safe automated file operations.BSD 3-Clause
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage SLURM cluster jobs with safety guardrails, including file transfer, job submission, log reading, and remote command execution.1MIT
- AlicenseNot gradedqualityCmaintenanceProvides a restricted Docker-based sandbox for LLM agents, enabling file operations, command execution, and local Git within an isolated runtime.18 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to safely run bounded, sandboxed tasks on remote machines with persistent state and reviewable artifacts.Apache 2.0