create.md

nsc create

Create a new instance.

create starts a fresh Namespace instance in an ephemeral and isolated environment. Namespace instances include a ready-to-use Kubernetes by default. The Kubernetes distribution is k3s. The environment is uniquely identified by an instance ID. You can specify the machine shape you need and a file to output the instance ID. For example:

Usage

nsc create [--machine_type [os/arch:]<cpu>x<mem>] \
    [--cidfile <path>] \
    [--output_json_to <path>] \
    [--output_registry_to <path>] \
    [--wait_kube_system] \
    [--wait_timeout <duration>] \
    [--selectors <name1=value1,name2=value2>] \
    [--label <key=value>] \
    [--purpose <text>] \
    [--unique_tag <tag>] \
    [--duration <duration>] \
    [--ephemeral] \
    [--bare] \
    [--volume <cache|persistent>:<tag>:<mountpoint>:<size>] \
    [--ingress wildcard] \
    [--enable <feature>] \
    [--features <feature1,feature2>] \
    [--experimental <json>] \
    [--experimental_from <path>] \
    [--output <plain|json>] \
    [--ssh_key <key>]

Example

The following example creates a new ephemeral linux/amd64 Kubernetes instance with the default machine shape of 4 CPUs and 8 GiB of memory.

nsc create

Created instance "h9am86n6gi25m"
  deadline: 2023-04-25T08:48:38Z

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

nsc create --machine_type 4x16 --cidfile /tmp/instance_id

Created instance "hrc4b9nvoj7ki"
  deadline: 2023-04-25T08:58:58Z

cat /tmp/instance_id

hrc4b9nvoj7ki

The following command creates a macOS Tahoe instance on Apple Silicon with 6 CPUs and 14 GiB of memory:

nsc create --machine_type macos/arm64:6x14 --selectors macos.version=26.x

Availability of machine shapes is subject to your plan and your remaining concurrency.

Options

--machine_type [os/arch:]x

Specifying the machine shape. Namespace supports arbitrary machine shapes that use any of [2, 4, 8, 16, 32] as CPU value, and [2, 4, 8, 16, 32, 64, 80, 96, 112, 128, 256, 384, 512] as RAM value, with the constraint that RAM must always be larger or equal to CPU.

Instances of different architectures and operating systems can be started by prepending os/arch to the machine shape. For example: nsc create --machine_type linux/arm64:2x8 starts a 2 vCPU 8GB RAM, ARM64 machine running Linux.

To start a macOS instance, use nsc create --machine_type macos/arm64:6x14. This creates a 6 vCPU, 14 GB RAM machine running macOS.

Learn more about available Machine Shapes

--cidfile

Write the instance ID to the specified file. If the file already exists, it will be overwritten. This is useful for automation that needs to capture the ID of a newly created instance without parsing the terminal output — see the example above.

--output_json_to

If specified, writes the instance's metadata as a JSON document to this file, in addition to the normal output printed to the terminal. This is useful when you need more than just the instance ID — for example, to pipe the full record into jq as part of a larger automation pipeline.

--output_registry_to

If specified, writes the instance's container registry address to this file. This mirrors the --output_registry_to flag on nsc docker login, and is useful when a script needs to immediately push or pull images against the instance's registry right after creating it.

--wait_kube_system

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

--wait_timeout

For how long to wait until the instance becomes ready before giving up. Defaults to 1m. This bounds how long nsc create blocks when --wait_kube_system is set and the kube-system resources are slow to become ready.

--selectors

When starting a macOS instance select the desired base image based on properties specified as key-value pairs. Available Selectors.

--label key=value

Annotate the new instance with the specified values. Multiple values can be specified. They are rendered by default in the web UI, and can be used for programmatic instance filtering.

--purpose

What documented purpose to attach to the created instance. Defaults to Manually created from CLI. This value is shown alongside the instance and can be filtered on with nsc instance report's --purpose/--exclude-purpose flags, which makes it a convenient way to tag instances created by a particular script or workflow.

--unique_tag

If specified, creates the instance with the given unique tag. Unique tags give automation a stable, human-chosen handle for an instance that doesn't depend on remembering the generated instance ID.

--duration

Specify how long an ephemeral environment should live for. E.g. --duration 10m.

--ephemeral

Create an ephemeral instance. Combine with --duration to control how long the instance lives before it is automatically destroyed.

--bare

If set to true, nsc creates an environment with the minimal set of services (e.g. no Kubernetes). Typically, it is used to create a remote instance to run containers.

--volume

Attach a volume to the instance. It follows the format {cache|persistent}:{tag}:{mountpoint}:{size}, e.g. cache:mytag:/cache:50gb. In case you select cache volume type, check how Cache Volumes work.

--ingress

Configures the ingress of this instance. Valid options: wildcard.

--enable

Enable an optional feature on the instance. Multiple --enable flags may be specified. Each value uses the form feature:value. Supported features:

  nsc create --enable=kubernetes:1.33 --enable=kubernetes-max-pods:250

The per-node pod CIDR is /24, so values close to 250 will use most of the per-node address space. Going significantly above the upstream default is generally only recommended for workloads with many small pods.

--features <feature1,feature2>

Attach a set of features to the instance. Multiple features can be specified as a comma-separated list, or by repeating the flag.

--experimental

JSON definition of experimental features to enable on the instance, provided inline as a string rather than read from a file. This is the inline counterpart to --experimental_from — see the Experimental features section below for the schema and the currently available features.

--experimental_from

Load the JSON definition of experimental features from the specified file, instead of passing it inline via --experimental. See the Experimental features section below for the schema and the currently available features.

--output <plain|json>

Output format for the command itself. One of plain (the default, human-readable) or json. Useful for scripting around nsc create when you don't need a persistent file — see also --output_json_to, which writes the JSON to a file rather than stdout.

--ssh_key

Injects the specified SSH public key into the created instance, so you can connect to it over SSH using the matching private key.

Experimental features

New features are often initially introduced 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:

Note: Currently only public images are supported. Private registries (like nscr.io) won't work.

Example:

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

This documentation is built and hosted on Mintlify, a developer documentation platform.