nsc create

Create a new Kubernetes cluster.

create starts a fresh Kubernetes cluster in an ephemeral and isolated environment. The Kubernetes distribution is k3s. The environment is uniquely identified by a cluster ID. You can specify the machine shape you need and a file to output the cluster ID. For example:


nsc create [--machine_type <cpu>x<mem>] [--output_to <path>] [--wait_kube_system]

Usage Example

The following example creates a new ephemeral Kubernetes cluster with the default machine shape (4 CPUs and 4 GiB of memory).

$ nsc create
  Created cluster "h9am86n6gi25m"
    deadline: 2023-04-25T08:48:38Z

The below command creates a Kubernetes cluster with 4 CPUs and 8 GiB of memory. Then, it writes the cluster ID into a file, which is especially useful for writing automation programs around nsc CLI.

$ nsc create --machine_type 4x8 --output_to /tmp/cluster_id
  Created cluster "hrc4b9nvoj7ki"
    deadline: 2023-04-25T08:58:58Z
$ cat /tmp/cluster_id
The availability of machine shapes may vary based on the remaining capacity in your Workspace.


--machine_type <cpu>x<mem>

Specifying the machine shape. The following are the supported machine shapes:

  • 2x2: 2 CPU 2 GB memory.
  • 2x4: 2 CPU 4 GB memory.
  • 4x4: 4 CPU 4 GB memory.
  • 4x8: 4 CPU 8 GB memory.
  • 4x16: 4 CPU 16 GB memory.
  • 16x32: 16 CPU 32 GB memory.

--output_to <path>

Write the cluster ID to file. If file already exists, it will get overwritten.


If specified nsc will wait until resources in kube-system Kubernetes namespace are ready.

Experimental features

We tend to introduce new possible features under experimental. Features here may graduate to be fully supported, or may end up being removed.

In order to use experimental features, pass --experimental_from pointing at a json file where the features you want to use are specified.

Currently, the following experimental features are available:

  • disks: specify an additional set of images to attach to the ephemeral environment. Each disk is created from a flattened container image, which you specify. And is mounted under /disk/<name>. NOTE: the current version of this feature requires that images used be public. That means that nscr.io is not supported.

  • containerd_shims: specify an additional set of containerd shims to configure containerd with.


	"disks": [
			"name": "gvisor",
			"image": "..."
	"containerd_shims": [
			"name": "runsc",
			"runtime_type": "io.containerd.runsc.v1",
			"add_to_path": ["/disk/gvisor"]