nsc build - Namespace Documentation
Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Assistant
Responses are generated using AI and may contain mistakes.
Build container images using Namespace Remote Builders.build builds a container image using provided Dockerfile and a “context”.
A build’s context is the set of files located in the specified PATH. The built
image can be either pushed to the target image registry or loaded to the local
docker registry.
Usage
nsc build PATH [--build-arg <arg[,arg]>] [-f <Dockerfile>] [--load] [-n <name[,name]>] [--output-local <path>] [--platform <platform[,platform]>] [--push] [--secret <id=mysecret[,src=/local/secret]>] [-t <tag[,tag]>]
Example
The following builds an image with name app using
docker file in the current directory (e.g. ./Dockerfile) and pushes it to the user’s
Workspace Container Registry (e.g. nscr.io/8enum0hp1l5ii).
nsc build . --name app --push
Output
Pushed for linux/amd64:
nscr.io/8enum0hp1l5ii/app:latest
You can tag and push the container image to any Container Registry of your choice. For example, the following would push to GitHub Container Registry.
nsc build . --tag ghcr.io/apprepo/app --push
Output
Pushed for linux/amd64:
ghcr.io/apprepo/app:latest
nsc build uses your local Docker credentials provider. So to push images to container registries, you need to log in with docker login
Available Commands
Options
—file, -f
To specify a Dockerfile to build. By default PATH/Dockerfile is used.
—tag, -t <tag[,tag]>
Set the image name and optionally a tag (format: “name:tag”). This option can accept multiple values as an input separated by a comma.
—name, -n <name[,name]>
Similarly to -t, it sets the image name and optionally a tag (format: “name:tag”).
It automatically specifies the Workspace Registry repository as part of the tags (i.e. nscr.io/<workspace ID>).
This option can accept multiple values as an input separated by a comma.
—build-arg <arg[,arg]>
This flag allows you to pass the build-time variables that are accessed like
regular environment variables in the RUN instruction of the Dockerfile.
—platform <platform[,platform]>
Set the target platform for the build. The default value is the platform of the
local host. The value takes the form of os/arch or os/arch/variant.
For example, linux/amd64 or linux/arm/v7.This option can accept multiple values as an input separated by a comma. With
multiple values the result will be built for all the specified platforms and
joined together into a single manifest list.
—push
Specify the option to push the build result to registry. nsc will push images
for all the provided with -t or -n options tags.
—load
Specify the option to automatically load the single-platform build result to
the local docker registry. Note that --load doesn’t support multi-platform
image builds.
—output-local
If set, writes the build output directly to the specified local directory instead of pushing the image to a registry or loading it into the local Docker registry. Use this when you need the raw build artifacts on disk rather than a container image.
—secret
A secret to expose to the build. Format: id=ID[,src=FILEPATH][,env=VARIABLE].
See also build secrets usage.
Last modified onOctober 26, 2026
Ctrl+I
{"docsConfig":{"theme":"almond","$schema":"https://mintlify.com/docs.json","name":"Namespace Documentation","colors":{"primary":"#1C32FF","light":"#6B78FF","dark":"#1C32FF"},"logo":{"light":"https://mintcdn.com/namespace-labs/qOJQ7kaWRgoS8lyv/logo-light.svg?fit=max\\u0026auto=format\\u0026n=qOJQ7kaWRgoS8lyv\\u0026q=85\\u0026s=6827b0c81c335badc1cef13b83383e1d","dark":"https://mintcdn.com/namespace-labs/qOJQ7kaWRgoS8lyv/logo-dark.svg?fit=max\\u0026auto=format\\u0026n=qOJQ7kaWRgoS8lyv\\u0026q=85\\u0026s=63702d83d8fb259023deb79db06aabbb","href":"https://namespace.so"},"favicon":"https://mintcdn.com/namespace-labs/MoefQ379UcpNU680/favicon.svg?fit=max\\u0026auto=format\\u0026n=MoefQ379UcpNU680\\u0026q=85\\u0026s=6f14a088da55e5f41847845796737353","navbar":{"links":\[{"href":"https://namespace.so/changelog","label":"Changelog"},{"href":"https://namespace.so/support","label":"Support"}\],"primary":{"type":"button","label":"Log in","href":"https://cloud.namespace.so"}},"footer":{"socials":{"github":"https://github.com/namespacelabs","linkedin":"https://www.linkedin.com/company/namespacelabs","x":"https://x.com/namespacelabs"}},"icons":{"library":"lucide"},"contextual":{"options":\["copy","view","chatgpt","claude"\],"display":"header"},"interaction":{"drilldown":false},"metadata":{"timestamp":true},"styling":{"latex":true},"navigation":{"global":{"anchors":\[{"anchor":"Changelog","icon":"history","href":"https://namespace.so/changelog"},{"anchor":"Trust Center (SOC2)","icon":"shield-check","href":"https://trust.namespace.so/"},{"anchor":"Status","icon":"activity","href":"https://namespace-status.com/"},{"anchor":"Support","icon":"message-circle","href":"https://namespace.so/support"}\]},"pages":\[\]}},"deployment":{"deploymentMetadataValue":{"subdomain":"namespace-labs","hasAudioNarration":false,"actualSubdomain":"namespace-labs","customDomains":\["namespace.so"\],"gitSource":{"type":"github","owner":"namespacelabs","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6ae0862207896b4595e1934b","collectionId":"847aecca-4a0b-40b4-a393-e976cc214b43","liveDeploymentHistoryId":"6ae0862207896b4595e1934b","schemaVersion":"v3"},"entitlements":{"AI\_CHAT":{"status":"ENABLED"},"WEB\_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6ae0a8f6edbd4c098a94623c","clientVersion":"0.0.3971","searchFilterCounts":\[{"language":"default","tag":"Products","count":377},{"language":"default","tag":"CLI","count":166},{"language":"default","tag":"Command line","count":165},{"language":"default","tag":"Namespace CLI","count":131},{"language":"default","tag":"Documentation","count":104},{"language":"default","tag":"GitHub Actions","count":40},{"language":"default","tag":"Devbox CLI","count":34},{"language":"default","tag":"Integrations","count":33},{"language":"default","tag":"SDK","count":25},{"language":"default","tag":"Namespace SDK","count":23}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"/docs","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-v7-file-tree","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"pause-universal-search-reconcile","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"per-site-search-delta","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-private-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-nav-generations","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-agent-model-picker","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"isAtlas":false,"googleFontsInlined":true},"customCss":[{"filePath":"snippets/diagrams/styles.css","content":".ns-diagram{--ns-diagram-background:#ffffff;--ns-diagram-grid:#e5e7ee;--ns-diagram-border:#e5e7ee;--ns-diagram-card:#ffffff;--ns-diagram-neutral-zone:#fafbfc;--ns-diagram-brand-zone-start:rgba(28, 50, 255, 0.04);--ns-diagram-brand-zone-end:rgba(28, 50, 255, 0.07);--ns-diagram-brand-border:#c8ceff;--ns-diagram-heading:#202938;--ns-diagram-muted:#8892a6;--ns-diagram-copy:#4a5468;position:relative;width:100%;margin:2rem 0;padding:clamp(20px,3.5vw,32px);overflow:hidden;color:var(--ns-diagram-heading);background:var(--ns-diagram-background);border:1px solid var(--ns-diagram-border);border-radius:20px;box-shadow:0 1px 0 rgba(32,41,56,.04),0 1px 2px rgba(32,41,56,.06)}.dark .ns-diagram{--ns-diagram-background:#111827;--ns-diagram-grid:#374151;--ns-diagram-border:#374151;--ns-diagram-card:#1f2937;--ns-diagram-neutral-zone:#171f2d;--ns-diagram-brand-zone-start:rgba(107, 120, 255, 0.1);--ns-diagram-brand-zone-end:rgba(107, 120, 255, 0.16);--ns-diagram-brand-border:#4f5fc7;--ns-diagram-heading:#f3f4f6;--ns-diagram-muted:#aeb6c5;--ns-diagram-copy:#cbd5e1}.ns-diagram-grid-background{position:absolute;inset:0;pointer-events:none;background-image:radial-gradient(circle,var(--ns-diagram-grid) 1px,transparent 1px);background-size:16px 16px;opacity:.5;mask-image:linear-gradient(180deg,transparent 0,#000 10%,#000 90%,transparent 100%)}.ns-diagram-content{position:relative}.ns-diagram-caption{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0}.ns-diagram-mark{display:inline-flex;flex-shrink:0;align-items:center;justify-content:center;margin:0;border-radius:8px}.ns-diagram-mark-anthropic{color:#d97757;background:#fcefe8}.ns-diagram-mark-devin{color:#4338ca;background:#eef0ff}.ns-diagram-mark-cursor{color:#111827;background:#eef0f3}.ns-diagram-mark-control{color:#1c32ff;background:#e0e7ff}.ns-diagram-mark-terminal{color:#fff;background:#202938}.ns-diagram-mark-worker{color:#4338ca;background:#eef1ff}.ns-diagram-zone{position:relative;display:flex;flex-direction:column;padding:1.25rem;background:var(--ns-diagram-neutral-zone);border:1px dashed #d2d6e0;border-radius:14px}.dark .ns-diagram-zone{border-color:#4b5563}.ns-diagram-zone-brand{background:linear-gradient(180deg,var(--ns-diagram-brand-zone-start),var(--ns-diagram-brand-zone-end));border:1px solid var(--ns-diagram-brand-border)}.ns-diagram-zone-header{display:flex;align-items:center;gap:.5rem;margin-bottom:.75rem;color:var(--ns-diagram-copy);font-size:11px;font-weight:600;letter-spacing:.1em;text-transform:uppercase}.ns-diagram-zone-center{display:flex;flex:1;align-items:center}.ns-diagram-zone-center>*{width:100%}.ns-diagram-card{position:relative;display:flex;align-items:center;gap:1rem;min-width:0;padding:1rem 1.25rem;background:var(--ns-diagram-card);border:1px solid var(--ns-diagram-border);border-radius:12px;box-shadow:0 1px 0 rgba(32,41,56,.04),0 1px 2px rgba(32,41,56,.06)}.ns-diagram-card-brand{border-color:var(--ns-diagram-brand-border)}.ns-diagram-card-copy{display:flex;min-width:0;flex-direction:column}.ns-diagram-card-label{color:var(--ns-diagram-heading);font-size:16px;font-weight:600;line-height:1.25;letter-spacing:-.01em}.ns-diagram-card-sublabel{margin-top:.125rem;color:var(--ns-diagram-muted);font-size:12px;line-height:1.35}.ns-managed-layout{display:grid;grid-template-columns:1fr auto 1.05fr;align-items:stretch}.ns-managed-connector{display:flex;width:64px;flex-direction:column;align-items:center;justify-content:center;padding:0 .25rem;color:var(--ns-diagram-muted);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10.5px}.ns-managed-connector>span{margin-bottom:.375rem}.ns-managed-connector-path{display:flex;width:56px;align-items:center}.ns-managed-connector-line{flex:1;height:1.5px;background:#d2d6e0}.ns-managed-connector-arrow{border-top:6px solid transparent;border-bottom:6px solid transparent;border-left:9px solid #d2d6e0}.ns-mini-connector{display:flex;flex-direction:column;align-items:center;padding:.375rem 0}.ns-mini-connector>div{width:1.5px;height:12px;background:var(--ns-diagram-brand-border)}.ns-mini-connector>span{border-top:7px solid var(--ns-diagram-brand-border);border-right:5px solid transparent;border-left:5px solid transparent}.ns-devin-devboxes,.ns-devin-sessions{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:1.5rem}.ns-devin-mobile-layout{display:none}.ns-devin-connectors,.ns-devin-connectors>div{display:grid;grid-template-columns:repeat(2,minmax(0,1fr))}.ns-devin-connectors{gap:1.5rem}.ns-devin-connectors>div{padding:0 1rem}.ns-devin-connector{position:relative;display:flex;min-height:110px;align-items:center;justify-content:center;color:var(--ns-diagram-copy);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10px;line-height:1.25;text-align:center}.ns-devin-management-connector{min-height:70px;color:#6366f1}.ns-devin-connector-line{position:absolute;top:0;bottom:0;left:50%;width:1.5px;background:#d2d6e0;transform:translateX(-50%)}.ns-devin-management-connector .ns-devin-connector-line,.ns-diagram-connector-dashed .ns-diagram-vertical-line{width:0;background:0 0;border-left:1.5px dashed var(--ns-diagram-brand-border)}.ns-devin-connector>span,.ns-diagram-vertical-connector>span{position:relative;z-index:1;padding:0 .375rem;background:var(--ns-diagram-background)}.ns-control-plane-pill{display:flex;align-items:center;align-self:center;gap:.375rem;margin-bottom:1rem;padding:.375rem .75rem;color:#4338ca;background:#eef1ff;border:1px solid var(--ns-diagram-brand-border);border-radius:999px;font-size:12px;font-weight:500}.ns-diagram-vertical-connector{position:relative;display:flex;align-items:center;justify-content:center;color:var(--ns-diagram-copy);font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,monospace;font-size:10px;line-height:1.25;text-align:center}.ns-diagram-vertical-line{position:absolute;top:0;bottom:0;left:50%;width:1.5px;background:#d2d6e0;transform:translateX(-50%)}.ns-diagram-connector-dashed{color:#6366f1}.ns-diagram-arrow-down{position:absolute;bottom:0;left:50%;border-top:8px solid #d2d6e0;border-right:5px solid transparent;border-left:5px solid transparent;transform:translateX(-50%)}.ns-devin-management-connector .ns-diagram-arrow-down,.ns-diagram-connector-dashed .ns-diagram-arrow-down{border-top-color:var(--ns-diagram-brand-border)}.ns-bazel-connector-inset{padding:0 1rem}.ns-bazel-workers{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:1rem}@media (max-width:767px){.ns-managed-layout{grid-template-columns:1fr}.ns-managed-connector{position:relative;width:auto;min-height:64px;padding:.5rem 0}.ns-managed-connector-path{width:auto;flex-direction:column}.ns-managed-connector-line{width:1.5px;height:24px;flex:none}.ns-managed-connector-arrow{border-top:9px solid #d2d6e0;border-right:6px solid transparent;border-bottom:0;border-left:6px solid transparent}.ns-devin-connectors,.ns-devin-devboxes,.ns-devin-sessions{grid-template-columns:1fr}.ns-devin-desktop-layout{display:none}.ns-devin-mobile-layout{display:block}.ns-devin-mobile-lane+.ns-devin-mobile-lane{margin-top:1.5rem;padding-top:1.5rem;border-top:1px solid var(--ns-diagram-border)}.ns-devin-mobile-connectors{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));padding:0 .5rem}.ns-devin-connector{min-height:80px}.ns-bazel-workers{grid-template-columns:1fr}}"},{"filePath":"style.css","content":":root{--namespace-radius-inline:0.25rem;--namespace-radius-control:0.375rem;--namespace-radius-container:0.5rem}#content-container,.almond-layout>div,.card,.chat-assistant-floating-input>div,.code-block,.frame,.pagination-next,.pagination-prev{border-radius:var(--namespace-radius-container)}.code-block [data-component-part=code-block-root],.frame>div{border-radius:inherit}#assistant-entry,#chat-assistant-textarea,#search-bar-entry,#search-input,.callout,.frame>.relative{border-radius:var(--namespace-radius-control)}.code-block-fade-overlay{border-radius:0 var(--namespace-radius-container) var(--namespace-radius-container) 0}#page-context-menu>button:first-child{border-radius:var(--namespace-radius-control) 0 0 var(--namespace-radius-control)}#page-context-menu>button:last-child{border-radius:0 var(--namespace-radius-control) var(--namespace-radius-control) 0}#content :not(pre)>code,#navigation-items li>a,#navigation-items li>button{border-radius:var(--namespace-radius-inline)}#navigation-items .nav-anchor>:is(svg, img),#navigation-items .sidebar-group-icon,#navigation-items [data-component-part=scroll-area-content]:has(>ul.nav-anchors),#navigation-items li>:is(a, button)>div[class=\"h-[1lh]\"]:first-child{display:flex;flex-direction:column}#navigation-items [data-component-part=scroll-area-content]>ul.nav-anchors{order:1;margin-top:1rem;padding-top:1rem;border-top:1px solid color-mix(in srgb,currentColor 10%,transparent)}#navigation-items [data-component-part=scroll-area-content]>ul.sidebar-group{margin-top:.5rem}#navigation-items [data-component-part=scroll-area-content]>ul.sidebar-group+div{margin-top:1rem}.tab-container{overflow:hidden;padding:0 1rem 1rem;border:1px solid color-mix(in srgb,currentColor 12%,transparent);border-radius:var(--namespace-radius-container)}.tab-container [data-component-part=tab-content]>[data-table-wrapper]:last-child{margin-bottom:0;padding-bottom:0}#content .katex-display>.katex{text-align:left}.compact-table table td{min-width:0}#navigation-items ul.sidebar-group>li.space-y-px+li.space-y-px{margin-top:.75rem}#navigation-items .my-2>.sidebar-group-header{margin-bottom:.625rem;font-size:.8125rem;line-height:1.625rem;font-weight:600;letter-spacing:-.02em;text-transform:none;opacity:1}#navigation-items ul.sidebar-group>li.space-y-px>button{font-size:.8125rem;font-weight:600;letter-spacing:-.02em;background-color:transparent}#navigation-items ul.sidebar-group>li.space-y-px>button:hover,#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button:hover{background-color:color-mix(in srgb,currentColor 6%,transparent)}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button,#navigation-items ul.sidebar-group>li.space-y-px>ul>li>a{padding-left:3rem!important;font-size:.8125rem;font-weight:400;letter-spacing:-.02em}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li[data-active-nav-item=true]>a,#navigation-items ul.sidebar-group>li.space-y-px>ul>li[data-active-nav-item=true]>a{color:#121516!important;background-color:rgb(18 21 22/6%)!important}.dark #navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li[data-active-nav-item=true]>a,.dark #navigation-items ul.sidebar-group>li.space-y-px>ul>li[data-active-nav-item=true]>a{color:#f4f4f5!important;background-color:rgb(255 255 255/8%)!important}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button{background-color:transparent}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>button>div[class=\"h-[1lh]\"]:first-child{margin-left:-1.75rem}.dark #navigation-items img[src*=buildkite-mark]{filter:brightness(.7)}.dark img[src*=\"/icons/apple.svg\"]{filter:invert(1)}.dark img.tab-icon[src*=\"/icons/linux.svg\"]{filter:invert(.35) brightness(1.54)}#navigation-items ul.sidebar-group>li.space-y-px>ul>li.space-y-px>ul>li>a{padding-left:4rem!important;font-size:.8125rem;font-weight:400;letter-spacing:-.02em}@media (min-width:1024px){#sidebar-content{width:calc(16.5rem + 10px)}#content-container{margin-left:calc(16.5rem + 10px)}#navbar{container-type:inline-size}#navbar .nav-tabs{position:fixed;top:0;left:20rem;height:3.5rem;column-gap:2rem}#navbar div:has(>div>.nav-tabs){justify-content:flex-end}@container (max-width: 69rem){#navbar .navbar-link:has(>a[href=\"https://namespace.so/changelog\\"\]){display:none}}}@media (min-width:1280px){#content-container{padding-right:1.5rem;padding-left:3rem}#content-container>div{column-gap:1.5rem;justify-content:flex-start}#content-area{width:calc(100% - 13.5rem);max-width:52rem;flex:none}#content-side-layout{width:15rem;max-width:15rem;flex-basis:15rem}#content-side-layout>div{width:15rem;padding-left:1rem}#content-side-layout>div>div{width:14rem}}@media (min-width:1700px){#content-container>div{justify-content:center}}"},{"filePath":"reference/github-actions/runner-configuration.css","content":""},{"filePath":"workspaces/access.css","content":""},{"filePath":"platform/workspaces/access.css","content":""},{"filePath":"reference/devbox-cli/desktop.css","content":""}],"page":{"pagePath":"reference/cli/build","slug":"/reference/cli/build","pageMetadata":{"title":"nsc build","description":null,"href":"/reference/cli/build"},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);return _jsxs(_Fragment,{children:[_jsxs(_components.p,{children:[`Build container images using `,_jsx(_components.a,{href:`/solutions/docker-builders`,children:`Namespace Remote Builders`}),`.`]}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`build`}),` builds a container image using provided `,_jsx(_components.code,{children:`Dockerfile`}),` and a “context”.\nA build’s context is the set of files located in the specified `,_jsx(_components.code,{children:`PATH`}),`. The built\nimage can be either pushed to the target image registry or loaded to the local\ndocker registry.`]}),`\n`,_jsx(Heading,{level:`2`,id:`usage`,children:`Usage`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`nsc`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` build`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` PATH`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [--build-arg `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`arg[,arg`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`]`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [-f `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`Dockerfil`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`e`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:`]`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:` [--load] [-n `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`name[,name]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] [--output-local `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`path`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] [--platform `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`platform[,platform]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] [--push] [--secret `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`id`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`mysecret[,src`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`=`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`/local/secret]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`] [-t `}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`\u003c`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`tag[,tag]`}),_jsx(_components.span,{style:{color:`#CF222E`,\"--shiki-dark\":`#D4D4D4`},children:`>`}),_jsx(_components.span,{style:{color:`#1F2328`,\"--shiki-dark\":`#D4D4D4`},children:`]`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`3`,id:`example`,children:`Example`}),`\n`,_jsxs(_components.p,{children:[`The following builds an image with name `,_jsx(_components.strong,{children:`app`}),` using\ndocker file in the current directory (e.g. `,_jsx(_components.code,{children:`./Dockerfile`}),`) and pushes it to the user’s\nWorkspace Container Registry (e.g. `,_jsx(_components.code,{children:`nscr.io/8enum0hp1l5ii`}),`).`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`nsc`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` build`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --name`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` app`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --push`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:`Output`,nocopy:`true`,numberOfLines:`3`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`Pushed for linux/amd64:`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` nscr.io/8enum0hp1l5ii/app:latest`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`You can tag and push the container image to any Container Registry of your choice.\nFor example, the following would push to GitHub Container Registry.`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#953800`,\"--shiki-dark\":`#DCDCAA`},children:`nsc`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` build`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` .`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --tag`}),_jsx(_components.span,{style:{color:`#0A3069`,\"--shiki-dark\":`#CE9178`},children:` ghcr.io/apprepo/app`}),_jsx(_components.span,{style:{color:`#0550AE`,\"--shiki-dark\":`#569CD6`},children:` --push`})]}),`\n`]})})}),`\n`,_jsx(CodeBlock,{filename:`Output`,nocopy:`true`,numberOfLines:`3`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`Pushed for linux/amd64:`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:` ghcr.io/apprepo/app:latest`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`nsc build`}),` uses your local Docker credentials provider. So to push images to container registries, you need to log in with `,_jsx(_components.code,{children:`docker login`})]}),`\n`,_jsx(Heading,{level:`2`,id:`available-commands`,children:`Available Commands`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.a,{href:`/reference/cli/build-logs`,children:`logs`})}),` - Print logs for a build.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.strong,{children:_jsx(_components.a,{href:`/reference/cli/build-resolve`,children:`resolve`})}),` - Resolve container build references by origin.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`options`,children:`Options`}),`\n`,_jsx(Heading,{level:`3`,id:`--file--f-dockerfile`,children:`—file, -f \u003cDockerfile>`}),`\n`,_jsxs(_components.p,{children:[`To specify a Dockerfile to build. By default `,_jsx(_components.code,{children:`PATH/Dockerfile`}),` is used.`]}),`\n`,_jsx(Heading,{level:`3`,id:`--tag--t-tagtag`,children:`—tag, -t \u003ctag[,tag]>`}),`\n`,_jsx(_components.p,{children:`Set the image name and optionally a tag (format: “name:tag”). This option can\naccept multiple values as an input separated by a comma.`}),`\n`,_jsx(Heading,{level:`3`,id:`--name--n-namename`,children:`—name, -n \u003cname[,name]>`}),`\n`,_jsxs(_components.p,{children:[`Similarly to `,_jsx(_components.code,{children:`-t`}),`, it sets the image name and optionally a tag (format: “name:tag”).\nIt automatically specifies the Workspace Registry repository as part of the tags (i.e. `,_jsx(_components.code,{children:`nscr.io/\u003cworkspace ID>`}),`).\nThis option can accept multiple values as an input separated by a comma.`]}),`\n`,_jsx(Heading,{level:`3`,id:`--build-arg-argarg`,children:`—build-arg \u003carg[,arg]>`}),`\n`,_jsxs(_components.p,{children:[`This flag allows you to pass the build-time variables that are accessed like\nregular environment variables in the `,_jsx(_components.code,{children:`RUN`}),` instruction of the Dockerfile.`]}),`\n`,_jsx(Heading,{level:`3`,id:`--platform-platformplatform`,children:`—platform \u003cplatform[,platform]>`}),`\n`,_jsxs(_components.p,{children:[`Set the target platform for the build. The default value is the platform of the\nlocal host. The value takes the form of `,_jsx(_components.code,{children:`os/arch`}),` or os/arch/variant.\nFor example, `,_jsx(_components.code,{children:`linux/amd64`}),` or `,_jsx(_components.code,{children:`linux/arm/v7`}),`.`]}),`\n`,_jsx(_components.p,{children:`This option can accept multiple values as an input separated by a comma. With\nmultiple values the result will be built for all the specified platforms and\njoined together into a single manifest list.`}),`\n`,_jsx(Heading,{level:`3`,id:`--push`,children:`—push`}),`\n`,_jsxs(_components.p,{children:[`Specify the option to push the build result to registry. `,_jsx(_components.code,{children:`nsc`}),` will push images\nfor all the provided with `,_jsx(_components.code,{children:`-t`}),` or `,_jsx(_components.code,{children:`-n`}),` options tags.`]}),`\n`,_jsx(Heading,{level:`3`,id:`--load`,children:`—load`}),`\n`,_jsxs(_components.p,{children:[`Specify the option to automatically load the single-platform build result to\nthe local docker registry. Note that `,_jsx(_components.code,{children:`--load`}),` doesn’t support multi-platform\nimage builds.`]}),`\n`,_jsx(Heading,{level:`3`,id:`--output-local-path`,children:`—output-local \u003cpath>`}),`\n`,_jsx(_components.p,{children:`If set, writes the build output directly to the specified local directory\ninstead of pushing the image to a registry or loading it into the local\nDocker registry. Use this when you need the raw build artifacts on disk\nrather than a container image.`}),`\n`,_jsx(Heading,{level:`3`,id:`--secret`,children:`—secret`}),`\n`,_jsxs(_components.p,{children:[`A secret to expose to the build. Format: `,_jsx(_components.code,{children:`id=ID[,src=FILEPATH][,env=VARIABLE]`}),`.\nSee also `,_jsx(_components.a,{href:`https://docs.docker.com/build/building/secrets/#using-build-secrets\`,children:\`build secrets usage`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"nsc build","description":null,"href":"/reference/cli/build"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Usage","slug":"usage","depth":2,"children":[{"title":"Example","slug":"example","depth":3,"children":[]}]},{"title":"Available Commands","slug":"available-commands","depth":2,"children":[]},{"title":"Options","slug":"options","depth":2,"children":[{"title":"—file, -f \u003cDockerfile>","slug":"--file--f-dockerfile","depth":3,"children":[]},{"title":"—tag, -t \u003ctag[,tag]>","slug":"--tag--t-tagtag","depth":3,"children":[]},{"title":"—name, -n \u003cname[,name]>","slug":"--name--n-namename","depth":3,"children":[]},{"title":"—build-arg \u003carg[,arg]>","slug":"--build-arg-argarg","depth":3,"children":[]},{"title":"—platform \u003cplatform[,platform]>","slug":"--platform-platformplatform","depth":3,"children":[]},{"title":"—push","slug":"--push","depth":3,"children":[]},{"title":"—load","slug":"--load","depth":3,"children":[]},{"title":"—output-local \u003cpath>","slug":"--output-local-path","depth":3,"children":[]},{"title":"—secret","slug":"--secret","depth":3,"children":[]}]}],"codeExamples":{}},"jsLinks":["/docs/_mintlify/custom/namespace-labs/fa018fe02fd436c8/navigation.js","/docs/_mintlify/custom/namespace-labs/4276600b7cb636ff/legacy-anchor-redirects.js"],"subdomain":"namespace-labs","siteName":"Namespace Documentation","title":"nsc build - Namespace Documentation","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-10-26T10:46:17.689Z","gitLastModified":"2026-10-26T10:45:54.000Z","originalFileLocation":"reference/cli/build.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"application-name\" content=\"Namespace Documentation\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"nsc build - Namespace Documentation\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Namespace Documentation\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://namespace.so/docs/reference/cli/build\\">\\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://namespace-labs.mintlify.app/\_mintlify/api/og/v2?division=Build\\u0026amp;title=nsc+build\\u0026amp;theme=1f89d53762a6d5304d1c63c4\\u0026amp;signature=ca795475eb7f98d0d4962d5da974d279d4ea67bac18d0c6c5464b49251d43217\\">\\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"nsc build - Namespace Documentation\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://namespace-labs.mintlify.app/\_mintlify/api/og/v2?division=Build\\u0026amp;title=nsc+build\\u0026amp;theme=1f89d53762a6d5304d1c63c4\\u0026amp;signature=ca795475eb7f98d0d4962d5da974d279d4ea67bac18d0c6c5464b49251d43217\\">\\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/namespace-labs/kZKeJ4zhJEuE6_kI/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Namespace Documentation\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#1C32FF\">\u003clink data-mint-head rel=\"canonical\" href=\"https://namespace.so/docs/reference/cli/build\\">\\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/reference/cli/build.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\\",\\"@graph\\":\[{\\"@type\\":\\"Organization\\",\\"@id\\":\\"https://namespace.so/#organization\\",\\"name\\":\\"Namespace Documentation\",\"url\":\"https://namespace.so\\",\\"logo\\":{\\"@type\\":\\"ImageObject\\",\\"url\\":\\"https://mintcdn.com/namespace-labs/qOJQ7kaWRgoS8lyv/logo-light.svg?fit=max\\u0026auto=format\\u0026n=qOJQ7kaWRgoS8lyv\\u0026q=85\\u0026s=6827b0c81c335badc1cef13b83383e1d\\"}},{\\"@type\\":\\"WebSite\\",\\"@id\\":\\"https://namespace.so/docs#website\\",\\"name\\":\\"Namespace Documentation\",\"url\":\"https://namespace.so/docs\\",\\"publisher\\":{\\"@id\\":\\"https://namespace.so/#organization\\"}},{\\"@type\\":\\"WebPage\\",\\"@id\\":\\"https://namespace.so/docs/reference/cli/build#webpage\\",\\"url\\":\\"https://namespace.so/docs/reference/cli/build\\",\\"name\\":\\"nsc build\",\"dateModified\":\"2026-10-26T10:45:54.000Z\",\"isPartOf\":{\"@id\":\"https://namespace.so/docs#website\\"},\\"breadcrumb\\":{\\"@id\\":\\"https://namespace.so/docs/reference/cli/build#breadcrumb\\"}},{\\"@type\\":\\"BreadcrumbList\\",\\"@id\\":\\"https://namespace.so/docs/reference/cli/build#breadcrumb\\",\\"itemListElement\\":\[{\\"@type\\":\\"ListItem\\",\\"position\\":1,\\"name\\":\\"Command line\",\"item\":\"https://namespace.so/docs/reference/cli/installation\\"},{\\"@type\\":\\"ListItem\\",\\"position\\":2,\\"name\\":\\"Namespace CLI\",\"item\":\"https://namespace.so/docs/reference/cli/installation\\"},{\\"@type\\":\\"ListItem\\",\\"position\\":3,\\"name\\":\\"nsc build\",\"item\":\"https://namespace.so/docs/reference/cli/build\\"}\]},{\\"@type\\":\[\\"Article\\",\\"TechArticle\\"\],\\"@id\\":\\"https://namespace.so/docs/reference/cli/build#article\\",\\"headline\\":\\"nsc build\",\"name\":\"nsc build\",\"url\":\"https://namespace.so/docs/reference/cli/build\\",\\"mainEntityOfPage\\":{\\"@id\\":\\"https://namespace.so/docs/reference/cli/build#webpage\\"},\\"dateModified\\":\\"2026-10-26T10:45:54.000Z\\",\\"publisher\\":{\\"@id\\":\\"https://namespace.so/#organization\\"},\\"isPartOf\\":{\\"@id\\":\\"https://namespace.so/docs#website\\"}}\]}\\u003c/script>\\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\\",\\"@type\\":\\"WebSite\\",\\"name\\":\\"Namespace Documentation\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\\"}}\\u003c/script>","siteName":"Namespace Documentation","nav":{"global":{"anchors":[{"anchor":"Changelog","icon":"history","href":"https://namespace.so/changelog"},{"anchor":"Trust Center (SOC2)","icon":"shield-check","href":"https://trust.namespace.so/"},{"anchor":"Status","icon":"activity","href":"https://namespace-status.com/"},{"anchor":"Support","icon":"message-circle","href":"https://namespace.so/support"}\]},"products":\[{"product":"Products","description":"Turnkey products built on the Namespace platform","tabs":[{"tab":"Documentation","icon":"book-open","pages":[{"title":"Documentation","href":""}]},{"tab":"Integrations","icon":"blocks","pages":[{"title":"Integrations","href":"/integrations/turborepo"}]},{"tab":"CLI","icon":"square-terminal","pages":[{"title":"Namespace Command Line Tools","sidebarTitle":"Overview","icon":"terminal","href":"/reference/cli"},{"group":"Command line","pages":[{"group":"Namespace CLI","icon":"square-terminal","expanded":false,"pages":[{"title":"Installation","href":"/reference/cli/installation"},{"group":"Setup and authentication","icon":"wrench","pages":[{"title":"nsc install","href":"/reference/cli/install"},{"title":"nsc completion","href":"/reference/cli/completion"},{"title":"nsc login","href":"/reference/cli/login"},{"title":"nsc logout","href":"/reference/cli/logout"},{"title":"nsc workspace describe","href":"/reference/cli/workspace-describe"},{"title":"nsc workspace concurrency","href":"/reference/cli/workspace-concurrency"}]},{"group":"Manage instances","icon":"server","pages":[{"title":"nsc create","href":"/reference/cli/create"},{"title":"nsc list","href":"/reference/cli/list"},{"title":"nsc describe","href":"/reference/cli/describe"},{"title":"nsc extend","href":"/reference/cli/extend"},{"title":"nsc destroy","href":"/reference/cli/destroy"},{"title":"nsc scratch ssh","href":"/reference/cli/scratch-ssh"}]},{"group":"Connect and inspect","icon":"terminal","pages":[{"title":"nsc ssh","href":"/reference/cli/ssh"},{"title":"nsc proxy","href":"/reference/cli/proxy"},{"title":"nsc rdp","href":"/reference/cli/rdp"},{"title":"nsc vnc","href":"/reference/cli/vnc"},{"title":"nsc logs","href":"/reference/cli/logs"},{"title":"nsc top","href":"/reference/cli/top"}]},{"group":"Run commands and workloads","icon":"play","pages":[{"title":"nsc run","href":"/reference/cli/run"},{"title":"nsc exec-scoped","href":"/reference/cli/exec-scoped"},{"title":"nsc kubectl","href":"/reference/cli/kubectl"}]},{"group":"Artifact","icon":"package","pages":[{"title":"nsc artifact list","href":"/reference/cli/artifact-list"},{"title":"nsc artifact upload","href":"/reference/cli/artifact-upload"},{"title":"nsc artifact download","href":"/reference/cli/artifact-download"},{"title":"nsc artifact describe","href":"/reference/cli/artifact-describe"},{"title":"nsc artifact extend","href":"/reference/cli/artifact-extend"},{"title":"nsc artifact expire","href":"/reference/cli/artifact-expire"},{"title":"nsc artifact cache-url","href":"/reference/cli/artifact-cache-url"}]},{"group":"Auth","icon":"key-round","pages":[{"title":"nsc auth check-login","href":"/reference/cli/auth-check-login"},{"title":"nsc auth generate-dev-token","href":"/reference/cli/auth-generate-dev-token"},{"title":"nsc auth issue-id-token","href":"/reference/cli/auth-issue-id-token"},{"title":"nsc auth issue-client-cert","href":"/reference/cli/auth-issue-client-cert"},{"title":"nsc auth exchange-oidc-token","href":"/reference/cli/auth-exchange-oidc-token"},{"title":"nsc auth exchange-aws-cognito-token","href":"/reference/cli/auth-exchange-aws-cognito-token"},{"title":"nsc auth exchange-circleci-token","href":"/reference/cli/auth-exchange-circleci-token"},{"title":"nsc auth trust-aws-cognito-identity-pool","href":"/reference/cli/auth-trust-aws-cognito-identity-pool"},{"title":"nsc auth trust-relationships","href":"/reference/cli/auth-trust-relationships"},{"title":"nsc auth trust-relationships list","href":"/reference/cli/auth-trust-relationships-list"},{"title":"nsc auth trust-relationships add","href":"/reference/cli/auth-trust-relationships-add"},{"title":"nsc auth trust-relationships update","href":"/reference/cli/auth-trust-relationships-update"},{"title":"nsc auth trust-relationships remove","href":"/reference/cli/auth-trust-relationships-remove"},{"title":"nsc aws assume-role","href":"/reference/cli/aws-assume-role"}]},{"group":"Base image","icon":"layers","pages":[{"title":"nsc base-image upload","href":"/reference/cli/base-image-upload"},{"title":"nsc base-image optimize","href":"/reference/cli/base-image-optimize"},{"title":"nsc base-image build-github-image","href":"/reference/cli/base-image-build-github-image"}]},{"group":"Bazel","icon":"boxes","pages":[{"title":"nsc bazel create-token","href":"/reference/cli/bazel-create-token"},{"title":"nsc bazel invocation list","href":"/reference/cli/bazel-invocation-list"},{"title":"nsc bazel invocation report","href":"/reference/cli/bazel-invocation-report"},{"title":"nsc bazel setup","description":null,"href":"/reference/cli/bazel-setup"}]},{"group":"Build","icon":"hammer","pages":[{"title":"nsc build","href":"/reference/cli/build"},{"title":"nsc build logs","description":null,"href":"/reference/cli/build-logs"},{"title":"nsc build resolve","href":"/reference/cli/build-resolve"}]},{"group":"Buildkite","icon":"/images/buildkite-agents/buildkite-mark.svg","pages":[{"title":"nsc buildkite queue","href":"/reference/cli/buildkite-queue"},{"title":"nsc buildkite queue list","href":"/reference/cli/buildkite-queue-list"},{"title":"nsc buildkite queue describe","href":"/reference/cli/buildkite-queue-describe"},{"title":"nsc buildkite queue update","href":"/reference/cli/buildkite-queue-update"}]},{"group":"Cache","icon":"database","pages":[{"title":"nsc cache bazel setup","href":"/reference/cli/bazel-cache-setup"},{"title":"nsc cache buck2 setup","href":"/reference/cli/cache-buck2-setup"},{"title":"nsc cache gradle setup","href":"/reference/cli/gradle-cache-setup"},{"title":"nsc cache gradle create-token","href":"/reference/cli/cache-gradle-create-token"},{"title":"nsc cache pants setup","href":"/reference/cli/pants-cache-setup"},{"title":"nsc cache sccache setup","href":"/reference/cli/sccache-setup"},{"title":"nsc cache sccache create-token","href":"/reference/cli/cache-sccache-create-token"},{"title":"nsc cache turborepo setup","href":"/reference/cli/cache-turborepo-setup"},{"title":"nsc cache turborepo list","href":"/reference/cli/cache-turborepo-list"}]},{"group":"Docker","icon":"container","pages":[{"title":"nsc docker login","href":"/reference/cli/docker-login"},{"title":"nsc docker attach-context","href":"/reference/cli/docker-attach"},{"title":"nsc docker remote","href":"/reference/cli/docker-remote"},{"title":"nsc docker buildx setup","href":"/reference/cli/docker-buildx-setup"},{"title":"nsc docker buildx status","href":"/reference/cli/docker-buildx-status"},{"title":"nsc docker buildx cleanup","href":"/reference/cli/docker-buildx-cleanup"}]},{"group":"Egress","icon":"shield","pages":[{"title":"nsc egress policy list","href":"/reference/cli/egress-policy-list"},{"title":"nsc egress policy describe","href":"/reference/cli/egress-policy-describe"},{"title":"nsc egress policy create","href":"/reference/cli/egress-policy-create"},{"title":"nsc egress policy update","href":"/reference/cli/egress-policy-update"},{"title":"nsc egress logs","href":"/reference/cli/egress-logs"}]},{"group":"Expose","icon":"radio-tower","pages":[{"title":"nsc expose container","href":"/reference/cli/expose"},{"title":"nsc expose kubernetes","href":"/reference/cli/expose-kubernetes"}]},{"group":"Git checkout","icon":"git-branch","pages":[{"title":"nsc git-checkout update-submodules","href":"/reference/cli/update-submodules"}]},{"group":"GitHub","icon":"github","pages":[{"title":"nsc github profile","href":"/reference/cli/github-profile"},{"title":"nsc github profile create","href":"/reference/cli/github-profile-create"},{"title":"nsc github profile list","href":"/reference/cli/github-profile-list"},{"title":"nsc github profile describe","href":"/reference/cli/github-profile-describe"},{"title":"nsc github profile update","href":"/reference/cli/github-profile-update"},{"title":"nsc github profile delete","href":"/reference/cli/github-profile-delete"},{"title":"nsc github profile test-build-base-image","href":"/reference/cli/github-profile-test-build-base-image"},{"title":"nsc github profile rebuild-base-image","href":"/reference/cli/github-profile-rebuild-base-image"},{"title":"nsc github base-image list","href":"/reference/cli/github-base-image-list"},{"title":"nsc github base-image describe","href":"/reference/cli/github-base-image-describe"},{"title":"nsc github job list","href":"/reference/cli/github-job-list"},{"title":"nsc github job describe","href":"/reference/cli/github-job-describe"}]},{"group":"Ingress","icon":"network","pages":[{"title":"nsc ingress list","href":"/reference/cli/ingress-list"},{"title":"nsc ingress generate-access-token","href":"/reference/cli/ingress-generate-access-token"}]},{"group":"Instance","icon":"server","pages":[{"title":"nsc instance history","href":"/reference/cli/instance-history"},{"title":"nsc instance report","href":"/reference/cli/instance-report"},{"title":"nsc instance metadata read","href":"/reference/cli/instance-metadata"},{"title":"nsc instance port-forward","href":"/reference/cli/instance-port-forward"},{"title":"nsc instance download","href":"/reference/cli/instance-download"},{"title":"nsc instance upload","href":"/reference/cli/instance-upload"}]},{"group":"Integrations","icon":"plug","pages":[{"title":"nsc integrations tailscale list","href":"/reference/cli/integrations-tailscale-list"},{"title":"nsc integrations tailscale set","href":"/reference/cli/integrations-tailscale-set"},{"title":"nsc integrations tailscale remove","href":"/reference/cli/integrations-tailscale-remove"}]},{"group":"Kubeconfig","icon":"file-key","pages":[{"title":"nsc kubeconfig write","href":"/reference/cli/kubeconfig-write"}]},{"group":"Registry","icon":"archive","pages":[{"title":"nsc registry list","href":"/reference/cli/registry-list"},{"title":"nsc registry describe","href":"/reference/cli/registry-describe"},{"title":"nsc registry share","href":"/reference/cli/registry-share"},{"title":"nsc registry update-image-expiration","href":"/reference/cli/registry-update-image-expiration"},{"title":"nsc registry default-expiration","href":"/reference/cli/registry-default-expiration"},{"title":"nsc registry policy","href":"/reference/cli/registry-policy"},{"title":"nsc registry policy get","href":"/reference/cli/registry-policy-get"},{"title":"nsc registry policy set","href":"/reference/cli/registry-policy-set"}]},{"group":"Reservation","icon":"calendar-clock","pages":[{"title":"nsc reservation list","href":"/reference/cli/reservation-list"},{"title":"nsc reservation describe","href":"/reference/cli/reservation-describe"},{"title":"nsc reservation wait","href":"/reference/cli/reservation-wait"},{"title":"nsc reservation cancel","href":"/reference/cli/reservation-cancel"}]},{"group":"Token","icon":"key","pages":[{"title":"nsc token create","href":"/reference/cli/token-create"},{"title":"nsc token list","href":"/reference/cli/token-list"},{"title":"nsc token refresh","href":"/reference/cli/token-refresh"},{"title":"nsc token revoke","href":"/reference/cli/token-revoke"}]},{"group":"Vault","icon":"lock-keyhole","pages":[{"title":"nsc vault list","href":"/reference/cli/vault-list"},{"title":"nsc vault add","href":"/reference/cli/vault-add"},{"title":"nsc vault set","href":"/reference/cli/vault-set"},{"title":"nsc vault delete","href":"/reference/cli/vault-delete"},{"title":"nsc vault export","href":"/reference/cli/vault-export"}]},{"group":"Version","icon":"badge-info","pages":[{"title":"nsc version","href":"/reference/cli/version"},{"title":"nsc version check","href":"/reference/cli/version-check"},{"title":"nsc version ensure","href":"/reference/cli/version-ensure"},{"title":"nsc version update","href":"/reference/cli/version-update"}]},{"group":"Volume","icon":"hard-drive","pages":[{"title":"nsc volume list","href":"/reference/cli/volume-list"},{"title":"nsc volume release","href":"/reference/cli/volume-release"}]}]},{"group":"Devbox CLI","icon":"square-terminal","expanded":false,"pages":[{"group":"Setup","icon":"wrench","expanded":false,"pages":[{"title":"Installation","href":"/reference/devbox-cli/installation"},{"title":"Agent Skills","href":"/reference/devbox-cli/agent-skills"},{"title":"devbox auth","sidebarTitle":"auth","href":"/reference/devbox-cli/auth"},{"title":"devbox update","sidebarTitle":"update","href":"/reference/devbox-cli/update"},{"title":"devbox version","sidebarTitle":"version","href":"/reference/devbox-cli/version"},{"title":"devbox completion","sidebarTitle":"completion","href":"/reference/devbox-cli/completion"},{"title":"devbox site-latency","sidebarTitle":"site-latency","href":"/reference/devbox-cli/site-latency"}]},{"group":"Manage Devboxes","icon":"server","pages":[{"title":"devbox create","sidebarTitle":"create","href":"/reference/devbox-cli/create"},{"title":"Devbox spec file","sidebarTitle":"spec file","href":"/reference/devbox-cli/spec-file"},{"title":"devbox list","sidebarTitle":"list","href":"/reference/devbox-cli/list"},{"title":"devbox stop","sidebarTitle":"stop","href":"/reference/devbox-cli/stop"},{"title":"devbox delete","sidebarTitle":"delete","href":"/reference/devbox-cli/delete"}]},{"group":"Connect and run","icon":"terminal","pages":[{"title":"devbox desktop","sidebarTitle":"desktop","href":"/reference/devbox-cli/desktop"},{"title":"devbox configure-ssh","sidebarTitle":"configure-ssh","href":"/reference/devbox-cli/configure-ssh"},{"title":"devbox ssh","sidebarTitle":"ssh","href":"/reference/devbox-cli/ssh"},{"title":"devbox session","sidebarTitle":"session","href":"/reference/devbox-cli/session"},{"title":"devbox exec","sidebarTitle":"exec","href":"/reference/devbox-cli/exec"},{"title":"devbox logs","sidebarTitle":"logs","href":"/reference/devbox-cli/logs"},{"title":"devbox service","sidebarTitle":"service","href":"/reference/devbox-cli/service"},{"title":"devbox open-ide","sidebarTitle":"open-ide","href":"/reference/devbox-cli/open-ide"}]},{"group":"Ports and URLs","icon":"network","pages":[{"title":"devbox port-forward","sidebarTitle":"port-forward","href":"/reference/devbox-cli/port-forward"},{"title":"devbox url","sidebarTitle":"url","href":"/reference/devbox-cli/url"}]},{"group":"Images","icon":"layers","pages":[{"title":"devbox image build","sidebarTitle":"image build","href":"/reference/devbox-cli/image-build"},{"title":"devbox image wire","sidebarTitle":"image wire","href":"/reference/devbox-cli/image-wire"},{"title":"devbox image list","sidebarTitle":"image list","href":"/reference/devbox-cli/image-list"},{"title":"devbox image describe","sidebarTitle":"image describe","href":"/reference/devbox-cli/image-describe"},{"title":"devbox image optimize","sidebarTitle":"image optimize","href":"/reference/devbox-cli/image-optimize"},{"title":"devbox image expire","sidebarTitle":"image expire","href":"/reference/devbox-cli/image-expire"}]},{"group":"Files","icon":"folder","pages":[{"title":"devbox upload","sidebarTitle":"upload","href":"/reference/devbox-cli/upload"},{"title":"devbox download","sidebarTitle":"download","href":"/reference/devbox-cli/download"}]},{"group":"Devbox pools","icon":"boxes","pages":[{"title":"devbox acquire","sidebarTitle":"acquire","href":"/reference/devbox-cli/acquire"},{"title":"devbox release","sidebarTitle":"release","href":"/reference/devbox-cli/release"}]},{"group":"Integrations","icon":"plug","pages":[{"title":"devbox setup-github","sidebarTitle":"setup-github","href":"/reference/devbox-cli/setup-github"},{"title":"devbox claude managed-agents","sidebarTitle":"claude","href":"/reference/devbox-cli/claude"}]}]}]}]},{"tab":"SDK","icon":"braces","pages":[{"title":"SDK","href":"/reference/sdk"}]},{"tab":"MCP","icon":"plug","pages":[{"title":"MCP","href":"/reference/mcp"}]}]},{"product":"Platform","description":"Lower-level primitives to build your own","pages":[{"title":"Platform","href":"/platform"}]}]},"title":"nsc build - Namespace Documentation","buildId":"dpl_GvhK4qVXq51DpfYJLCtPpYNN4YHN","deploymentId":"dpl_GvhK4qVXq51DpfYJLCtPpYNN4YHN","dynamics":[],"chunks":[]}