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

# Instance Configuration

> Configure the shape, deadline, exported ports, volumes, and workload of a Namespace instance.

An instance is declared in a single `CreateInstance` call, so everything about the machine and the workload it runs is set at creation time.
This page covers the fields of `CreateInstanceRequest` that select the machine, bound its lifetime, expose it on the network, give it storage, and choose the workload model.

The fields are the same in every language. Each example below shows the fragment to add to a `CreateInstance` request in Go and TypeScript, plus the JSON body a plain HTTP client sends.
See the [quickstart](/docs/platform/instances/quickstart) for a complete create call.

## Machine shape

`shape` selects the machine. `machineArch` accepts `amd64` and `arm64`, and `os` accepts `linux` and `macos`.
`selectors` adds further constraints on placement, such as a macOS version.

<CodeGroup>
  ```typescript TypeScript theme={null}
  shape: {
    os: "macos",
    machineArch: "arm64",
    virtualCpu: 6,
    memoryMegabytes: 14336,
    selectors: [{ name: "macos.version", value: "26.x" }],
  }
  ```

  ```go Go theme={null}
  import stdlib "namespacelabs.dev/integrations/proto/namespace/stdlib"

  Shape: &computepb.InstanceShape{
  	Os:              "macos",
  	MachineArch:     "arm64",
  	VirtualCpu:      6,
  	MemoryMegabytes: 14336,
  	Selectors: []*stdlib.Label{
  		{Name: "macos.version", Value: "26.x"},
  	},
  },
  ```
</CodeGroup>

Not every combination of vCPU and memory is available. See [machine shapes](/docs/platform/compute/machine-shapes) for the supported sizes.

## Deadline

`deadline` is a request, not a guarantee. Workspace policy can shorten it, so read `metadata.deadline` on the response for the deadline that actually applies.
Use `ExtendInstance` to push it out while work is still in progress. Its `ensureMinimum` field is idempotent, which makes it suitable for a heartbeat.

## Exported ports

`exportPorts` publishes a container port through the platform. `proto` is either `HTTP`, where Namespace terminates TLS and forwards cleartext HTTP to your container, or `TCP`, where Namespace terminates TLS and proxies the raw stream.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { ContainerPort_Proto } from "@namespacelabs/sdk/proto/namespace/cloud/compute/v1beta/compute_pb";

  containers: [
    {
      name: "web",
      imageRef: "nginx",
      exportPorts: [
        { name: "http", containerPort: 80, proto: ContainerPort_Proto.HTTP },
      ],
    },
  ]
  ```

  ```go Go theme={null}
  Containers: []*computepb.ContainerRequest{{
  	Name:     "web",
  	ImageRef: "nginx",
  	ExportPorts: []*computepb.ContainerPort{
  		{Name: "http", ContainerPort: 80, Proto: computepb.ContainerPort_HTTP},
  	},
  }},
  ```
</CodeGroup>

The allocated endpoint for each port is returned in `containers[].exportedPort[]`.
Exported ports are container-scoped and Linux only. To expose a port on macOS, or to add an endpoint after boot, use the `ingresses` field or the `CreateIngress` RPC.

Exported endpoints require Namespace authentication by default. See [access controls](/docs/platform/networking/ingress#access-controls) for how to authenticate a caller or make a route public.

## Volumes

A container volume with `persistencyKind: CACHE` is restored on a best-effort basis from the most recent volume carrying the same `tag`, which lets a new instance start with a warm cache.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { VolumeRequest_PersistencyKind } from "@namespacelabs/sdk/proto/namespace/cloud/compute/v1beta/compute_pb";

  containers: [
    {
      name: "build",
      imageRef: "busybox",
      volumes: [
        {
          mountPoint: "/cache",
          tag: "build-cache",
          sizeMb: 1024,
          persistencyKind: VolumeRequest_PersistencyKind.CACHE,
        },
      ],
    },
  ]
  ```

  ```go Go theme={null}
  Containers: []*computepb.ContainerRequest{{
  	Name:     "build",
  	ImageRef: "busybox",
  	Volumes: []*computepb.VolumeRequest{{
  		MountPoint:      "/cache",
  		Tag:             "build-cache",
  		SizeMb:          1024,
  		PersistencyKind: computepb.VolumeRequest_CACHE,
  	}},
  }},
  ```
</CodeGroup>

Use `PERSISTENT` instead when the data has to survive reliably. Those volumes are snapshotted on shutdown.
See [cache volumes](/docs/platform/storage/cache-volumes) for how tags and reuse work.

## macOS workloads

macOS instances run `applications` rather than containers. `imageRef` is used only to distribute the files: the platform extracts the image filesystem and runs `command` against it.
`ENTRYPOINT` and `CMD` from the image configuration are not used.

<CodeGroup>
  ```typescript TypeScript theme={null}
  applications: [
    {
      name: "demo",
      imageRef: "nscr.io/<workspace-id>/demo@sha256:<digest>",
      command: "./imagetool",
      args: ["--help"],
      environment: { SHELL: "/usr/bin/bash" },
    },
  ]
  ```

  ```go Go theme={null}
  Applications: []*computepb.ApplicationRequest{{
  	Name:     "demo",
  	ImageRef: "nscr.io/<workspace-id>/demo@sha256:<digest>",
  	Command:  "./imagetool",
  	Args:     []string{"--help"},
  	Environment: map[string]string{
  		"SHELL": "/usr/bin/bash",
  	},
  }},
  ```
</CodeGroup>

See [macOS](/docs/platform/compute/macos) for available versions and base images.

## Reusing an instance

`experimental.uniqueTag` makes creation idempotent. Repeating a request with the same tag returns the running instance instead of creating a second one, and `ReleaseUniqueTag` gives the tag up again.
Fields under `experimental` can change or be removed at any time.

<CodeGroup>
  ```typescript TypeScript theme={null}
  experimental: { uniqueTag: "my-worker" }
  ```

  ```go Go theme={null}
  Experimental: &computepb.CreateInstanceRequest_ExperimentalFeatures{
  	UniqueTag: "my-worker",
  },
  ```
</CodeGroup>


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