# 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 `linux/amd64` Kubernetes instance
with the default machine shape of 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
```

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

```bash theme={null}
nsc create --machine_type macos/arm64:6x14 --selectors macos.version=26.x
```

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

## Options

### --machine\_type \[os/arch:]<cpu>x<mem>

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](/content/docs/architecture/compute/machine-shapes.md)

### --cidfile <path>

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 <path>

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 <path>

If specified, writes the instance's container registry address to this file.
This mirrors the `--output_registry_to` flag on [`nsc docker login`](/content/docs/reference/cli/docker-login/index.html), 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](/content/docs/architecture/compute/macos.md#available-selectors/index.html).

### --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 <text>

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

### --unique\_tag <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](/content/docs/architecture/storage/cache-volumes.md) work.

### --ingress

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

### --enable <feature>

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.

### --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>

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 <path>

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 <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:

* `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"]
		}
	]
}
```

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.