Instance Configuration

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

shape: {
  os: "macos",
  machineArch: "arm64",
  virtualCpu: 6,
  memoryMegabytes: 14336,
  selectors: [{ name: "macos.version", value: "26.x" }],
}

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"},
	},
},

Not every combination of vCPU and memory is available. See 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.

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 },
    ],
  },
]

Containers: []*computepb.ContainerRequest{{
	Name:     "web",
	ImageRef: "nginx",
	ExportPorts: []*computepb.ContainerPort{
		{Name: "http", ContainerPort: 80, Proto: computepb.ContainerPort_HTTP},
	},
}},

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

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,
      },
    ],
  },
]

Containers: []*computepb.ContainerRequest{{
	Name:     "build",
	ImageRef: "busybox",
	Volumes: []*computepb.VolumeRequest{{
		MountPoint:      "/cache",
		Tag:             "build-cache",
		SizeMb:          1024,
		PersistencyKind: computepb.VolumeRequest_CACHE,
	}},
}},

Use PERSISTENT instead when the data has to survive reliably. Those volumes are snapshotted on shutdown. See 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.

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

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",
	},
}},

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

experimental: { uniqueTag: "my-worker" }

Experimental: &computepb.CreateInstanceRequest_ExperimentalFeatures{
	UniqueTag: "my-worker",
},

Build with Namespace

Building Blocks

Machine shape

Deadline

Exported ports

Volumes

macOS workloads

Reusing an instance

​Machine shape

​Deadline

​Exported ports

​Volumes

​macOS workloads

​Reusing an instance

Machine shape

Deadline

Exported ports

Volumes

macOS workloads

Reusing an instance