> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://k3s.io/). 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

```bash theme={null}
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 Kubernetes instance with the
default machine shape (4 CPUs and 8 GiB of memory).

```bash theme={null}
nsc create
```

```text nocopy Output theme={null}
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.

```bash theme={null}
nsc create --machine_type 4x16 --cidfile /tmp/instance_id
```

```text nocopy Output theme={null}
Created instance "hrc4b9nvoj7ki"
  deadline: 2023-04-25T08:58:58Z
```

```bash theme={null}
cat /tmp/instance_id
```

```text nocopy Output theme={null}
hrc4b9nvoj7ki
```

Availability of [machine shapes](/docs/architecture/compute/machine-shapes) is subject to your plan and your remaining concurrency.

## Options

<h3 id="--machine_type-osarchcpuxmem">
  \--machine\_type \[os/arch:]\<cpu>x\<mem>
</h3>

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.

[Learn more about available Machine Shapes](/docs/architecture/compute/machine-shapes)

<h3 id="--cidfile-path">
  \--cidfile \<path>
</h3>

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.

<h3 id="--output_json_to-path">
  \--output\_json\_to \<path>
</h3>

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.

<h3 id="--output_registry_to-path">
  \--output\_registry\_to \<path>
</h3>

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

<h3 id="--wait_kube_system">
  \--wait\_kube\_system
</h3>

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

<h3 id="--wait_timeout">
  \--wait\_timeout
</h3>

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.

<h3 id="--selectors">
  \--selectors
</h3>

When starting a macOS instance select the desired base image based on properties specified as key-value pairs.
[Available Selectors](/docs/architecture/compute/macos#available-selectors).

<h3 id="--label-keyvalue">
  \--label key=value
</h3>

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.

<h3 id="--purpose-text">
  \--purpose \<text>
</h3>

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`](/docs/reference/cli/instance-report)'s `--purpose`/`--exclude-purpose`
flags, which makes it a convenient way to tag instances created by a
particular script or workflow.

<h3 id="--unique_tag-tag">
  \--unique\_tag \<tag>
</h3>

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.

<h3 id="--duration">
  \--duration
</h3>

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

<h3 id="--ephemeral">
  \--ephemeral
</h3>

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

<h3 id="--bare">
  \--bare
</h3>

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.

<h3 id="--volume">
  \--volume
</h3>

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](/docs/architecture/storage/cache-volumes) work.

<h3 id="--ingress">
  \--ingress
</h3>

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

<h3 id="--enable-feature">
  \--enable \<feature>
</h3>

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

* `kubernetes:<version>` — pins the version of [k3s](https://k3s.io/) installed
  on the instance. For example, `--enable=kubernetes:1.33` requests Kubernetes
  1.33. The list of supported versions evolves over time; if an unsupported
  version is requested the API rejects the request.
* `kubernetes-max-pods:<n>` — overrides the kubelet `--max-pods` value for the
  k3s node. Defaults to 110 (the upstream Kubernetes default). The maximum
  allowed value is 250. Requires Kubernetes to be enabled.

  ```bash theme={null}
  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.

<h3 id="--features-feature1feature2">
  \--features \<feature1,feature2>
</h3>

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

<h3 id="--experimental-json">
  \--experimental \<json>
</h3>

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.

<h3 id="--experimental_from-path">
  \--experimental\_from \<path>
</h3>

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.

<h3 id="--output-plainjson">
  \--output \<plain|json>
</h3>

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.

<h3 id="--ssh_key-key">
  \--ssh\_key \<key>
</h3>

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:

* `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**: Currently only public images are supported. Private registries (like `nscr.io`) won't work.
* `containerd_shims`: specify an additional set of containerd shims to configure
  containerd with.

Example:

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