io.github.nogoo9/no-crd

Official

by nogoo9 · TypeScript

Dynamic pod spawner & proxy for ephemeral AI agent workspaces on Kubernetes without CRDs

Spawns ephemeral Kubernetes pods for AI agent workspaces without requiring custom resources.

@nogoo9/no-crd

Agent-Driven, On-Demand Pod Orchestration in Kubernetes — Without Custom Resource Definitions.

@nogoo9/no-crd is a lightweight, cross-runtime Model Context Protocol (MCP) server that empowers AI agents and APIs to dynamically spawn, route to, and manage ephemeral containerized sandboxes on standard Kubernetes (k8s/k3s) clusters — without requiring Custom Resource Definitions (CRDs), cluster-level operators, or elevated RBAC permissions.

It provides JupyterHub-like dynamic pod lifecycle management but is completely agnostic to actual workloads and supports multi-runtime execution under Bun, Deno, and Node.js.

📚 For detailed guides, API reference, and configuration options, visit the public Documentation Website or access the built-in documentation served directly at /docs/ (e.g. http://localhost:3000/docs/) when running the server.

🗺️ Choose Your Path

To get started with @nogoo9/no-crd, select the track that matches your goals:

Track A: AI Agent & MCP Users $\rightarrow$ MCP Client Setup Guide
- Best for: Connecting no-crd to Cursor, Claude Desktop, Cline, or Roo Code to let your agent manage pods.
Track B: Platform & Service Deployers $\rightarrow$ SSO & Routing Deployment Guide
- Best for: Deploying a multi-tenant sandbox service in your Kubernetes cluster with Keycloak OIDC, stateless cookies, and reverse proxy routing.
Track C: SDK & Code Contributors $\rightarrow$ SDK & Contributor Guide
- Best for: Programmatically controlling pods via the TypeScript SDK or contributing to the core runtime codebase.

🚀 Key Features

No CRDs Required: Runs directly against core Kubernetes resources (Pods, ConfigMaps, ServiceAccounts). Highly portable, secure, and compatible with restricted/managed environments (EKS, GKE, K3s).
Agent Sandbox Spawner: Specialized spawner tools that automate workspace provisioning with context validation, init containers, IAM roles, pre-stop hooks, and lifecycle sync.
ConfigMap-Based Templates: Store, version, and load reusable pod templates stored as standard Kubernetes ConfigMaps.
Local Filesystem Templates: Bake YAML/JSON pod templates into Docker images or mount them from host paths — with built-in defaults shipped in the package.
Isomorphic Multi-Runtime SDK: Imports seamlessly as a composable programmatic SDK or MCP server running under Node.js, Bun, or Deno.
Workspace Routing Proxy (Experimental): Built-in reverse proxy routing that dynamically pipes traffic to running container IPs with secure user token ownership verification, path-scoped session cookies (nocr_token and nocr_sess), and automatic HMAC-signed session management for short-lived token resilience.
Experimental JWT Authentication: Built-in OAuth token validation engine supporting HS256, RS256, ES256, JWKS endpoints, and OAuth 2.0 Token Introspection (RFC 7662).
Embedded Web UI App: Exposes an interactive web-based Pod Manager interface featuring a light/dark theme toggle, client-side PKCE OIDC login with proactive silent token refresh, and workspace file preview rendering (supporting HTML sandboxed iframes and custom Markdown rendering).

⚡ Quick Start

Run Standalone via NPX (No Installation)

bash

# Option 1: Start HTTP/SSE server on port 3000
npx @nogoo9/no-crd --transport http --port 3000

# Option 2: Run over standard input/output (stdio) for local IDE agents
npx @nogoo9/no-crd --transport stdio --mode cluster

Install Globally

bash

npm install -g @nogoo9/no-crd
nocrd9 --transport stdio --mode cluster

Run via Docker

bash

docker run -d -p 3000:3000 \
  -v "$HOME/.kube/config:/app/.kube/config:ro" \
  -e KUBECONFIG=/app/.kube/config \
  ghcr.io/nogoo9/no-crd:latest

⚙️ Configuration & Environment Variables

The server and command-line utility are configurable using CLI options or environment variables. Below is the quick reference table of all settings:

🔌 Server Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
`-t, --transport`	`TRANSPORT`	`http`	`http`, `stdio`, `both`	Server transport mode. `both` fires up both transports simultaneously.
`-p, --port`	`PORT`	`3000`	Number	HTTP server port for SSE transport.
`-H, --host`	`HOST`	`0.0.0.0`	String	Host interface to bind the HTTP/SSE server to.
`--base-url`	`BASE_URL`	`""`	Path string	Base URL path prefix for hosting behind a reverse proxy (e.g. `/gateway/no-crd`).
-	`STATELESS`	`false`	`true`, `false`	Enable stateless request handling (no session affinity).
`-l, --log-level`	`LOG_LEVEL`	`info`	`debug`, `info`, `warning`, `error`, `fatal`	Logging verbosity filter.
-	`LOG_FILE`	`nogoo9-mcp.log`	String	Output file path for file logging.
-	`RATE_LIMIT_MAX`	`100`	Number	Maximum requests allowed per window for rate limited routes.
-	`RATE_LIMIT_WINDOW`	`60000`	Number	Time window in milliseconds for rate limited routes.
`--proxy-timeout`	`PROXY_TIMEOUT`	`120000`	Number	Timeout in milliseconds for the routing proxy upstream requests.
`--proxy-keep-alive`	`PROXY_KEEP_ALIVE`	`true`	`true`, `false`	Enable TCP keep-alive for the routing proxy upstream requests.

🔒 TLS Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
`--tls-cert`	`TLS_CERT`	-	Path string	Path to TLS certificate file to enable HTTPS.
`--tls-key`	`TLS_KEY`	-	Path string	Path to TLS private key file to enable HTTPS.
`--tls-ca`	`TLS_CA`	-	Path string	Path to TLS CA certificate file for HTTPS client/verification.
-	`NODE_TLS_REJECT_UNAUTHORIZED`	`true`	`0 (false)`, `1 (true)`	Set to `0` to bypass TLS verification (for development/testing only).

🌐 CORS Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
`--cors-origin`	`CORS_ALLOWED_ORIGIN`, `CORS_ORIGIN`	`*`	String	CORS Allowed Origin header.
`--cors-methods`	`CORS_ALLOWED_METHODS`, `CORS_METHODS`	`GET, POST, OPTIONS`	String	CORS Allowed Methods header.
`--cors-headers`	`CORS_ALLOWED_HEADERS`, `CORS_HEADERS`	`Content-Type, Authorization, mcp-protocol-version, mcp-session-id`	String	CORS Allowed Headers header.
`--cors-allow-credentials`	`CORS_ALLOW_CREDENTIALS`, `CORS_CREDENTIALS`	`false`	`true`, `false`	Enable CORS Access-Control-Allow-Credentials header.
`--cors-expose-headers`	`CORS_EXPOSED_HEADERS`, `CORS_EXPOSED`	`mcp-session-id, x-refreshed-token`	String	Custom CORS Access-Control-Expose-Headers header.
`--cors-max-age`	`CORS_MAX_AGE`	-	Number	Custom CORS Access-Control-Max-Age header in seconds.

☸️ Kubernetes Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
`-m, --mode`	`MODE`	`cluster`	`cluster`, `namespaced`	Kubernetes access scope. `namespaced` locks operations to a single namespace.
`-n, --namespace`	`NAMESPACE`, `DEFAULT_NAMESPACE`	`nogoo9`	String	Default Kubernetes namespace for operations.
`--disable-permission-checks`	`DISABLE_PERMISSION_CHECKS`	`false`	`true`, `false`	Disable Kubernetes RBAC permission checks and assume all tools are enabled.
`--managed-only`	`MANAGED_ONLY`	`true`	`true`, `false`	When true, pod tools only operate on pods managed by this server (`nogoo9/managed-by` label). No one bypasses this, not even admins. See ADR-008.
`--default-workspace-port`	`DEFAULT_WORKSPACE_PORT`	-	Number	Default target port inside the workspace pods to proxy traffic to.
-	`REGISTRY_URL`	-	URL string	Target container registry URL to query for images (e.g. `http://localhost:5001`).
-	`TEMPLATES_DIR`	-	Path string	Path to local directory containing pod template files (YAML/JSON). See ADR-001.
-	`BUILTIN_TEMPLATES`	`true`	`true`, `false`	Set to `false` to disable built-in templates shipped with the package.

🔑 Authentication Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
`--auth-enabled`	`AUTH_ENABLED`	`false`	`true`, `false`	Enables JWT token authentication on MCP tools and route proxy.
-	`JWT_VERIFICATION_REQUIRED`	`true`	`true`, `false`	Enable/disable JWT signature verification (signature checks).
-	`JWT_SECRET`	-	String	Symmetric HMAC-SHA256 secret for token verification.
-	`JWT_PUBLIC_KEY`	-	String	PEM encoded RSA/ECDSA public key for asymmetric token verification.
-	`JWKS_URI`	-	URL string	Remote JWKS endpoint URL to dynamically retrieve verification keys.
-	`INTROSPECTION_ENDPOINT`, `JWT_INTROSPECTION_ENDPOINT`	-	URL string	Endpoint for token introspection/validation.
-	`OAUTH_CLIENT_ID`	-	String	OAuth client ID for auth configuration.
-	`OAUTH_CLIENT_SECRET`	-	String	OAuth client secret for auth configuration.
-	`JWT_AUDIENCE`	-	String	Expected token audience. Falls back to `OAUTH_CLIENT_ID` if set.
-	`AUTH_ISSUER`, `JWT_ISSUER`	`""`	URL string	Identifier URL for the Authorization Server advertised in metadata discovery.
-	`AUTH_SUB_JSONPATH`	`$.sub`	JSONPath	Payload path to extract unique user identity from JWT payload.
`--auth-scope-jsonpath`	`AUTH_SCOPE_JSONPATH`	`$.scope`	JSONPath	Payload path to extract scopes claim from JWT payload.
`--auth-roles-jsonpath`	`AUTH_ROLES_JSONPATH`, `AUTH_ADMIN_JSONPATH`	`$.realm_access.roles`	JSONPath	Payload path to extract user roles from JWT payload.
-	`AUTH_ADMIN_ROLE`	`admin`	String	Role name signifying administrator access.
`--auth-required-read-scope`	`AUTH_REQUIRED_READ_SCOPE`	`nogoo9:read`	String	OAuth scope required for read operations. If not set, read scope check is bypassed.
`--auth-required-write-scope`	`AUTH_REQUIRED_WRITE_SCOPE`	`nogoo9:write`	String	OAuth scope required for write/mutation operations. If not set, write scope check is bypassed.
`--auth-required-admin-scope`	`AUTH_REQUIRED_ADMIN_SCOPE`	`nogoo9:admin`	String	OAuth scope required for administrator operations. If not set, admin scope check is bypassed.
`--auth-required-read-role`	`AUTH_REQUIRED_READ_ROLE`	`viewer`	String	User role required for read operations. If not set, read role check is bypassed.
`--auth-required-write-role`	`AUTH_REQUIRED_WRITE_ROLE`	`user`	String	User role required for write/mutation operations. If not set, write role check is bypassed.
-	`PROXY_SESSION_TTL`	`1800`	Number	Session cookie expiration lifetime in seconds (sliding window duration).
-	`PROXY_REFRESH_COOKIE_TTL`	`604800`	Number	Default Max-Age for the encrypted refresh token cookie (nocr_refresh). Overridden by the IdP's refresh_expires_in when available.
-	`PROXY_TOKEN_COOKIE_TTL`	`86400`	Number	Default Max-Age for the access token cookie (nocr_token). Overridden by the JWT exp claim when available.
-	`PROXY_SESSION_SECRET`	`""`	String	HMAC secret key used to sign stateless session cookies. Falls back to `JWT_SECRET` if not configured.
-	`OAUTH_SCOPES`	`openid profile email offline_access`	Space-separated scope string	OAuth scopes to request during authorization. Include 'offline_access' for refresh tokens.
-	`OAUTH_AUTHORIZATION_URL`	-	URL string	Direct OAuth authorization URL.
-	`OAUTH_SERVER_DISCOVERY_URL`, `OAUTH_DISCOVERY_URL`	-	URL string	Discovery URL for the OAuth server used by the backend gateway. Falls back to OAUTH_DISCOVERY_URL.
-	`OAUTH_SERVER_TOKEN_URL`, `OAUTH_TOKEN_URL`	-	URL string	Direct OAuth token exchange endpoint for the backend server.
-	`OAUTH_END_SESSION_URL`	-	URL string	Direct OAuth logout endpoint.
`--auth-inject-workspace-jwt`	`AUTH_INJECT_WORKSPACE_JWT`	`true`	`true`, `false`	Determines if the custom 'x-workspace-jwt' header containing the raw token is injected into proxy requests.
-	`AUTH_DEFAULT_ROLE`	`viewer`	String	Fallback role if the token does not provide scopes/roles.

🖥️ UI & Themes Configuration

CLI Option	Environment Variable	Default	Allowed Values	Description
-	`UI_ENABLED`	`true`	`true`, `false`	Enables the embedded HTML Pod Manager UI resource.
-	`THEMES_DIR`	`themes`	Path string	Local directory path containing custom CSS UI themes.
-	`THEMES_CONFIGMAP`	-	String	Name of Kubernetes ConfigMap containing custom UI theme configurations.
-	`DOCS_DIR`	`/app/docs (Docker) or docs/.vitepress/dist (Local)`	Path string	Base directory from which static documentation files are served.
-	`OAUTH_DISCOVERY_URL`	`""`	URL string	Discovery URL for the OAuth authorization server used by the UI client.
-	`OAUTH_CLIENT_ID`	`""`	String	OAuth client ID for UI authorization.
-	`OAUTH_LOGIN_METHOD`	`redirect`	`redirect`, `popup`	Login interaction mode for UI OAuth client.
-	`UI_TITLE`	`nogoo9 Pod Manager`	String	Custom title shown in the dashboard header.
-	`UI_SUBTITLE`	`On-demand Kubernetes pod orchestration and agent-sandbox management without CRDs.`	String	Custom subtitle shown below the dashboard title.

☸️ Kubernetes Setup & RBAC Permissions

For the @nogoo9/no-crd MCP server to interact with Kubernetes, it must run with appropriate RBAC permissions. Depending on your configuration, you can deploy it with Cluster-Wide (ClusterRole) access or Namespace-Scoped (Role) access.

Tool-to-Permission Mapping

Below is the mapping showing which Kubernetes API resources and verbs each MCP tool requires. The server dynamically checks these permissions at startup (via SelfSubjectAccessReview) and only registers tools that the active identity is authorized to use.

Resource: `configmaps`

Required Verb	Associated MCP Tools	Description / Purpose
`create`	`create_template`	Save a new pod template definition as a ConfigMap.
`delete`	`delete_template`	Delete a stored pod template ConfigMap.
`get`	`create_pod_from_template`	Read template pod specifications stored in ConfigMaps.
`update`	`update_template`	Modify metadata, annotations, or specifications of an existing template.

Resource: `events`

Required Verb	Associated MCP Tools	Description / Purpose
`list`	`get_workspace_events`

Resource: `namespaces`

Required Verb	Associated MCP Tools	Description / Purpose
`list`	`list_namespaces`	Discover namespaces in the cluster (only required in cluster access mode).

Resource: `pods`

Required Verb	Associated MCP Tools	Description / Purpose
`create`	`create_pod`, `create_pod_from_template`, `spawn_workspace`, `upgrade_all_workspaces`, `upgrade_workspace`	Provision and deploy new pods or workspace sandboxes.
`delete`	`delete_pod`, `stop_workspace`, `upgrade_all_workspaces`, `upgrade_workspace`	Terminate and clean up pods or workspace sandboxes.
`get`	`get_pod`, `get_workspace`, `upgrade_workspace`	Retrieve detailed JSON spec for a specific pod.
`list`	`list_pods`, `list_workspaces`, `upgrade_all_workspaces`	Retrieve lists of pods or agent workspace pods.
`patch`	`patch_pod`	Strategic merge patch labels, annotations, or resource requests/limits.

Resource: `pods/log`

Required Verb	Associated MCP Tools	Description / Purpose
`get`	`get_pod_logs`	Retrieve standard output/error logs from pod containers.

1. Cluster-Wide Mode (`MODE=cluster`)

Use this mode if you want the MCP server to manage sandboxes across any namespace in the cluster.

Create a ClusterRole and ClusterRoleBinding:

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: nogoo-mcp
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch", "create", "delete", "patch", "update"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: nogoo-mcp
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: nogoo-mcp
subjects:
  - kind: ServiceAccount
    name: nogoo-mcp
    namespace: nogoo9 # Change to the namespace where your MCP server runs

2. Namespace-Scoped Mode (`MODE=namespaced`)

Use this mode if the MCP server should be restricted to a single namespace (e.g. nogoo9). In this mode, no cluster-level or administrative permissions are needed.

Create a Role and RoleBinding in the target namespace:

yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: nogoo-mcp
  namespace: nogoo9
rules:
  - apiGroups: [""]
    resources: ["pods"]
    verbs: ["get", "list", "watch", "create", "delete", "patch", "update"]
  - apiGroups: [""]
    resources: ["pods/log"]
    verbs: ["get"]
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "create", "update", "patch", "delete"]
  - apiGroups: [""]
    resources: ["serviceaccounts"]
    verbs: ["get", "list", "create", "update", "patch", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: nogoo-mcp
  namespace: nogoo9
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: Role
  name: nogoo-mcp
subjects:
  - kind: ServiceAccount
    name: nogoo-mcp
    namespace: nogoo9

(Note: In namespace-scoped mode, the list_namespaces tool will only return the target namespace, and namespace parameter inputs to all tools will default to the target namespace.)

📑 Workspace Templates & Spawner Annotations

Templates in @nogoo9/no-crd can be loaded from three sources (highest to lowest priority):

Kubernetes ConfigMaps — labeled with nogoo9/pod-template: "true" (original mechanism)
Custom local directory — set via TEMPLATES_DIR env var (YAML or JSON files)
Built-in templates — shipped with the npm package (disable with BUILTIN_TEMPLATES=false)

See ADR-001 for format details.

1. How to Define a Template

To register a template with the spawner, create a ConfigMap meeting the following requirements:

Discovery Label: Must be labeled with nogoo9/pod-template: "true".
Spec Key: The data block must contain a key named spec whose value is a JSON string conforming to the PodSpecSchema (e.g. containers, volumes, restartPolicy).
Behavior Customization: Set annotations on the ConfigMap metadata to configure advanced spawner integrations (like IAM role binding, init containers, and pre-stop lifecycle hooks).

Example Template Definition:

yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: node-workspace-template
  namespace: nogoo9
  labels:
    nogoo9/pod-template: "true"
  annotations:
    nogoo9/description: "A standard Node.js development sandbox with S3 storage sync"
    nogoo9/tag: "node-20"
    nogoo9/required-context: "PROJECT_NAME,REPO_URL"
    nogoo9/iam-role-arn: "arn:aws:iam::123456789012:role/workspace-s3-access"
    nogoo9/init-image: "alpine/git"
    nogoo9/init-command: "git clone $REPO_URL /workspace/$PROJECT_NAME"
    nogoo9/pre-stop-command: "aws s3 sync /workspace s3://my-workspace-backups/$PROJECT_NAME"
    nogoo9/default-grace-period: "120"
data:
  spec: |
    {
      "containers": [
        {
          "name": "workspace",
          "image": "node:20-alpine",
          "command": ["sleep", "infinity"],
          "volumeMounts": [
            {
              "name": "workspace-storage",
              "mountPath": "/workspace"
            }
          ]
        }
      ],
      "volumes": [
        {
          "name": "workspace-storage",
          "emptyDir": {}
        }
      ]
    }

2. Supported Spawner Annotations

The spawner inspects ConfigMap metadata annotations (and custom inline annotations passed during spawn_workspace) to customize the workspace lifecycle:

Annotation / Label Key	Type	Description
`nogoo9/workspace-auth-mode`	Annotation (Comma-separated)	Configures authorization modes for the workspace proxy. Comma-separated list of: `token-api` (exposes token retrieval endpoints at `_auth/token` & `_auth/authorize` for SPAs), `inject-headers` (rewrites headers to forward user identity like `x-user-sub` and JWTs to container; enabled by default if `AUTH_ENABLED=true`), `no-auth` (bypasses all auth/owner checks for public workspaces). (Available from v0.6.0, no-auth from v0.8.0)
`nogoo9/auth-require-token`	Annotation ("true"	"false")
`nogoo9/template-version`	Annotation (String)	Specifies the version of the pod template. Used to track if workspaces are outdated. (Available from v0.8.0)
`nogoo9/workspace-name`	Annotation (String)	Stores the user-defined display name of the workspace. (Available from v0.4.0)
`nogoo9/template-ref`	Annotation (String)	The reference to the pod template used to spawn the workspace (e.g. `default/workspace-terminal`). (Available from v0.4.0)
`nogoo9/managed-by`	Label (String)	Used to label workspace pods created by this MCP server to restrict operational scope. (Available from v0.5.0)
`nogoo9/pod-template`	Label (`"true"`)	Identifies a Kubernetes `ConfigMap` as a reusable pod template.
`nogoo9/type`	Label (`"workspace"`)	Applied automatically by the spawner to identify running agent workspace pods.
`nogoo9/workspace-id`	Label	Identifies the unique agent session / workspace ID associated with the running pod.
`nogoo9/user-sub`	Label / Annotation	Represents the authenticated user subject (owner) of the workspace pod, used for access control validation and ServiceAccount labeling.
`nogoo9/description`	Annotation (String)	A friendly, human-readable summary of the template's purpose and contents.
`nogoo9/tag`	Annotation (String)	A version or tag associated with the template environment (e.g. `node-20`).
`nogoo9/required-context`	Annotation (Comma-separated)	Validates that target environment variables are provided in the tool call's `context` parameter (e.g. `GITHUB_TOKEN,DATABASE_URL`).
`nogoo9/iam-role-arn`	Annotation (AWS Role ARN)	Instructs the spawner to provision a dedicated Kubernetes `ServiceAccount` annotated for EKS IAM Role mapping (IRSA).
`nogoo9/init-image`	Annotation (Image string)	The container image to run in the dynamic `spawner-init` init-container.
`nogoo9/init-command`	Annotation (Shell command)	The shell command to run in the init-container. It automatically shares the main container's volume mounts.
`nogoo9/init-share-volumes`	Annotation ("true"	"false")
`nogoo9/pre-stop-command`	Annotation (Shell command)	A shell command executed in a Kubernetes `preStop` lifecycle exec hook when the workspace is terminated (e.g. to save/push state).
`nogoo9/pre-stop-sidecar-image`	Annotation (Image string)	If specified alongside `pre-stop-command`, runs the pre-stop command inside a dedicated sidecar container instead of the main container.
`nogoo9/default-grace-period`	Annotation (Number in seconds)	Overrides the Pod's `terminationGracePeriodSeconds` (defaults to `60` if a pre-stop command is defined) to give cleanup commands time to finish.
`nogoo9/workspace-port`	Annotation (Number)	The port inside the container to proxy traffic to. Defaults to `DEFAULT_WORKSPACE_PORT` or `3000`.
`nogoo9/workspace-path`	Annotation (String)	The default URL subpath mapping for the workspace web interface (defaults to `/`).
`nogoo9/workspace-type`	Annotation (String)	The format specification of the main entry point (e.g. `iframe`, `novnc`).
`nogoo9/preview-path`	Annotation (String)	The default folder or file subpath to render in the UI files preview tab.
`nogoo9/preview-type`	Annotation (String)	Fallback preview rendering mode for the preview tab (e.g. `markdown`, `html`).
`nogoo9/api.<api-name>.port`	Annotation (Number)	Defines an additional HTTP service port exposed by the workspace.
`nogoo9/api.<api-name>.visibility`	Annotation (String)	Specifies access visibility for the custom API endpoint. Supported values: `private` (accessible only by the workspace owner), `internal` (accessible by any logged-in user), `admin` (accessible by the owner or users with the admin scope and role), `scope:<scope_name>` (accessible by users possessing the specified OIDC scope), `role:<role_name>` (accessible by users possessing the specified user role), or a comma-separated list of allowed user subjects.
`nogoo9/api.<api-name>.path`	Annotation (String)	Defines the subpath routing prefix for this specific API (e.g. `/terminal`).
`nogoo9/api.<api-name>.desc`	Annotation (String)	A short description of this additional API, shown in the UI interface.
`nogoo9/api.<api-name>.method`	Annotation (String)	Comma-separated list of supported HTTP methods (e.g. `GET,POST`, `*`, defaults to any method).
`nogoo9/api.<api-name>.refresh`	Annotation (Duration)	Sets the refresh frequency for custom stats/activity or other mini API views in the dashboard cards (e.g. `10s`, `1m`, or `init` to query only once on startup).
`nogoo9/api.stats.refresh`	Annotation (Duration)	Explicitly configures the reload frequency for the reserved `stats` API metrics on the workspace dashboard card (e.g., `10s`, `30s`, `init`).
`nogoo9/api.last_activity.refresh`	Annotation (Duration)	Explicitly configures the reload frequency for the reserved `last_activity` epoch timestamp API on the workspace dashboard card (e.g., `30s`, `1m`, `init`).

📦 Programmatic SDK & API Proxy Services

@nogoo9/no-crd provides a complete programmatic SDK and dynamic cluster routing proxy to allow developers to build custom pod orchestrators and route workspace traffic natively.

1. Composable Programmatic SDK

You can import @nogoo9/no-crd in your Bun, Deno, or Node.js codebase to control pod sandboxes and templates programmatically, bypassing the MCP HTTP server.

typescript

import { KubeConfig } from "@kubernetes/client-node";
import { 
  initK8sContext, 
  spawnWorkspace, 
  stopWorkspace, 
  listWorkspaces 
} from "@nogoo9/no-crd";

// 1. Initialize Kubernetes API Context (optionally pass custom configuration)
const kc = new KubeConfig();
kc.loadFromDefault();
const ctx = initK8sContext(kc);

// 2. Spawn a workspace sandbox from a template
const spawnResult = await spawnWorkspace(ctx, {
  id: "agent-session-42",
  templateRef: "nogoo9/default-agent-workspace",
  context: {
    "S3_BUCKET": "my-bucket",
    "S3_FOLDER": "session-42"
  }
});
console.log(`Spawned pod: ${spawnResult.podName}`);

// 3. List active workspaces running in the namespace
const list = await listWorkspaces(ctx, {
  namespace: "nogoo9"
});
console.log(`Active workspaces count: ${list.workspaces.length}`);

// 4. Terminate the workspace sandbox
await stopWorkspace(ctx, {
  id: "agent-session-42"
});

2. Workspace Routing Proxy (Experimental)

WARNING

The workspace routing proxy and JWT authentication engine are experimental and likely to change in the next version.

The server includes a built-in reverse proxy routing service. HTTP requests targeting: http://<mcp-server-host>/route/<workspace-id>/<subpath> are dynamically proxied directly to the running workspace pod's IP address inside the cluster.

If AUTH_ENABLED is true:

Token Bootstrapping & Path-Scoped Cookies: Since standard browser navigations (links, iframes) cannot transmit custom HTTP headers, the client passes the active JWT via a ?token= query parameter on initial redirect. The proxy validates it and issues a secure, path-scoped cookie (nocr_token), allowing subsequent resource requests (JS, CSS, images, WebSockets) to authenticate seamlessly without URL parameters.
Direct Access Redirect (SSO): Accessing a workspace URL directly without active credentials redirects you to the main dashboard's login screen. Once logged in, the dashboard automatically routes you back to the target workspace URL with a fresh bootstrap token.
Resource Ownership Verification: The workspace pod's nogoo9/user-sub label must match the JWT's subject claim, preventing unauthorized access to other users' workspaces.
Proxy target port: Inside the workspace pod defaults to 3000 or can be overridden via pod annotation nogoo9/workspace-port or the DEFAULT_WORKSPACE_PORT environment variable.
Multi-Port / Custom API Routing: You can expose and route additional APIs inside the pod (e.g., a web terminal or secondary service) by defining custom annotations in the template (e.g., nogoo9/api.terminal.port: "7681", nogoo9/api.terminal.path: "/terminal"). The proxy will dynamically handle subpath routing and method checks.
A stateless signed session cookie (nocr_sess) is minted on first successful JWT validation, enabling workspace traffic to survive short-lived token expiry. (Available from v0.4.0) See ADR-002 and ADR-003 for design details.

For a detailed breakdown of the redirection lifecycle, Keycloak configuration, and JWT claims, see the SSO & OIDC Integration Guide.

3. OAuth Resource Discovery (RFC 9728)

Exposes the standardized metadata endpoint GET /.well-known/oauth-protected-resource returning:

Supported authorization servers.
Token format specifications.
Required scopes.

This allows client interfaces (and MCP clients) to automatically discover security requirements and handle dynamic OAuth authentication flows.

4. Embedded Web UI & Dashboard Themes

When the server runs in HTTP/SSE transport mode, the visual React Pod Manager UI Dashboard is served directly at root / (e.g. http://localhost:3000/).

Dashboard Themes: The UI includes a system/light/dark toggle and supports custom visual themes.
Three-Source Theme Merge Engine: CSS stylesheets are dynamically scanned and merged from:
1. Kubernetes ConfigMap (THEMES_CONFIGMAP environment variable).
2. Custom Local Directory (THEMES_DIR environment variable, defaults to themes/).
3. Built-In Catalog (pre-baked styles: Dracula, Nord, Stripe, Slack, Vercel, Apple, Superhuman, Notion, and Antigravity).

Duplicate theme IDs are resolved according to priority: ConfigMap > Local Directory > Built-In Catalog. For detailed customization guidelines and CSS templates, see the Dashboard Themes & Branding Guide.

🔌 API Reference (MCP Tools & Resources)

Pod Tools

list_pods: Retrieve a summary of pods in the namespace. Filters by labelSelector, fieldSelector, and limit.
get_pod: Fetch full Kubernetes API JSON payload for a target pod name.
create_pod: Create a custom pod with direct container/volume specifications.
patch_pod: Apply a Strategic Merge Patch to modify labels, annotations, or container resource limits dynamically.
delete_pod: Terminate a pod with optional gracePeriodSeconds.
get_pod_logs: Fetch logs for a container with options like tailLines, sinceSeconds, timestamps, limitBytes, and previous.
list_namespaces: List all namespaces accessible with current credentials.
list_registry_images: List catalog images from the configured REGISTRY_URL.

Pod Template Tools

Manage preconfigured pod specifications stored as standard Kubernetes ConfigMaps (labeled nogoo9/pod-template=true).

list_templates: Show available templates.
get_template: Get the raw pod template spec.
create_template: Store a new pod template spec.
update_template: Update labels, annotations, or specs on an existing template.
delete_template: Delete a template.
create_pod_from_template: Spawn a pod using a template, applying container overrides (environment variables, commands, resources) and top-level overrides.

Agent Workspace (Spawner) Tools

Specially designed for AI agents to safely spawn and clean up their own workspace sandboxes.

list_workspaces: List active agent workspaces (with JWT/owner mapping support).
spawn_workspace: Spawn a workspace sandbox pod. Features:
- Context Validation (nogoo9/required-context): Requires the caller to supply critical env variables (e.g. API keys) before spawning.
- Init Containers (nogoo9/init-image / nogoo9/init-command): Initialize workspace directories/files before main containers start.
- Pre-Stop Hooks (nogoo9/pre-stop-command): Run custom cleanup commands (e.g., commit/sync code to git or S3) upon termination.
- IAM Role Mapping (nogoo9/iam-role-arn): Dynamically provisions AWS EKS IAM Role service accounts.
stop_workspace: Clean up and terminate the workspace pod.

Utilities

current_namespace: Returns active namespace and access mode.

MCP Resources

pod-template://{namespace}/{name}: Exposes stored pod templates directly as read-only MCP resources.
ui://nogoo9/app: Exposes the embedded React/web UI app (if UI_ENABLED=true and built). When the server runs in HTTP/SSE transport mode, the UI is also served directly at / or /ui (e.g. http://localhost:3000/) and automatically falls back to standard HTTP JSON-RPC calls when loaded outside a postMessage-compatible MCP host (such as in a standard browser tab or the MCP Inspector).

🏗️ Architecture

code

  ┌───────────────────────┐
  │   AI Agent / Client   │
  └───────────┬───────────┘
              │ (Stdio or SSE Transport)
              ▼
  ┌───────────────────────┐
  │      MCP Server       │ <── (Queries ConfigMaps for specs)
  └───────────┬───────────┘
              │ (Kubernetes API - CoreV1)
              ▼
  ┌──────────────────────────────────────────┐
  │            Kubernetes Cluster            │
  │  ┌────────────────────────────────────┐  │
  │  │         Target Namespace           │  │
  │  │  ┌──────────┐ ┌──────────┐ ┌────┐  │  │
  │  │  │ Agent    │ │ Custom   │ │    │  │  │
  │  │  │ Sandbox  │ │ Workload │ │... │  │  │
  │  │  │ Pod      │ │ Pod      │ │    │  │  │
  │  │  └──────────┘ └──────────┘ └────┘  │  │
  │  └────────────────────────────────────┘  │
  └──────────────────────────────────────────┘

The server interacts directly with the Kubernetes API using @kubernetes/client-node. By using standard Pod and ConfigMap resources, the setup is highly scalable, requires no cluster operator installs, and easily adheres to strict enterprise namespace-level security policies.

🛠️ Development

We use Moon for toolchain management and task running, and Biome for formatting and linting.

Prerequisites

Bun 1.3.11+
Node.js 22.14.0+
Moon 2.1.3+
k3d (for local Kubernetes cluster)

Setup Environment

bash

# Install dependencies
bun install

# Auto-fix code formatting and linting via Biome
bun run format

# Run TypeScript compilation checks
bun run typecheck

Running Tests

bash

# Run unit tests
moon run mcp:test

# Run full spawner workspace lifecycle tests (requires local k3d)
bun run test:lifecycle

Local Cluster Testing (k3d)

Bootstrap a local k3d Kubernetes cluster complete with a local registry, built-in mock S3, and Traefik:

bash

# Spin up development cluster
moon run k3d:bootstrap

# Rebuild, push, and deploy MCP server to the cluster
moon run mcp:deploy

# Tear down the cluster
moon run k3d:teardown

📄 License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Install

Configuration

Environment variables

KUBECONFIG

Path to the Kubernetes API credentials configuration file

BASE_URL

Hosting URL subpath prefix for gateways and reverse proxies

STATELESS

Disable in-memory session tracking for stateless execution

TLS_CERT

Local file path containing TLS public certificate (HTTPS)

TLS_KEYsecret

Local file path containing TLS private key (HTTPS)

TLS_CA

Local file path containing trusted client Certificate Authority

NODE_TLS_REJECT_UNAUTHORIZED

Set to '0' to allow connection to unverified TLS endpoints

REGISTRY_URL

Default container registry for workspace image resolution

TEMPLATES_DIR

Local filesystem directory containing custom YAML/JSON templates

BUILTIN_TEMPLATES

Enable loading of standard pre-configured templates (default: true)

AUTH_ENABLED

Enforce JWT verification and user tenant isolation (default: false)

JWT_VERIFICATION_REQUIRED

Set to 'false' to skip OIDC cryptographic signature checks

JWT_SECRETsecret

HMAC-SHA symmetric secret key to sign/verify JWT tokens

JWT_PUBLIC_KEYsecret

PEM public key to verify asymmetric OIDC signatures

JWKS_URI

Discovery URI to fetch keys from OIDC provider dynamically

INTROSPECTION_ENDPOINT

RFC 7662 compliant token introspection validation endpoint

OAUTH_CLIENT_ID

Client identifier for OAuth2 authentication flows

OAUTH_CLIENT_SECRETsecret

Client secret credentials used for token introspection

JWT_AUDIENCE

Target audience check value for incoming OIDC tokens

AUTH_ISSUER

Expected token issuer authority check value (e.g. Keycloak)

AUTH_SUB_JSONPATH

JSONPath pattern to extract user identity subject from token

AUTH_ADMIN_ROLE

Bypass role name that grants admin access (default: nogoo9-admin)

PROXY_SESSION_TTL

Active lifetime in seconds for signed proxy session cookies

PROXY_SESSION_SECRETsecret

Secret key for session cookie signing

UI_ENABLED

Serve the built-in HTML dashboard (default: true)

THEMES_DIR

Filesystem directory to scan for custom CSS themes

THEMES_CONFIGMAP

ConfigMap name storing dynamic CSS theme overrides

DOCS_DIR

Directory containing static documentation web files to serve

OAUTH_DISCOVERY_URL

Standard OIDC .well-known configuration discovery endpoint

OAUTH_LOGIN_METHOD

UI SSO flow login method: 'redirect' or silent 'iframe'

UI_TITLE

Custom dashboard header title for white-label branding

UI_SUBTITLE

Custom dashboard subtitle text below the header title

Arguments

--transportdefault stdio

stdio|http|both

--modedefault cluster

cluster|namespaced

--namespacedefault nogoo9

nogoo9

--portdefault 3000

3000

--hostdefault 0.0.0.0

0.0.0.0

--log-leveldefault info

debug|info|warning|error|fatal

--disable-permission-checks

--cors-origindefault *

--cors-methodsdefault GET, POST, OPTIONS

GET, POST, OPTIONS

--cors-headersdefault Content-Type, Authorization

Content-Type, Authorization

--cors-allow-credentials

--auth-required-read-scope

mcp:read

--auth-required-write-scope

mcp:write

--auth-scope-jsonpathdefault $.scope

$.scope

--auth-required-read-role

reader

--auth-required-write-role

writer

--auth-roles-jsonpathdefault $.realm_access.roles

$.realm_access.roles

claude_desktop_config.json

{
  "mcpServers": {
    "no-crd": {
      "command": "npx",
      "args": [
        "-y",
        "@nogoo9/no-crd@0.11.1"
      ],
      "env": {
        "KUBECONFIG": "<YOUR_KUBECONFIG>",
        "BASE_URL": "<YOUR_BASE_URL>",
        "STATELESS": "<YOUR_STATELESS>",
        "TLS_CERT": "<YOUR_TLS_CERT>",
        "TLS_KEY": "<YOUR_TLS_KEY>",
        "TLS_CA": "<YOUR_TLS_CA>",
        "NODE_TLS_REJECT_UNAUTHORIZED": "<YOUR_NODE_TLS_REJECT_UNAUTHORIZED>",
        "REGISTRY_URL": "<YOUR_REGISTRY_URL>",
        "TEMPLATES_DIR": "<YOUR_TEMPLATES_DIR>",
        "BUILTIN_TEMPLATES": "<YOUR_BUILTIN_TEMPLATES>",
        "AUTH_ENABLED": "<YOUR_AUTH_ENABLED>",
        "JWT_VERIFICATION_REQUIRED": "<YOUR_JWT_VERIFICATION_REQUIRED>",
        "JWT_SECRET": "<YOUR_JWT_SECRET>",
        "JWT_PUBLIC_KEY": "<YOUR_JWT_PUBLIC_KEY>",
        "JWKS_URI": "<YOUR_JWKS_URI>",
        "INTROSPECTION_ENDPOINT": "<YOUR_INTROSPECTION_ENDPOINT>",
        "OAUTH_CLIENT_ID": "<YOUR_OAUTH_CLIENT_ID>",
        "OAUTH_CLIENT_SECRET": "<YOUR_OAUTH_CLIENT_SECRET>",
        "JWT_AUDIENCE": "<YOUR_JWT_AUDIENCE>",
        "AUTH_ISSUER": "<YOUR_AUTH_ISSUER>",
        "AUTH_SUB_JSONPATH": "<YOUR_AUTH_SUB_JSONPATH>",
        "AUTH_ADMIN_ROLE": "<YOUR_AUTH_ADMIN_ROLE>",
        "PROXY_SESSION_TTL": "<YOUR_PROXY_SESSION_TTL>",
        "PROXY_SESSION_SECRET": "<YOUR_PROXY_SESSION_SECRET>",
        "UI_ENABLED": "<YOUR_UI_ENABLED>",
        "THEMES_DIR": "<YOUR_THEMES_DIR>",
        "THEMES_CONFIGMAP": "<YOUR_THEMES_CONFIGMAP>",
        "DOCS_DIR": "<YOUR_DOCS_DIR>",
        "OAUTH_DISCOVERY_URL": "<YOUR_OAUTH_DISCOVERY_URL>",
        "OAUTH_LOGIN_METHOD": "<YOUR_OAUTH_LOGIN_METHOD>",
        "UI_TITLE": "<YOUR_UI_TITLE>",
        "UI_SUBTITLE": "<YOUR_UI_SUBTITLE>"
      }
    }
  }
}

@nogoo9/no-crd

🗺️ Choose Your Path

🚀 Key Features

⚡ Quick Start

Run Standalone via NPX (No Installation)

Install Globally

Run via Docker

⚙️ Configuration & Environment Variables

🔌 Server Configuration

🔒 TLS Configuration

🌐 CORS Configuration

☸️ Kubernetes Configuration

🔑 Authentication Configuration

🖥️ UI & Themes Configuration

☸️ Kubernetes Setup & RBAC Permissions

Tool-to-Permission Mapping

Resource: configmaps

Resource: events

Resource: namespaces

Resource: pods

Resource: pods/log

1. Cluster-Wide Mode (MODE=cluster)

2. Namespace-Scoped Mode (MODE=namespaced)

📑 Workspace Templates & Spawner Annotations

1. How to Define a Template

Example Template Definition:

2. Supported Spawner Annotations

📦 Programmatic SDK & API Proxy Services

1. Composable Programmatic SDK

2. Workspace Routing Proxy (Experimental)

3. OAuth Resource Discovery (RFC 9728)

4. Embedded Web UI & Dashboard Themes

🔌 API Reference (MCP Tools & Resources)

Pod Tools

Pod Template Tools

Agent Workspace (Spawner) Tools

Utilities

MCP Resources

🏗️ Architecture

🛠️ Development

Prerequisites

Setup Environment

Running Tests

Local Cluster Testing (k3d)

📄 License

Install

Configuration

Resource: `configmaps`

Resource: `events`

Resource: `namespaces`

Resource: `pods`

Resource: `pods/log`

1. Cluster-Wide Mode (`MODE=cluster`)

2. Namespace-Scoped Mode (`MODE=namespaced`)