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

Quickly run containers in an ephemeral environment.

`run` starts containers in an ephemeral environment. When given an image, an
optional name, and set of ports to expose, a new ephemeral environment is
started with the specified containers. For example:

## Usage

```bash theme={null}
nsc run --image <reference> \
    [--on <id>] \
    [--name <name>] \
    [--publish, -p <ports>] \
    [--ingress <rules>] \
    [--volume <spec>] \
    [--env, -e <key=value>] \
    [--enable_docker] \
    [--user <user>] \
    [--machine_type [os/arch:]<cpu>x<mem>] \
    [--features <feature1,feature2>] \
    [--wait] \
    [--wait_timeout <duration>] \
    [--duration <duration>] \
    [--documented_purpose <text>] \
    [--development] \
    [--output, -o <plain|json>] \
    [--] [args]
```

### Example

The following example starts a new ephemeral environment, running nginx. The `nginx`
container image has nginx, an http reverse proxy, listening on port 80. We
export that port to a public endpoint, using `-p 80`.

Exported endpoints are Internet-facing but require authentication. Whoever has access to the
workspace where the ephemeral environment was created in, will also have access to the
endpoint.

```bash theme={null}
nsc run --image nginx -p 80
```

```text nocopy Output theme={null}
Created new ephemeral environment! (id: 85a32emcg99ii).
More at: https://cloud.namespace.so/01gr490qvbntkjn9jwypnd4g04/instance/85a32emcg99ii
Running "nginx-t082s"
  Exported 80/tcp as https://4bi2reg-85a32emcg99ii.fra1.namespaced.app
```

## Arguments

Arguments passed to the command will be passed as arguments to the running container.
If you want to specify flags as container arguments, specify them after `--`.
For example: `nsc run --image nginx -- nginx -t`

## Options

<h3 id="--image-reference">
  \--image \<reference>
</h3>

Specifying an image is required. OCI compatible image registries are supported,
but images must be public, unless you're using `nscr.io`, nsc's own Private
[Container Registry](/docs/architecture/storage/container-registry).

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

Rather than creating a new ephemeral environment, start the containers in an
existing environment (identified by its id).

Containers started in the same environment share networking, they can reach each
other on the local private network.

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

Container names show up in observability, like logs. If no name is provided, a
name is generated based on the container image name.

<h3 id="--publish--p-ports">
  \--publish, -p \<ports>
</h3>

Exports the specified ports (separated by commas) as public ingresses.

A nsc-based ingress does automatic TLS termination, but only HTTP backend
traffic is supported at the moment. In other words, the container exporting the
port must export an HTTP service.

Ports can also be exported after a container has started, using `nsc expose`.

<h3 id="--enable_docker">
  \--enable\_docker
</h3>

Enable the use of Docker from within the container.

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

Attach a volume to the instance. It follows the format
`{cache|persistent}:{tag}:{mountpoint}:{size}`.

For example, `--volume cache:mytag:/cache:50gb` will result in a [Cache Volume](/docs/architecture/storage/cache-volumes)
with the tag `mytag` mounted at `/cache`. There will be 50 GB of space available.

<h3 id="--output--o-format">
  \--output, -o \<format>
</h3>

Specifying `run` command output format. Supported options are `json` and
`plain`. By default `plain` output format is used.

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

Wait until the containers have started.

Note: This waits until the container runtime has started the necessary
processes, and does not check for readiness.

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

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

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

Specify additional rules per ingress. The following effects can be set per
route:

* `noauth`: Disables authentication on the route.

Rules are defined by mapping one or more rules to a port: `--ingress <port>=<rule>`
with the special case of `*` acting as a wildcard to any port.

Rules are defined by specifying method, path regex, using one of the following schemes:

* `<effect>`: Applies effect to any method or path.
* `<path_regex>:<effect>`: Applies effect to paths that match `path_regex` (the full path without the query is using for matching.).
* `<method>[,<method>,...]:<path_regex>:<effect>`: In addition to matching path, also matches against the HTTP method used.

<h3 id="--env--e-keyvalue">
  \--env, -e \<key=value>
</h3>

Pass additional environment variables to the container. Specify
`--env <key>=<value>`, or repeat the flag to set more than one variable.

<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="--machine_type-osarchcpuxmem">
  \--machine\_type \[os/arch:]\<cpu>x\<mem>
</h3>

Specify the machine shape for the underlying instance. Namespace supports
arbitrary machine shapes; see [Machine Shapes](/docs/architecture/compute/machine-shapes)
for the supported CPU/RAM combinations, and how to prepend `os/arch` to target
a different architecture or operating system.

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

Customize the user the container runs as, overriding the image's default user.

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

For how long to wait until the instance becomes ready before giving up.
Defaults to `1m`. This bounds how long `nsc run` blocks when `--wait` is set
and the container is slow to start.

<h3 id="--documented_purpose-text">
  \--documented\_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="--development">
  \--development
</h3>

Enables a handful of development facilities on the created environment,
including making the container image optional, so you can start an
environment without immediately running a container in it.