# Create cluster Source: https://docs.nscale.com/api-reference/clusters/create-cluster /openapi/nks-openapi.yaml post /api/v1/clusters Create a cluster. # Delete cluster Source: https://docs.nscale.com/api-reference/clusters/delete-cluster /openapi/nks-openapi.yaml delete /api/v1/clusters/{clusterID} Delete a cluster and its node pools. # Get cluster Source: https://docs.nscale.com/api-reference/clusters/get-cluster /openapi/nks-openapi.yaml get /api/v1/clusters/{clusterID} Get a cluster. # List clusters Source: https://docs.nscale.com/api-reference/clusters/list-clusters /openapi/nks-openapi.yaml get /api/v1/clusters List clusters. Results are ordered by exact display name and then by public resource ID. Repeated values within one status filter are combined with OR; different filter classes are combined with AND. # Update cluster Source: https://docs.nscale.com/api-reference/clusters/update-cluster /openapi/nks-openapi.yaml put /api/v1/clusters/{clusterID} Update a cluster. # List file storage classes Source: https://docs.nscale.com/api-reference/file-storage-classes/list-file-storage-classes /openapi/region-openapi.yaml get /api/v2/filestorageclasses List storage classes. # Create file storage Source: https://docs.nscale.com/api-reference/file-storage/create-file-storage /openapi/region-openapi.yaml post /api/v2/filestorage Create a new storage. Snapshot Policies are managed as inline parent File Storage desired state. Omitted or empty spec.snapshotPolicies stores no user-managed policies, and a non-empty list persists exactly the caller-supplied policies. Default Snapshot Protection is controlled separately by spec.defaultSnapshotProtectionEnabled. # Delete file storage Source: https://docs.nscale.com/api-reference/file-storage/delete-file-storage /openapi/region-openapi.yaml delete /api/v2/filestorage/{filestorageID} Delete a storage. # Get file storage Source: https://docs.nscale.com/api-reference/file-storage/get-file-storage /openapi/region-openapi.yaml get /api/v2/filestorage/{filestorageID} Get all storage information this ID. # List file storage Source: https://docs.nscale.com/api-reference/file-storage/list-file-storage /openapi/region-openapi.yaml get /api/v2/filestorage List storage for project. # Update file storage Source: https://docs.nscale.com/api-reference/file-storage/update-file-storage /openapi/region-openapi.yaml put /api/v2/filestorage/{filestorageID} Update this storage. Snapshot Policies are managed as inline parent File Storage desired state. Omitted spec.snapshotPolicies preserves existing user-managed policies, an empty list clears all user-managed policies, and a non-empty list replaces the full user-managed policy list. Default Snapshot Protection is controlled separately by spec.defaultSnapshotProtectionEnabled. # List flavors Source: https://docs.nscale.com/api-reference/flavors/list-flavors /openapi/compute-openapi.yaml get /api/v1/organizations/{organizationID}/regions/{regionID}/flavors Lists all compute compatible flavors that the user has access to. # Create group Source: https://docs.nscale.com/api-reference/groups/create-group /openapi/identity-openapi.yaml post /api/v1/organizations/{organizationID}/groups Allows creation of a new group. # Delete group Source: https://docs.nscale.com/api-reference/groups/delete-group /openapi/identity-openapi.yaml delete /api/v1/organizations/{organizationID}/groups/{groupid} Allows the deletion of an existing group. # Get group Source: https://docs.nscale.com/api-reference/groups/get-group /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/groups/{groupid} Allows a single group to be polled. # List groups Source: https://docs.nscale.com/api-reference/groups/list-groups /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/groups Returns a list of groups that are defined for the organization. # Update group Source: https://docs.nscale.com/api-reference/groups/update-group /openapi/identity-openapi.yaml put /api/v1/organizations/{organizationID}/groups/{groupid} Allows a group to be updated. # Create a compute image from a disk image URL. Source: https://docs.nscale.com/api-reference/images/create-a-compute-image-from-a-disk-image-url /openapi/region-openapi.yaml post /api/v1/organizations/{organizationID}/regions/{regionID}/images Create a compute image from a public URL. Only raw images are supported, other container formats such as qcow2 must be first converted to a raw image. # Delete a compute image. Source: https://docs.nscale.com/api-reference/images/delete-a-compute-image /openapi/region-openapi.yaml delete /api/v1/organizations/{organizationID}/regions/{regionID}/images/{imageID} # List compute disk images Source: https://docs.nscale.com/api-reference/images/list-compute-disk-images /openapi/region-openapi.yaml get /api/v2/regions/{regionID}/images # List images Source: https://docs.nscale.com/api-reference/images/list-images /openapi/compute-openapi.yaml get /api/v1/organizations/{organizationID}/regions/{regionID}/images Lists all compute compatible images that the user has access to. # Create chat completion Source: https://docs.nscale.com/api-reference/inference/create-chat-completion /openapi/serverless-openapi.yaml post /v1/chat/completions Generates a chat completion response for the provided model and chat history. # Create completion Source: https://docs.nscale.com/api-reference/inference/create-completion /openapi/serverless-openapi.yaml post /v1/completions Generates a completion response for the provided model and prompt. # Create embeddings Source: https://docs.nscale.com/api-reference/inference/create-embeddings /openapi/serverless-openapi.yaml post /v1/embeddings Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. # Create image Source: https://docs.nscale.com/api-reference/inference/create-image /openapi/serverless-openapi.yaml post /v1/images/generations Creates an image based on the provided text prompt. # Create instance Source: https://docs.nscale.com/api-reference/instances/create-instance /openapi/compute-openapi.yaml post /api/v2/instances Create an instance. # Delete instance Source: https://docs.nscale.com/api-reference/instances/delete-instance /openapi/compute-openapi.yaml delete /api/v2/instances/{instanceID} Delete an instance. # Get instance Source: https://docs.nscale.com/api-reference/instances/get-instance /openapi/compute-openapi.yaml get /api/v2/instances/{instanceID} Get an instance. # Get instance console output Source: https://docs.nscale.com/api-reference/instances/get-instance-console-output /openapi/compute-openapi.yaml get /api/v2/instances/{instanceID}/consoleoutput Get the console output for an instance. # Get instance console VNC Source: https://docs.nscale.com/api-reference/instances/get-instance-console-vnc /openapi/compute-openapi.yaml get /api/v2/instances/{instanceID}/consolesession Create a new console session for an instance. # Get instance SSH key Source: https://docs.nscale.com/api-reference/instances/get-instance-ssh-key /openapi/compute-openapi.yaml get /api/v2/instances/{instanceID}/sshkey Retrieve the SSH key for an instance. # List instances Source: https://docs.nscale.com/api-reference/instances/list-instances /openapi/compute-openapi.yaml get /api/v2/instances List compute instances. # Reboot instance Source: https://docs.nscale.com/api-reference/instances/reboot-instance /openapi/compute-openapi.yaml post /api/v2/instances/{instanceID}/reboot Reboot an instance. By default this will perform a software ACPI reboot. You can specifiy a hard power cycle as a query parameter. # Snapshot instance Source: https://docs.nscale.com/api-reference/instances/snapshot-instance /openapi/compute-openapi.yaml post /api/v2/instances/{instanceID}/snapshot Take a snapshot of an instance and create an image from it. # Start instance Source: https://docs.nscale.com/api-reference/instances/start-instance /openapi/compute-openapi.yaml post /api/v2/instances/{instanceID}/start Start a stopped instance. # Stop instance Source: https://docs.nscale.com/api-reference/instances/stop-instance /openapi/compute-openapi.yaml post /api/v2/instances/{instanceID}/stop Stop a running instnace. # Update instance Source: https://docs.nscale.com/api-reference/instances/update-instance /openapi/compute-openapi.yaml put /api/v2/instances/{instanceID} Update an instance. # Create load balancer Source: https://docs.nscale.com/api-reference/load-balancers/create-load-balancer /openapi/region-openapi.yaml post /api/v2/loadbalancers Create a new load balancer. # Delete load balancer Source: https://docs.nscale.com/api-reference/load-balancers/delete-load-balancer /openapi/region-openapi.yaml delete /api/v2/loadbalancers/{loadBalancerID} Delete a load balancer. # Get load balancer Source: https://docs.nscale.com/api-reference/load-balancers/get-load-balancer /openapi/region-openapi.yaml get /api/v2/loadbalancers/{loadBalancerID} Get a load balancer. # List load balancers Source: https://docs.nscale.com/api-reference/load-balancers/list-load-balancers /openapi/region-openapi.yaml get /api/v2/loadbalancers List load balancers. # Update load balancer Source: https://docs.nscale.com/api-reference/load-balancers/update-load-balancer /openapi/region-openapi.yaml put /api/v2/loadbalancers/{loadBalancerID} Update a load balancer. # List endpoints Source: https://docs.nscale.com/api-reference/models/list-endpoints /openapi/serverless-openapi.yaml get /organizations/{organization_id}/endpoints Returns a list of all model endpoints that are available for use by the specified organization. Includes details like pricing as decimal USD, model information, and last usage. # List models Source: https://docs.nscale.com/api-reference/models/list-models /openapi/serverless-openapi.yaml get /v1/models Returns a list of models available for the specified organization. # Create network Source: https://docs.nscale.com/api-reference/networks/create-network /openapi/region-openapi.yaml post /api/v2/networks Create a new network. # Delete network Source: https://docs.nscale.com/api-reference/networks/delete-network /openapi/region-openapi.yaml delete /api/v2/networks/{networkID} Delete a network. # Get network Source: https://docs.nscale.com/api-reference/networks/get-network /openapi/region-openapi.yaml get /api/v2/networks/{networkID} Get a network. # List networks Source: https://docs.nscale.com/api-reference/networks/list-networks /openapi/region-openapi.yaml get /api/v2/networks List networks. # Update network Source: https://docs.nscale.com/api-reference/networks/update-network /openapi/region-openapi.yaml put /api/v2/networks/{networkID} Update a network's mutable fields. # Create node pool Source: https://docs.nscale.com/api-reference/node-pools/create-node-pool /openapi/nks-openapi.yaml post /api/v1/nodepools Create a node pool. # Delete node pool Source: https://docs.nscale.com/api-reference/node-pools/delete-node-pool /openapi/nks-openapi.yaml delete /api/v1/nodepools/{nodePoolID} Delete a node pool. # Get node pool Source: https://docs.nscale.com/api-reference/node-pools/get-node-pool /openapi/nks-openapi.yaml get /api/v1/nodepools/{nodePoolID} Get a node pool. # List node pools Source: https://docs.nscale.com/api-reference/node-pools/list-node-pools /openapi/nks-openapi.yaml get /api/v1/nodepools List node pools. Results are ordered by exact display name and then by public resource ID. Repeated values within one status filter are combined with OR; different filter classes are combined with AND. # Update node pool Source: https://docs.nscale.com/api-reference/node-pools/update-node-pool /openapi/nks-openapi.yaml put /api/v1/nodepools/{nodePoolID} Update a node pool. # Create endpoint Source: https://docs.nscale.com/api-reference/object-storage/create-endpoint /openapi/storage-openapi.yaml post /api/v1/objectstorageendpoints Provisions a new S3-compatible object storage endpoint in the requested organization, project, and region using the selected immutable endpoint class. Access keys are managed through dedicated APIs, and identity policies are managed as part of the endpoint specification. # Create endpoint access key Source: https://docs.nscale.com/api-reference/object-storage/create-endpoint-access-key /openapi/storage-openapi.yaml post /api/v1/objectstorageendpoints/{objectStorageEndpointID}/accesskeys Creates an access key for the specified object storage endpoint. The server generates the immutable access key identifier and secret. The secret is returned only once in the create response. # Delete endpoint Source: https://docs.nscale.com/api-reference/object-storage/delete-endpoint /openapi/storage-openapi.yaml delete /api/v1/objectstorageendpoints/{objectStorageEndpointID} Deletes the object storage endpoint and any endpoint-level resources managed with it (including any buckets created through the endpoint). # Delete endpoint access key Source: https://docs.nscale.com/api-reference/object-storage/delete-endpoint-access-key /openapi/storage-openapi.yaml delete /api/v1/objectstorageendpoints/{objectStorageEndpointID}/accesskeys/{objectStorageAccessKeyID} Deletes the specified access key associated with the specified object storage endpoint. # Get endpoint Source: https://docs.nscale.com/api-reference/object-storage/get-endpoint /openapi/storage-openapi.yaml get /api/v1/objectstorageendpoints/{objectStorageEndpointID} Returns a single object storage endpoint, including its class selection, configured identity policies, and any exposure details that have been provisioned. # Get endpoint access key Source: https://docs.nscale.com/api-reference/object-storage/get-endpoint-access-key /openapi/storage-openapi.yaml get /api/v1/objectstorageendpoints/{objectStorageEndpointID}/accesskeys/{objectStorageAccessKeyID} Returns the specified access key associated with the specified object storage endpoint. The response includes the access key identifier and identity policy name, but never the secret. # List endpoint access keys Source: https://docs.nscale.com/api-reference/object-storage/list-endpoint-access-keys /openapi/storage-openapi.yaml get /api/v1/objectstorageendpoints/{objectStorageEndpointID}/accesskeys Returns the access keys associated with the specified object storage endpoint. Each access key includes only its identity policy name and access key identifier. # List endpoint classes Source: https://docs.nscale.com/api-reference/object-storage/list-endpoint-classes /openapi/storage-openapi.yaml get /api/v1/objectstorageendpointclasses List the available object storage endpoint classes, including supported exposure types and regional availability. # List endpoints Source: https://docs.nscale.com/api-reference/object-storage/list-endpoints /openapi/storage-openapi.yaml get /api/v1/objectstorageendpoints List the object storage endpoints with optional filtering by tag, organization, project, and region. # Update endpoint Source: https://docs.nscale.com/api-reference/object-storage/update-endpoint /openapi/storage-openapi.yaml put /api/v1/objectstorageendpoints/{objectStorageEndpointID} Updates the endpoint metadata and, optionally, replaces the full set of configured identity policies. The selected endpoint class remains immutable after creation. # Get organization Source: https://docs.nscale.com/api-reference/organizations/get-organization /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID} Get an organization. # List organizations Source: https://docs.nscale.com/api-reference/organizations/list-organizations /openapi/identity-openapi.yaml get /api/v1/organizations Returns a list of organizations that the user is a member of. If an email address is provided in the query this allows a user with sufficient privilege to check if a given user is a member of any organizations. # Update organization Source: https://docs.nscale.com/api-reference/organizations/update-organization /openapi/identity-openapi.yaml put /api/v1/organizations/{organizationID} Update an organization. # Get placement server Source: https://docs.nscale.com/api-reference/placement-servers/get-placement-server /openapi/reservation-openapi.yaml get /api/v2/placements/{placementID}/servers/{serverID} Get a placement server. # List placement servers Source: https://docs.nscale.com/api-reference/placement-servers/list-placement-servers /openapi/reservation-openapi.yaml get /api/v2/placements/{placementID}/servers List placement servers. # Reboot placement server Source: https://docs.nscale.com/api-reference/placement-servers/reboot-placement-server /openapi/reservation-openapi.yaml post /api/v2/placements/{placementID}/servers/{serverID}/reboot Reboot a placement server. # Stop placement server Source: https://docs.nscale.com/api-reference/placement-servers/stop-placement-server /openapi/reservation-openapi.yaml post /api/v2/placements/{placementID}/servers/{serverID}/stop Stop a placement server. # Create placement Source: https://docs.nscale.com/api-reference/placements/create-placement /openapi/reservation-openapi.yaml post /api/v2/placements Create a placement. # Delete placement Source: https://docs.nscale.com/api-reference/placements/delete-placement /openapi/reservation-openapi.yaml delete /api/v2/placements/{placementID} Delete a placement and all Region servers created for it. # Get placement Source: https://docs.nscale.com/api-reference/placements/get-placement /openapi/reservation-openapi.yaml get /api/v2/placements/{placementID} Get a placement. # List placements Source: https://docs.nscale.com/api-reference/placements/list-placements /openapi/reservation-openapi.yaml get /api/v2/placements List placements. # Get platform release Source: https://docs.nscale.com/api-reference/platform-releases/get-platform-release /openapi/nks-openapi.yaml get /api/v1/platformreleases/{releaseID} Get a platform release. # List platform releases Source: https://docs.nscale.com/api-reference/platform-releases/list-platform-releases /openapi/nks-openapi.yaml get /api/v1/platformreleases List platform releases. # Create project Source: https://docs.nscale.com/api-reference/projects/create-project /openapi/identity-openapi.yaml post /api/v1/organizations/{organizationID}/projects Creates a new project resource for the user's organization. # Delete project Source: https://docs.nscale.com/api-reference/projects/delete-project /openapi/identity-openapi.yaml delete /api/v1/organizations/{organizationID}/projects/{projectID} Deletes the project associated with the authenticated user's scoped authorization token. This is a cascading operation and will delete all contained cluster managers and clusters. # Get project Source: https://docs.nscale.com/api-reference/projects/get-project /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/projects/{projectID} Gets a project. # List projects Source: https://docs.nscale.com/api-reference/projects/list-projects /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/projects List all projects for the organization. # Update project Source: https://docs.nscale.com/api-reference/projects/update-project /openapi/identity-openapi.yaml put /api/v1/organizations/{organizationID}/projects/{projectID} Updates a project. # List quotas Source: https://docs.nscale.com/api-reference/quotas/list-quotas /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/quotas Gets quotas for the organization. # List regions Source: https://docs.nscale.com/api-reference/regions/list-regions /openapi/compute-openapi.yaml get /api/v1/organizations/{organizationID}/regions Lists compute service compatible regions. # List reservation units Source: https://docs.nscale.com/api-reference/reservation-units/list-reservation-units /openapi/reservation-openapi.yaml get /api/v2/reservation-units List reservation units. # Create reservation Source: https://docs.nscale.com/api-reference/reservations/create-reservation /openapi/reservation-openapi.yaml post /api/v2/reservations Create a reservation. # Delete reservation Source: https://docs.nscale.com/api-reference/reservations/delete-reservation /openapi/reservation-openapi.yaml delete /api/v2/reservations/{reservationID} Delete a reservation and all placements allocated from it. # Get reservation Source: https://docs.nscale.com/api-reference/reservations/get-reservation /openapi/reservation-openapi.yaml get /api/v2/reservations/{reservationID} Get a reservation. # List reservations Source: https://docs.nscale.com/api-reference/reservations/list-reservations /openapi/reservation-openapi.yaml get /api/v2/reservations List reservations. # List roles Source: https://docs.nscale.com/api-reference/roles/list-roles /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/roles Returns roles that can be used by the organization. # Create security group Source: https://docs.nscale.com/api-reference/security-groups/create-security-group /openapi/region-openapi.yaml post /api/v2/securitygroups Create a new security group. # Delete security group Source: https://docs.nscale.com/api-reference/security-groups/delete-security-group /openapi/region-openapi.yaml delete /api/v2/securitygroups/{securityGroupID} Delete a security groups. # Get security group Source: https://docs.nscale.com/api-reference/security-groups/get-security-group /openapi/region-openapi.yaml get /api/v2/securitygroups/{securityGroupID} Get a security group. # List security groups Source: https://docs.nscale.com/api-reference/security-groups/list-security-groups /openapi/region-openapi.yaml get /api/v2/securitygroups List security groups. # Update security group Source: https://docs.nscale.com/api-reference/security-groups/update-security-group /openapi/region-openapi.yaml put /api/v2/securitygroups/{securityGroupID} Update a security group. # Create service account Source: https://docs.nscale.com/api-reference/service-accounts/create-service-account /openapi/identity-openapi.yaml post /api/v1/organizations/{organizationID}/serviceaccounts Creates a new service account and returns an access token, The returned access token can only be read once. # Delete service account Source: https://docs.nscale.com/api-reference/service-accounts/delete-service-account /openapi/identity-openapi.yaml delete /api/v1/organizations/{organizationID}/serviceaccounts/{serviceAccountID} Removes a service account and revokes an access token. # List service accounts Source: https://docs.nscale.com/api-reference/service-accounts/list-service-accounts /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/serviceaccounts Lists all service accounts. # Rotate service account token Source: https://docs.nscale.com/api-reference/service-accounts/rotate-service-account-token /openapi/identity-openapi.yaml post /api/v1/organizations/{organizationID}/serviceaccounts/{serviceAccountID}/rotate Rotates a service account's access token. The returned access token can only be read once. # Update service account Source: https://docs.nscale.com/api-reference/service-accounts/update-service-account /openapi/identity-openapi.yaml put /api/v1/organizations/{organizationID}/serviceaccounts/{serviceAccountID} Updates a service account. # Create SSH certificate authority Source: https://docs.nscale.com/api-reference/ssh-certificate-authorities/create-ssh-certificate-authority /openapi/region-openapi.yaml post /api/v2/sshcertificateauthorities Create a new SSH certificate authority. # Delete SSH certificate authority Source: https://docs.nscale.com/api-reference/ssh-certificate-authorities/delete-ssh-certificate-authority /openapi/region-openapi.yaml delete /api/v2/sshcertificateauthorities/{sshCertificateAuthorityID} Delete an SSH certificate authority. # Get SSH certificate authority Source: https://docs.nscale.com/api-reference/ssh-certificate-authorities/get-ssh-certificate-authority /openapi/region-openapi.yaml get /api/v2/sshcertificateauthorities/{sshCertificateAuthorityID} Get an SSH certificate authority. # List SSH certificate authorities Source: https://docs.nscale.com/api-reference/ssh-certificate-authorities/list-ssh-certificate-authorities /openapi/region-openapi.yaml get /api/v2/sshcertificateauthorities List SSH certificate authorities. # Create user Source: https://docs.nscale.com/api-reference/users/create-user /openapi/identity-openapi.yaml post /api/v1/organizations/{organizationID}/users Creates a new user and associates with a set of groups. # Delete user Source: https://docs.nscale.com/api-reference/users/delete-user /openapi/identity-openapi.yaml delete /api/v1/organizations/{organizationID}/users/{userID} Deletes a user and disassociates them with all groups they are a member of. # List users Source: https://docs.nscale.com/api-reference/users/list-users /openapi/identity-openapi.yaml get /api/v1/organizations/{organizationID}/users Lists all users. # Update user Source: https://docs.nscale.com/api-reference/users/update-user /openapi/identity-openapi.yaml put /api/v1/organizations/{organizationID}/users/{userID} Updates a user. # Get the deployed service version Source: https://docs.nscale.com/api-reference/version/get-the-deployed-service-version /openapi/region-openapi.yaml get /api/version Returns the build version stamped into the running binary at release time, allowing clients and CI gates to verify exactly which release is deployed. # List volume classes Source: https://docs.nscale.com/api-reference/volume-classes/list-volume-classes /openapi/region-openapi.yaml get /api/v2/volumeclasses Lists provider-neutral VolumeClasses from Regions visible to the caller. Repeat the regionID query parameter to narrow results to one or more Regions. Missing or inaccessible Regions are omitted, so selectors can produce an empty or partial list. Media and performance caps are returned only when published by the Region. # Create volume Source: https://docs.nscale.com/api-reference/volumes/create-volume /openapi/region-openapi.yaml post /api/v2/volumes Create a volume on the Region and project implied by its Network. The VolumeClass and requested capacity are immutable after creation. # Delete volume Source: https://docs.nscale.com/api-reference/volumes/delete-volume /openapi/region-openapi.yaml delete /api/v2/volumes/{volumeID} Delete a volume. A volume in use must be detached before deletion. # Get volume Source: https://docs.nscale.com/api-reference/volumes/get-volume /openapi/region-openapi.yaml get /api/v2/volumes/{volumeID} Get a volume, including its desired capacity and provider-observed state. # List volumes Source: https://docs.nscale.com/api-reference/volumes/list-volumes /openapi/region-openapi.yaml get /api/v2/volumes List volumes visible to the caller, optionally narrowed by scope, Region, or Network. # Update volume Source: https://docs.nscale.com/api-reference/volumes/update-volume /openapi/region-openapi.yaml put /api/v2/volumes/{volumeID} Update a volume's mutable metadata and tags. # Changelog Source: https://docs.nscale.com/changelog/changelog News and improvements from the Nscale team. **January 2026** ## Quick Search & Navigation Refresh A major overhaul of the console's command palette and navigation experience. The Quick Search dialog now supports multi-page flows, improved resource discovery, and an integrated theme switcher—all accessible via Cmd+K. ## Features * **Unified create actions.** All resource creation flows are now accessible directly from the Cmd+K quick search * **Enhanced Quick Search.** Multi-page flow with improved resource search and theme switcher built in * **Duplicate-name validation.** Prevents naming conflicts across projects, VPCs, security groups, filesystems, and images * **Batch instance creation.** Create multiple instances at once with public IP toggle support * **Image snapshots.** Create image snapshots directly from instance detail views * **Filesystem improvements.** VPC multi-select in creation/editing with improved UI * **Navigation updates.** New tabs across serverless details, usage & billing, Kubernetes details, fine-tuning overview, and project compute clusters * **Security groups.** Add actions in instance view with rule side panel for create/edit * **Jobs enhancements.** Parameters field on create with AI summary/diagnosis for failed jobs * **Dashboard quotas.** Private dashboard now displays available quotas ## Nscale CLI * **Device CLI login.** New device authentication flow with refresh token and expires-at fields **December 2025** ## Instances & Networking MVP The console now includes a complete instances and networking workflow. Create and manage instances with full security group support, storage side panels, and quota visibility. ## Features * **Instances + networking MVP.** Full instance actions and security group management * **Storage create side panel.** Streamlined storage creation with improved details view * **Quota callout.** Clear visibility into resource quotas * **Instance create polish.** Refined instance creation flow and UI improvements * **Device status.** Updated device status display **November 2025** ## Instances v2 & UI Refresh A comprehensive refresh of the console UI alongside the new Instances v2 experience. New list and detail views, storage cards, usage visualisation, and a broad refresh of core components. ## Features * **Instance list & detail views.** New views with create image side panel * **Storage details cards.** Improved storage details page with card layout * **Usage visualisation.** New bar chart for usage metrics * **UI component refresh.** Updated form components, drawers, card tables, and tooltips * **Instances v2.** List pages for supporting resources * **API keys removed.** API key management moved out of console * **Workbench polish.** UI improvements to the Workbench experience * **Design system alignment.** Button styling aligned to design system **October 2025** ## Dedicated Infrastructure & Workbench Upgrades New dedicated infrastructure nodes addon and significant Workbench improvements including model selection fixes, preset rules, and comparison-mode enhancements. ## Features * **Dedicated infrastructure nodes.** New addon for dedicated infrastructure * **Workbench upgrades.** Model selection/validation fixes, preset rules, comparison-mode improvements, and license display * **Job status handling.** Improved job completion status handling * **Workload pool IPs.** Machine IP display and copy improvements * **Region validation.** Region change validation fixes * **Image selector.** Improved image selection experience * **Preset baseline.** Now updates to current version automatically **July 2025** ## Serverless Fine-tuning ![Serverless Fine-tuning](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/fine-tuning2x.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=ef8fbd87be15ffaa2b86ed2c5c529fcc) Introducing Serverless Fine-tuning – the fastest way to customise open-weight foundation models without touching infrastructure. Spin up a secure, pay-as-you-go training job in a single API call, watch metrics stream in real-time, and download your tuned model or push straight to Hugging Face. ## Features * **Two-step workflow.** Pick any supported base model (Llama 3, Mistral 7B, DeepSeek, Qwen and more) and launch a job with your dataset – no cluster sizing, no Dockerfiles * **LoRA-powered efficiency.** Default Low-Rank-Adaptation (LoRA) reduces GPU hours and cost * **Live metrics & easy monitoring.** Poll one endpoint to track train\_loss, eval\_loss, perplexity * **Export or deploy instantly.** One-click push to Hugging Face or direct download of a ready-to-serve artefact * **Serverless pricing.** \$2 minimum per job, billed by processed tokens; every new account still gets \$5 free credit to experiment ## Quick start ```bash theme={null} # 1. List available base models curl -H "Authorization: Bearer $NSCALE_API_TOKEN" \ https://fine-tuning.api.nscale.com/api/v1/organizations/$ORG_ID/base-models # 2. Launch a LoRA job curl -X POST https://fine-tuning.api.nscale.com/api/v1/organizations/$ORG_ID/jobs \ -H "Authorization: Bearer $NSCALE_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "support-bot-finetune", "base_model_id": "e5f6a7b8-c9d0-1234-efab-567890123456", "dataset": {"id":"","prompt_column":"prompt","answer_column":"response"}, "hyperparameters":{"n_epochs":3,"batch_size":4,"lora":{"enabled":true,"r":8,"alpha":16}} }' # 3. Stream training metrics curl -H "Authorization: Bearer $NSCALE_API_TOKEN" \ https://fine-tuning.api.nscale.com/api/v1/organizations/$ORG_ID/jobs/$JOB_ID/metrics ``` **March 2025** ## Serverless Inference ![Serverless Inference](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/serverless-inference2x.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=0f5f913d1c839c3face1019fee6b00c1) Our fully-managed, pay-per-request runtime that puts a pool of GPUs behind a single OpenAI-compatible endpoint. Instead of capacity planning, container images and infra dashboards, you call `https://inference.api.nscale.com/v1/*` and get deterministic, low-latency responses from today’s best open-source models—all billed per token and delivered from data-sovereign, 100% renewable data-centres. ## Features * **OpenAI-compatible endpoints.** Drop-in support for Llama, Qwen, DeepSeek and other leading models makes migration a copy-paste job * **Pay-as-you-go billing.** Prices are per 1 million tokens including input and output tokens for Chat, Multimodal, Language and Code models. Image models is based on image size and steps * **80% lower cost & 100% renewable.** Our vertically-integrated stack slashes TCO versus hyperscalers while guaranteeing data privacy—requests are never logged or reused * **\$5 free credits to get started.** Every new account includes starter credits so you can ship to production in minutes ## Under the hood | Area | What it looks like | Why it matters | | - | - | - | | **API surface** | Drop‑in equivalents for `GET /models`, `POST /chat/completions`, `POST /images` with optional `stream: true` for SSE (`text/event-stream`). | Migrate from OpenAI by changing only the base URL and key. | | **Model library** | Launch set covers Meta Llama‑4 Scout 17B, Qwen‑3 235B, Mixtral‑8×22B, DeepSeek‑R1 distills, SD‑XL 1.0 and more (text, code, vision). | Lets teams A/B models or mix modalities without provisioning extra infra. | | **Elastic runtime** | “Zero rate limits, no cold starts.” Traffic is sharded over thousands of MI300X/MI250X/H100 GPUs, spun up on‑demand by our orchestration layer. | Bursty workloads stay \< 200 ms tail latency without you over‑allocating GPUs. | | **Cost model** | Tokens in, tokens out — billed per 1M tokens; images billed per megapixel. Every account starts with \$5 free credit. | Fine‑grained, deterministic spend; easy to embed in metered SaaS. | | **Security / privacy** | End‑to‑end TLS, org‑scoped API keys, full tenant isolation; we never log or train on user prompts or outputs. | Meets GDPR, HIPAA and most vendor‑assessment checklists out of the box. | | **Sustainability** | All compute runs in hydro‑powered facilities; the vertical stack is 80% cheaper‑per‑token than hyperscalers. | Fewer carbon (and budget) emissions per request. | ## Quick start ```bash theme={null} curl -X POST \ https://inference.api.nscale.com/v1/chat/completions \ -H "Authorization: Bearer $NSCALE_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "meta-llama/Llama-4-Scout-17B-Instruct", "messages": [{"role":"user","content":"Hello world"}], "stream": true }' ``` # Evaluations (coming soon) Source: https://docs.nscale.com/docs/ai-services/evaluations Coming soon ## **Measure, compare, and optimise your AI models** Understanding model performance is key to building reliable AI applications. With Nscale’s upcoming **Evaluation** service, you’ll be able to test, benchmark, and compare models against industry-standard metrics, ensuring optimal results for your use case. ## **What to expect** * **Automated benchmarks** – Evaluate models using predefined or custom datasets. * **Compare performance** – Test different models side by side for accuracy, latency, and cost efficiency. * **Optimisation insights** – Identify areas for improvement and fine-tune models accordingly. # Serverless models Source: https://docs.nscale.com/docs/ai-services/models Explore the models currently available for serverless inference, ready to deploy instantly for chat, vision, embeddings and image generation. > [!WARNING] > > **Upcoming model retirements** > > We're upgrading our serverless inference service with newer, more capable models from 26 October 2026. To keep your application running smoothly, switch to an alternative model by 2 November 2026. [See the affected models](#upcoming-model-retirements). Our model list is available in the Nscale Console under **AI Services → Models**, or on [our website ](https://www.nscale.com/product/serverless). You can also programmatically access model information including pricing and context length through the [/v1/models API endpoint](/api-reference/models/list-models). > [!TIP] > > Try out some of the examples from the Use Cases documentation: > > * [Chat](/docs/use-cases/chat) > * [Image Generation](/docs/use-cases/image-generation) ## New models These models are now available for serverless inference. Prices are in USD per 1 million tokens. | Model | Author | Input price | Output price | | - | - | - | - | | GLM 5.3 | Z.ai | \$1.40 | \$4.40 | | Qwen3.8-27B | Qwen | \$0.20 | \$2.50 | | Qwen3.8-Flash-Next-FP8 | Qwen | \$0.15 | \$0.47 | Find them in the Nscale Console under **AI Services → Models**. ## Upcoming model retirements Switch to an alternative model by 2 November 2026. ### Recommended model upgrades | Existing model | Author | Recommended upgrade | | - | - | - | | `gpt-oss-20b` | OpenAI | GLM 5.3 | | `gpt-oss-120b` | OpenAI | GLM 5.3 | | `Llama-3.1-8B-Instruct` | Meta | Qwen3.8-27B | | `Llama-4-Scout-17B-16E-Instruct` | Meta | Qwen3.8-27B | | `Qwen2.5-Coder-32B-Instruct` | Qwen | Qwen3.8-27B | | `Qwen3-4B-Instruct-2507` | Qwen | Qwen3.8-27B | | `Qwen3-8B` | Qwen | Qwen3.8-27B | | `Qwen3-14B` | Qwen | Qwen3.8-27B | | `Qwen3-32B` | Qwen | Qwen3.8-27B | | `Qwen3-235B-A22B-Instruct-2507` | Qwen | Qwen3.8-Flash-Next | The upgraded models support tool calling. `Qwen3-Embedding-8B` isn't affected and remains available. ### Other models retiring between 2-4 November 2026 | Model | Author | | - | - | | `DeepSeek-R1-Distill-Llama-8B` | DeepSeek | | `DeepSeek-R1-Distill-Qwen-7B` | DeepSeek | | `DeepSeek-R1-Distill-Qwen-14B` | DeepSeek | | `Devstral-Small-2505` | Mistral AI | | `FLUX.1-schnell` | Black Forest Labs | | `Kimi-K2.5` | Moonshot AI | | `Mixtral-8x22B-Instruct-v0.1` | Mistral AI | | `NVIDIA-Nemotron-3-Nano-30B-A3B-BF16` | NVIDIA | | `Qwen2.5-Coder-7B-Instruct` | Qwen | | `Qwen3-4B-Thinking-2507` | Qwen | | `Qwen3-235B-A22B` | Qwen | | `Qwen2.5-Coder-3B-Instruct` | Qwen | Need a model that isn't in our serverless catalog? See [dedicated models](/docs/dedicated-models/deploy-a-model) or [contact support](mailto:helpdesk@nscale.com). > **Looking for a model?** > > We're always reviewing new models to add to our serverless inference platform. Whether you're a researcher, a developer, or just someone with a great idea, > we'd love to hear from you. Let us know what you'd like to see available next. # Workbench Source: https://docs.nscale.com/docs/ai-services/workbench Experiment with models, save and compare presets, and view costs. ## Overview The **Workbench** is the evolution of the Playground. It lets you experiment with models interactively while also giving you tools to **save, manage, and compare presets** for different configurations. A preset captures your selected model, parameters, and system prompt, making it easy to revisit or share specific setups. ![Workbench visual](https://mintcdn.com/nscale/5cvpEeN1jrpcQB9B/images/workbench-visual.png?fit=max\&auto=format\&n=5cvpEeN1jrpcQB9B\&q=85\&s=173df5c3a267cf23a3754d6f23d64121) ## Getting Started When you open Workbench for the first time, you’ll see a **default preset**. This preset comes preloaded with baseline parameters and cannot be deleted. It acts as a reliable reset point whenever you need to start fresh. Before beginning, check that your account has **sufficient credits**, since usage is billed per request. You’ll see costs broken down per input and output token on the preset card (e.g. `$0.1 input / $0.4 output`), and detailed usage will appear after each model response. To create and save your own presets: 1. **Open the parameters panel** on the right-hand side. 2. **Select a model** from the dropdown list. 3. **Adjust parameters** such as temperature, top-p, max tokens, or penalties. 4. **Add a system prompt** if you’d like to guide the model’s behaviour. 5. **Save your preset**: either update the current preset or save as a new one. ## Working with Presets ### Default Preset Every account starts with a **default preset**. This preset provides a baseline configuration so you can begin experimenting immediately. * The default preset cannot be deleted or renamed, and it always remains available as a way to return to the standard model setup. * When you change anything in the default preset — such as parameters, the model, or the system prompt — the default itself is never altered. Instead, you’ll be prompted to **save your changes as a new preset**. * This means your default preset is always preserved, acting as a reliable reset point no matter how many custom presets you create. ### Saving Presets Presets let you store a particular combination of model, parameters, and system prompt so you can return to it later. Whenever you make a change — adjusting a parameter, switching the model, or editing the system prompt — a **Save Preset CTA** will appear at the bottom of the parameters sidebar. This is your indicator that the current preset has been modified but not yet saved. From there, the options differ depending on which preset you started with: * **Default Preset** → You’ll see a single option: **Save Preset**, which will create a **new preset** from your changes while leaving the default untouched. * **Custom Preset** → You’ll see two options: * **Update Preset** → Updates the existing preset with your changes. * **Save As New Preset** → Creates a brand-new preset, leaving the current one unchanged. This workflow makes it clear when you’re updating an existing preset versus creating a new one, while guaranteeing that the default preset is always preserved. ### Comparing Presets Workbench allows you to compare two presets side by side. This is especially useful when you want to evaluate how different parameter settings or prompts affect a model’s output. * You can only compare presets that use the **same model type**. * For example: * Compare two **text-generation presets** using `gpt-4o-mini` — one tuned for creative storytelling (high temperature) and another tuned for concise summaries (low temperature). * Compare two **image-generation presets** with the `stable-diffusion-xl` model — one configured for photorealistic outputs, another for more stylized art. You cannot compare across model types (e.g. text vs image). If you attempt to do so, Workbench will prompt you to select presets of the same type. On smaller screen sizes, comparison mode is unavailable. Increase your screen size to enable it. ### Preset History Preset history allows you to revisit past versions of a preset. Every time you save, a new version is created. * Open the kebab menu and select **View history**. * A panel will display the **current version** and **previous versions**. * Select any past version to load it into the Workbench. * To restore it, press **Save**, which creates a new “current” version from that point. ## Parameters Workbench supports the same parameter controls as Playground: * **Model** – Choose the model you want to work with. * **Temperature** – Controls randomness of outputs. * **Top P** – Nucleus sampling, influences diversity. * **Max Tokens** – Maximum length of the model’s response. * **Presence Penalty** – Encourages the model to introduce new tokens. * **Frequency Penalty** – Reduces repetition of existing tokens. All parameter settings are stored as part of a preset. ## Ready to use the model in your app? Once you’ve tested a preset and are happy with the results, you can easily move to implementation. 1. **Click “View Code”** from the kebab menu on your preset. 2. Choose your preferred client (e.g. cURL, Node.js, Python). 3. Copy the generated snippet. 4. Replace the placeholder `NSCALE_API_KEY` with your **service token** (see Authentication docs). ## Billing Workbench runs entirely on **serverless usage**. * Costs are displayed on each preset card (e.g. `$0.1 input / $0.4 output`). * Per-request token usage and cost appear beneath each model response. * Your account balance and billing information are always visible in the lower-left sidebar. ## Example Workflows * Create a **creative writing preset**: * High temperature, custom system prompt for storytelling, saved as its own configuration. * Create a **coding preset**: * Low temperature, higher max tokens, tuned penalties for accuracy, saved for reuse. * Compare outputs: * Run the same prompt through two presets (e.g. creative vs structured) to see how parameter changes affect results. > **[Contact Support](mailto:helpdesk@nscale.com)** > > Need assistance? Get help from our support team # OpenAPI specs Source: https://docs.nscale.com/docs/api-reference/openapi-specs Browse the OpenAPI spec for every Nscale service. Most service specs are published to [`nscaledev/openapi`](https://github.com/nscaledev/openapi); these links always point at the latest released version. > **[Serverless](https://petstore.swagger.io/?url=https://inference.api.nscale.com/openapi.yaml)** > > Serverless AI inference and model access. > **[Compute](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/compute/latest/openapi.yaml)** > > Provisioning and lifecycle management of Compute instances. > **[Kubernetes (NKS)](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/nks-core/main/openapi.yaml)** > > Kubernetes clusters, node pools, and NKS versions. > **[Identity](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/identity/latest/openapi.yaml)** > > Organizations, users, and access control. > **[Region](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/region/latest/openapi.yaml)** > > Networking and storage resources scoped to a region. > **[Storage](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/storage/latest/openapi.yaml)** > > Object storage endpoints and access keys. > **[Reservation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/reservation/latest/openapi.yaml)** > > GPU capacity reservations and placement. # Contexts Source: https://docs.nscale.com/docs/cli/contexts Manage CLI contexts to switch between organizations and user configurations. Contexts let you store named configurations — including organization, project, region, and user credentials — so you don't need to pass these flags on every command. Contexts are persisted in the user configuration folder. For example, on macOS they are stored in `~/.config/nscale/contexts.yaml`. **Aliases:** `context`, `ctx` ## Subcommands * [set](#set) — Create or update a context * [use](#use) — Set the current active context * [list](#list) — List all contexts * [delete](#delete) — Delete a context * [clear](#clear) — Clear the current context *** ## set Create or update a context with a given name, organization, and user. The `--org`, `--project`, and `--region` flags expect resource IDs, not names. Use `nscale organizations list`, `nscale projects list`, and `nscale regions list` to discover the IDs. Any flag that is omitted will be prompted for interactively. The context name can be passed as a positional argument or with `--name`; passing both is an error unless they match. If you omit it, the CLI prompts for it. ```bash theme={null} nscale contexts set --org [--project ] [--region ] [--user ] ``` ### Flags | Flag | Description | | - | - | | `--name string` | Context name | | `--org string` | Organization ID (global flag) | | `--project string` | Project ID | | `--region string` | Region ID | | `--user string` | Keyring user credentials to use | ### Examples ```bash theme={null} nscale contexts set prod --org --user default --project --region ``` For interactive mode (prompts for all values): ```bash theme={null} nscale contexts set ``` *** ## use Set the current active context. All subsequent commands will use this context unless overridden with `--context`. If you omit the name, the CLI prompts you to pick one of your contexts. ```bash theme={null} nscale contexts use ``` ### Example ```bash theme={null} nscale contexts use prod ``` *** ## list List all configured contexts. The context in effect is marked in the `Active` column. **Aliases:** `list`, `ls` ```bash theme={null} nscale contexts list ``` Contexts are read from local configuration rather than the API, so `list` has no `--json` or `-q` flags. Use the global [`--format`](/docs/cli/overview#output-formats) flag instead. Under `--format json`, each context is a flat object (`name`, `organizationId`, ..., `active`) rather than the usual `metadata`/`spec`/`status` envelope: ```bash theme={null} nscale contexts list --format json ``` *** ## delete Delete a context by name. The CLI asks for confirmation before deleting, and warns you if the context is currently active (deleting it leaves no context active). `delete` has no `--yes` flag, so it needs a terminal to answer the prompt. **Aliases:** `delete`, `rm`, `remove` ```bash theme={null} nscale contexts delete ``` ### Example ```bash theme={null} nscale contexts delete prod ``` *** ## clear Clear the current active context. After clearing, commands will require explicit flags for organization, project, etc. ```bash theme={null} nscale contexts clear ``` # Device authorization Source: https://docs.nscale.com/docs/cli/device-authorization Reference for the OAuth 2.0 device authorization grant flow used by the CLI, including endpoints, timing, and security notes. ## Device authorization reference This section provides detailed technical information about the OAuth 2.0 Device Authorization Grant flow used by the CLI. ### Overview The device flow lets a CLI request authorization while the user completes login in a browser on a secondary device. Nscale follows RFC 8628. The console acts as the OAuth client, so the CLI's requests carry no `client_id`. ```mermaid theme={null} sequenceDiagram participant CLI as CLI (Device) participant API as Console API participant Browser as Browser (User) CLI->>API: POST /api/oauth2/device
{ scope } API-->>CLI: { device_code, user_code,
verification_uri,
expires_in: 600,
interval: 5 } CLI->>Browser: Display verification URI
and user code Browser->>API: GET /auth/device?code=XXXX-YYYY Browser->>API: POST /api/auth/device/verify
{ code } API-->>Browser: { valid: true, scope } Browser->>API: GET /auth/device/callback Note over API: authorizeDevice() stores tokens
in secure session store loop Poll until authorized CLI->>API: POST /api/oauth2/token
{ grant_type: device_code,
device_code } API-->>CLI: authorization_pending / slow_down end API-->>CLI: { access_token, refresh_token,
token_type: "Bearer", expires_in } ``` ### Technical details #### Session storage Device sessions are stored in a secure, server-side key-value store. Sessions are never exposed to the client and are automatically expired. #### Timing | Parameter | Value | Description | | - | - | - | | Session TTL | 600 seconds (10 min) | Time for user to complete authentication | | Token pickup window | 60 seconds | Time for CLI to retrieve token after authorization | | Polling interval | 5 seconds | Minimum interval between polling requests | #### User codes User codes are 8 characters in format `XXXX-YYYY` and use an ambiguity-reduced character set to minimize input errors. ### API endpoints #### 1. Device authorization request **`POST /api/oauth2/device`** Initiates the device authorization flow. Request: ```bash theme={null} curl -X POST https://console.nscale.com/api/oauth2/device \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "scope=openid%20email%20profile" ``` Response: ```json theme={null} { "device_code": "550e8400-e29b-41d4-a716-446655440000", "user_code": "WDJB-MJHT", "verification_uri": "https://console.nscale.com/auth/device", "verification_uri_complete": "https://console.nscale.com/auth/device?code=WDJB-MJHT", "expires_in": 600, "interval": 5 } ``` #### 2. Token endpoint (polling) **`POST /api/oauth2/token`** The CLI polls this endpoint until authorization completes. Request: ```bash theme={null} curl -X POST https://console.nscale.com/api/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=urn:ietf:params:oauth:grant-type:device_code" \ -d "device_code=550e8400-e29b-41d4-a716-446655440000" ``` Responses: | Status | Error code | Meaning | Action | | - | - | - | - | | 400 | `authorization_pending` | User has not completed auth | Wait `interval` seconds, retry | | 400 | `slow_down` | Polling too fast | Increase interval, retry | | 400 | `access_denied` | User denied request | Stop polling, show error | | 400 | `expired_token` | Session expired | Stop polling, restart flow | | 200 | - | Success | Use returned tokens | Success response: ```json theme={null} { "access_token": "eyJ...", "token_type": "Bearer", "refresh_token": "eyJ...", "expires_in": 3599 } ``` #### 3. Token refresh **`POST /api/oauth2/token`** Refresh an expired access token. Request: ```bash theme={null} curl -X POST https://console.nscale.com/api/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=refresh_token" \ -d "refresh_token=" ``` ### Token storage recommendations Store tokens securely using platform-appropriate mechanisms: | Platform | Recommended storage | | - | - | | macOS | Keychain (`security` command or `keytar` npm package) | | Linux | libsecret / GNOME Keyring / encrypted file | | Windows | Windows Credential Manager | Example with keytar: ```typescript theme={null} import * as keytar from "keytar"; const SERVICE_NAME = "nscale-cli"; const ACCOUNT_NAME = "default"; async function storeTokens(tokens: TokenResponse): Promise { await keytar.setPassword( SERVICE_NAME, ACCOUNT_NAME, JSON.stringify({ access_token: tokens.access_token, refresh_token: tokens.refresh_token, expires_at: Date.now() + (tokens.expires_in || 3600) * 1000, }) ); } ``` ### Security considerations #### Device code phishing Attackers can socially engineer users into authorizing malicious device codes. Mitigations include: * Short session TTL (10 minutes) limits attack window. * User sees a consent screen with requested scopes. * Users can deny suspicious requests. * Device flow can be disabled if not required. #### Brute force code guessing Mitigations include high-entropy user codes, short TTLs, and consistent error responses to prevent enumeration. #### Token leakage Mitigations include single-use tokens, short pickup windows (60 seconds), and secure server-side session storage. #### Polling rate abuse Mitigations include server-side rate limiting and the `slow_down` error when polling too fast. ### RFC 8628 compliance Our implementation follows RFC 8628 (OAuth 2.0 Device Authorization Grant): | Requirement | Status | Implementation | | - | - | - | | Device authorization endpoint | Yes | `POST /api/oauth2/device` | | Token endpoint with device\_code grant | Yes | `POST /api/oauth2/token` | | User code display | Yes | 8-character code format `XXXX-YYYY` | | Verification URI | Yes | `/auth/device` | | Verification URI complete | Yes | `/auth/device?code={user_code}` | | expires\_in parameter | Yes | 600 seconds | | interval parameter | Yes | 5 seconds | | authorization\_pending error | Yes | Returned while user authenticating | | slow\_down error | Yes | Returned when polling too fast | | access\_denied error | Yes | Returned when user denies | | expired\_token error | Yes | Returned when session expires | ### References * [RFC 8628 - OAuth 2.0 Device Authorization Grant](https://datatracker.ietf.org/doc/html/rfc8628) # Docs Source: https://docs.nscale.com/docs/cli/docs Print the CLI's own documentation. The CLI carries its own reference documentation, so the full command surface is always available offline and always matches the version you have installed. These commands read nothing from the API, so no authentication or organization is required. ## Subcommands * [reference](#reference) — Print the full command reference as Markdown *** ## reference Print the full command reference as Markdown: every command with its signature, the flags shared across the CLI, the response shapes to expect, and jq recipes for extracting fields. Because everything arrives in a single call, this is the quickest way to keep an offline copy of the reference, or to hand the whole command surface to a coding agent instead of having it walk `--help` one command at a time. ```bash theme={null} nscale docs reference ``` ### Examples ```bash theme={null} # Save the reference to a file nscale docs reference > nscale-reference.md # Page through it in the terminal nscale docs reference | less ``` # File storage Source: https://docs.nscale.com/docs/cli/filestorage Manage file storage resources. **Aliases:** `filestorage`, `fs` Manage [file storage](/docs/storage/file-storage): shared NFS filesystems that instances and Kubernetes clusters on the same network can mount. Every command acts in the organization given by `--org`, or the one saved in your [context](/docs/cli/contexts). Commands that act on one file storage resource take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List file storage resources * [classes](#classes) — List file storage classes * [get](#get) — Get file storage details * [create](#create) — Create a new file storage resource * [update](#update) — Update an existing file storage resource * [delete](#delete) — Delete a file storage resource **Snapshot policies** (aliases: `snapshot-policy`, `sp`) * [snapshot-policy list](#snapshot-policy-list) — List snapshot policies for a file storage resource * [snapshot-policy create](#snapshot-policy-create) — Create a snapshot policy for a file storage resource * [snapshot-policy update](#snapshot-policy-update) — Update a snapshot policy on a file storage resource * [snapshot-policy delete](#snapshot-policy-delete) — Delete a snapshot policy from a file storage resource *** ## list List file storage resources, optionally filtered by project or region. The table shows each resource's ID, name, region, size in GiB, and remote ports. **Remote Ports** is the IP range of the NFS storage endpoints for each network attachment, ready to use as the `remoteports` mount option. It's empty until an attachment has been given a range. ```bash theme={null} nscale filestorage list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage list --region nscale filestorage list --project -q '.[].metadata.id' ``` *** ## classes List the file storage classes you can create file storage in. A class sets the kind of storage and the region it lives in. Pass its ID as `spec.storageClassId` when you [create](#create) a file storage resource. The table shows each class's ID, name, region, supported protocols, and parallelism. ```bash theme={null} nscale filestorage classes [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Region ID (defaults to all regions)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage classes --region nscale filestorage classes --region -q '.[].metadata.id' ``` *** ## get Get details for a file storage resource, including its NFS settings, snapshot policies, and network attachments. Each attachment in `status.attachments` carries its `mountSource`, in `:` format, and its `mountOptions`. ```bash theme={null} nscale filestorage get [flags] ``` ### Flags
FlagDescription
`--id string`File storage ID. Can also be passed as a positional argument
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage get --json nscale filestorage get -q '.status.attachments[].mountSource' ``` *** ## create Create a new file storage resource. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, project, region, size (1 to 1013 GiB), NFS settings, networks to attach, and Default Snapshot Protection. It offers only regions that have a file storage class, and uses the first class it finds in the region you choose. To choose the [class](#classes) yourself or add [snapshot policies](#snapshot-policies), use a file. ```bash theme={null} nscale filestorage create [flags] ``` Example payload: ```json storage.json theme={null} { "metadata": { "name": "shared-data" }, "spec": { "organizationId": "", "projectId": "", "regionId": "", "storageClassId": "", "sizeGiB": 200, "storageType": { "NFS": { "rootSquash": true, "posixAcl": false, "atimeUpdateIntervalSeconds": 0 } }, "attachments": { "networkIds": [""] } } } ``` | Field | Notes | | - | - | | `spec.storageClassId` | A class from the same region. List them with [`classes`](#classes). | | `spec.storageType.NFS` | `rootSquash` is required. `posixAcl` and `atimeUpdateIntervalSeconds` are optional and default to `false` and `0`. See [NFS settings](/docs/storage/file-storage#nfs-settings) for what each does. The CLI rejects an `atime` interval outside the accepted range before sending the request. | | `spec.attachments.networkIds` | Optional. The networks the file storage is mounted from. | | `spec.defaultSnapshotProtectionEnabled` | Optional. Omit it to turn on Default Snapshot Protection, or set `false` to leave it off. | | `spec.snapshotPolicies` | Optional. User-managed [snapshot policies](/docs/storage/file-storage#snapshot-policies), up to 4. | ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage create --file storage.json nscale filestorage create --stdin < storage.json cat storage.json | nscale filestorage create --stdin ``` *** ## update Update an existing file storage resource. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, size, NFS settings, networks, and Default Snapshot Protection, pre-filled from the resource as it stands. The prompts leave snapshot policies unchanged; manage them with the [`snapshot-policy`](#snapshot-policies) commands. A payload takes `metadata` and the `spec` fields from [`create`](#create) except `organizationId`, `projectId`, `regionId`, and `storageClassId`. It replaces the resource's settings, with these exceptions for omitted fields: | Field | When omitted | | - | - | | `spec.storageType.NFS.posixAcl` | Resets to `false` | | `spec.storageType.NFS.atimeUpdateIntervalSeconds` | Resets to `0` | | `spec.defaultSnapshotProtectionEnabled` | Keeps the current setting | | `spec.snapshotPolicies` | Keeps the current policies. Send `[]` to remove them all, or a list to replace them all. | If your payload leaves out `posixAcl` or `atimeUpdateIntervalSeconds` while the resource has them set, the CLI prints a warning on stderr before sending it, including with `--dry-run`. The payload is still sent as written. To keep the current values, start from `nscale filestorage get --json`. ```bash theme={null} nscale filestorage update [flags] ``` ### Flags
FlagDescription
`--id string`File storage ID. Can also be passed as a positional argument
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage update --file storage.json nscale filestorage update --stdin < storage.json cat storage.json | nscale filestorage update --stdin ``` *** ## delete Delete a file storage resource. > [!WARNING] > > Deleting file storage permanently removes all its data and snapshots. This can't be undone. ```bash theme={null} nscale filestorage delete [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | File storage ID. Can also be passed as a positional argument | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale filestorage delete --yes ``` *** ## Snapshot policies Snapshot policies take point-in-time snapshots of a file storage resource on a schedule and keep a set number of them. Each resource can have up to **4** policies. For how schedules and retention work, see [Snapshot policies](/docs/storage/file-storage#snapshot-policies). The `snapshot-policy` commands edit the policies stored on the file storage resource. Each change reads the resource and sends it back with the updated policy list. The rest of the resource is left as it is, including Default Snapshot Protection. Default Snapshot Protection is managed by Nscale and doesn't appear in these commands. `create` and `update` collect the policy through interactive prompts and don't accept a JSON file, so they need a terminal. With `--ci`, they fail. To set policies in a script, send the full `spec.snapshotPolicies` list with [`update`](#update) instead. The prompts ask for: | Prompt | Shown for | Rules | | - | - | - | | **Name** | Every policy | Lowercase letters, numbers, and dashes; at most 19 characters; unique on the resource | | **Frequency** | Every policy | `Hourly`, `Daily`, `Weekly`, or `Monthly` | | **Day of week** | Weekly | `Monday` through `Sunday` | | **Day of month** | Monthly | `1` through `28`, so the policy runs every month | | **Time of day (UTC)** | Daily, weekly, monthly | 24-hour `HH:MM` | | **Latest snapshots to keep** | Every policy | At least `1`. Older snapshots are deleted automatically. | *** ## snapshot-policy list List the snapshot policies on a file storage resource. The table shows each policy's name, frequency, run time, number of snapshots kept, and provisioning status. With `--json` or `-q`, the output is the array of policies from `spec.snapshotPolicies`. Each policy has `name`, `schedule`, and `retention` fields, with no `metadata` wrapper. ```bash theme={null} nscale filestorage snapshot-policy list [flags] ``` ### Flags
FlagDescription
`--id string`File storage ID. Can also be passed as a positional argument
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale filestorage snapshot-policy list nscale fs sp list -q '.[].name' ``` *** ## snapshot-policy create Add a snapshot policy to a file storage resource. The CLI [prompts](#snapshot-policies) for the policy's name, schedule, and retention, then asks you to confirm. It fails if the resource already has 4 policies. On success, the updated file storage resource is printed. ```bash theme={null} nscale filestorage snapshot-policy create [flags] ``` ### Flags
FlagDescription
`--id string`File storage ID. Can also be passed as a positional argument
`--org string`Organization ID
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale filestorage snapshot-policy create ``` *** ## snapshot-policy update Change a snapshot policy's name, schedule, or retention. The CLI [prompts](#snapshot-policies) for each field, pre-filled from the policy as it stands, then asks you to confirm. If you omit `--name`, you pick the policy from a list. Policy names identify policies in the API, so renaming a policy replaces it with a new one. On success, the updated file storage resource is printed. ```bash theme={null} nscale filestorage snapshot-policy update --name [flags] ``` ### Flags
FlagDescription
`--id string`File storage ID. Can also be passed as a positional argument
`--org string`Organization ID
`--name string`Name of the snapshot policy to update (prompts if omitted)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale filestorage snapshot-policy update --name daily ``` *** ## snapshot-policy delete Remove a snapshot policy from a file storage resource. If you omit `--name`, you pick the policy from a list. ```bash theme={null} nscale filestorage snapshot-policy delete --name [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | File storage ID. Can also be passed as a positional argument | | `--org string` | Organization ID | | `--name string` | Name of the snapshot policy to delete (prompts if omitted) | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale filestorage snapshot-policy delete --name daily --yes ``` *** ## Related > **[File Storage (Console)](/docs/storage/file-storage)** > > Create and manage file storage via the Console UI. # Flavors Source: https://docs.nscale.com/docs/cli/flavors List available compute flavors (instance types). Flavors define the hardware configuration available for compute instances — including CPU, memory, and GPU specifications. ## Subcommands * [list](#list) — List flavors *** ## list List the flavors in a region, including pinned-only ones. If you omit `--region`, the CLI opens an interactive picker, so always pass it in scripts. The table shows each flavor's ID, name, architecture, CPU count, memory, disk, whether it is pinned-only, and its GPUs. ```bash theme={null} nscale flavors list --region [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Pinned-only flavors A pinned-only flavor is reservation-only: a server using it must target a specific host, so instances and on-demand node pools can't use it. These flavors show `yes` in the **Pinned** column and have `spec.pinnedOnly` set to `true` in JSON output. The interactive flavor pickers for [instances](/docs/cli/instances#create) and [compute node pools](/docs/cli/kubernetes#nodepool-create) leave them out. To list only the flavors an instance can use: ```bash theme={null} nscale flavors list --region \ -q '.[] | select(.spec.pinnedOnly != true) | .metadata.id' ``` ### Examples ```bash theme={null} # List all flavors in a region nscale flavors list --org --region # Output as JSON nscale flavors list --org --region --json ``` # Groups Source: https://docs.nscale.com/docs/cli/groups Manage groups within an organization. Groups allow you to organize users and control access to resources within an organization. Commands that act on one group take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List groups * [get](#get) — Get group details * [create](#create) — Create a new group * [update](#update) — Update an existing group * [delete](#delete) — Delete a group *** ## list List groups in an organization. ```bash theme={null} nscale groups list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## get Get details for a specific group. ```bash theme={null} nscale groups get --org ``` ### Flags
FlagDescription
`--id string`Group ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new group in the specified organization. Supports interactive mode or JSON input. ```bash theme={null} nscale groups create --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale groups create --org --file group.json nscale groups create --org --stdin < group.json cat group.json | nscale groups create --org --stdin # Interactive mode nscale groups create ``` *** ## update Update an existing group. ```bash theme={null} nscale groups update --org [flags] ``` ### Flags
FlagDescription
`--id string`Group ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale groups update --org --file group.json nscale groups update --org --stdin < group.json cat group.json | nscale groups update --org --stdin # Interactive mode nscale groups update ``` *** ## delete Delete an existing group. ```bash theme={null} nscale groups delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Group ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | # Images Source: https://docs.nscale.com/docs/cli/images Manage compute images. Images are the base templates used when creating compute instances. You can use public images or create custom ones. **Aliases:** `images`, `img` Commands that act on one image take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List images * [create](#create) — Create a new image * [delete](#delete) — Delete an image *** ## list List available images, optionally filtered by organization and region. ```bash theme={null} nscale images list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale images list --org --region ``` *** ## create Create a new custom image. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the image details. ```bash theme={null} nscale images create [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Region ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale images create --file image.json nscale images create --stdin < image.json cat image.json | nscale images create --stdin ``` *** ## delete Delete an existing image. ```bash theme={null} nscale images delete [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Image ID | | `--org string` | Organization ID | | `--region string` | Region ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale images delete --org --yes ``` *** ## Related > **[Custom Images (Console)](/docs/storage/custom-images)** > > Upload and use custom OS images via the Console UI. # Inferencing Source: https://docs.nscale.com/docs/cli/inferencing Manage inferencing resources — list models, endpoints, and send chat completions. **Aliases:** `inferencing`, `infer` ## Subcommands * [list-models](#list-models) — List available models * [list-endpoints](#list-endpoints) — List inferencing endpoints * [chat](#chat) — Send a chat completion request *** ## list-models Returns a list of all models available on the serverless platform. ```bash theme={null} nscale inferencing list-models [flags] ``` ### Flags
FlagDescription
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale inferencing list-models --json ``` *** ## list-endpoints Returns a list of all model endpoints available for use by the specified organization. ```bash theme={null} nscale inferencing list-endpoints [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale inferencing list-endpoints --org ``` *** ## chat Send a chat completion request to the inference API using a configuration file. Supports both batch and interactive modes. ```bash theme={null} nscale inferencing chat [flags] ``` ### Flags | Flag | Description | | - | - | | `--config string` | Path to a chat configuration file (JSON) | | `--messages string` | Path to a JSON+LD file containing additional messages | | `--ui` | Launch interactive chat TUI | ### Reasoning content When you use the interactive TUI (`--ui`) with a model that supports reasoning, the model's thought process appears in a separate "Thought Process" bubble above the response. The reasoning streams live as the model works through the problem, and the final answer appears in the standard response bubble once reasoning is complete. This gives you visibility into how the model arrives at its answer without cluttering the final response. ### Examples ```bash theme={null} # Send a chat completion using a config file nscale inferencing chat --config chat-config.json # Launch the interactive chat TUI nscale inferencing chat --config chat-config.json --ui # Include additional messages from a file nscale inferencing chat --config chat-config.json --messages extra-messages.json ``` *** ## Related > **[Models](/docs/ai-services/models)** > > Learn about available models on the Nscale platform. > **[Chat Use Case](/docs/use-cases/chat)** > > End-to-end guide for chat inferencing. # Instances Source: https://docs.nscale.com/docs/cli/instances Manage compute instances. **Aliases:** `instances`, `inst` Commands that act on one instance take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List instances * [get](#get) — Get instance details * [create](#create) — Create a new instance * [update](#update) — Update an existing instance * [delete](#delete) — Delete an instance * [start](#start) — Start an instance * [stop](#stop) — Stop an instance * [reboot](#reboot) — Reboot an instance * [snapshot](#snapshot) — Create a snapshot from an instance * [ssh](#ssh) — Open an SSH session to an instance * [sshkey](#sshkey) — Get an instance's SSH key * [consoleoutput](#consoleoutput) — Get instance console output * [consolesession](#consolesession) — Get a VNC console session URL *** ## list List compute instances, optionally filtered by organization, project, network, or region. ```bash theme={null} nscale instances list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--network string`Network ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale instances list --org --region ``` *** ## get Get details for a specific instance. ```bash theme={null} nscale instances get --org ``` ### Flags
FlagDescription
`--id string`Instance ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new compute instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the instance details. Optionally supply a cloud-init configuration or bind an SSH certificate authority. ```bash theme={null} nscale instances create [flags] ``` ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--cloud-init-path string`Path to a cloud-init YAML file
`--ssh-ca-id string`SSH certificate authority ID to bind (pass empty string to clear)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale instances create --file instance.json nscale instances create --stdin < instance.json cat instance.json | nscale instances create --stdin ``` *** ## update Update an existing instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the fields to change. You can update the description and other mutable fields, but the instance **name is immutable** — it cannot be changed after creation. ```bash theme={null} nscale instances update [flags] ``` ### Flags
FlagDescription
`--id string`Instance ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--ssh-ca-id string`SSH certificate authority ID to bind (pass empty string to clear)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale instances update --file instance.json nscale instances update --stdin < instance.json cat instance.json | nscale instances update --stdin ``` *** ## delete Delete an existing instance. ```bash theme={null} nscale instances delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | *** ## start Start a stopped instance. ```bash theme={null} nscale instances start --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm start | *** ## stop Stop a running instance. ```bash theme={null} nscale instances stop --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm stop | *** ## reboot Reboot an instance. Use `--hard` for a hard reboot. ```bash theme={null} nscale instances reboot --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | | `--hard` | Use hard reboot | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm reboot | *** ## snapshot Create an image snapshot from an instance. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the snapshot name and description. ```bash theme={null} nscale instances snapshot [flags] ``` ### Flags
FlagDescription
`--id string`Instance ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm snapshot
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale instances snapshot --file snapshot.json nscale instances snapshot --stdin < snapshot.json cat snapshot.json | nscale instances snapshot --stdin ``` *** ## ssh Open an interactive SSH session to an instance using the system SSH client. ```bash theme={null} nscale instances ssh [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | | `-l, --ssh-user string` | SSH login user (default: `"root"`) | ### Examples ```bash theme={null} nscale instances ssh nscale instances ssh --id nscale instances ssh --org nscale instances ssh --ssh-user ubuntu nscale instances ssh -l ubuntu nscale instances ssh -l ubuntu nscale instances ssh -- -L 8443:127.0.0.1:443 ``` *** ## sshkey Get the SSH key for an instance. ```bash theme={null} nscale instances sshkey --org ``` ### Flags
FlagDescription
`--id string`Instance ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## consoleoutput Retrieve the serial console output of an instance. ```bash theme={null} nscale instances consoleoutput --org [flags] ``` ### Flags
FlagDescription
`--id string`Instance ID
`--org string`Organization ID
`--length int`Output length in bytes (0 uses API default)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## consolesession Get a VNC console session URL for an instance. ```bash theme={null} nscale instances consolesession --org ``` ### Flags | Flag | Description | | - | - | | `--id string` | Instance ID | | `--org string` | Organization ID | *** ## Related > **[Instances (Console)](/docs/compute/create-new-instances)** > > Create and manage instances via the Console UI. > **[Custom Images](/docs/storage/custom-images)** > > Upload and use custom OS images for instances. # Kubernetes Source: https://docs.nscale.com/docs/cli/kubernetes Manage Nscale Kubernetes Service clusters, node pools, platform releases, and kubeconfigs. **Aliases:** `kubernetes`, `k8s` Manage [Nscale Kubernetes Service (NKS)](/docs/platform-services/managed-kubernetes) clusters, the node pools that provide their worker capacity, and the platform releases they run on. Every command except [`token`](#token) acts in the organization given by `--org`, or the one saved in your [context](/docs/cli/contexts). A typical workflow: 1. Pick a platform release with [`release list`](#release-list). 2. Create a cluster on an existing [network](/docs/cli/networks) with [`cluster create`](#cluster-create). 3. Add worker capacity with [`nodepool create`](#nodepool-create). 4. Point `kubectl` at the cluster with [`kubeconfig get`](#kubeconfig-get). Cluster and node pool writes are asynchronous: the API accepts the request and does the work in the background. Pass `--wait` to block until the resource settles. If `--wait-timeout` runs out first, the command prints the resource as it stands and exits non-zero, while the operation carries on server-side. Commands that act on one resource take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands **Clusters** (aliases: `cluster`, `clusters`) * [cluster list](#cluster-list) — List Kubernetes clusters * [cluster get](#cluster-get) — Get Kubernetes cluster details * [cluster create](#cluster-create) — Create a new Kubernetes cluster * [cluster update](#cluster-update) — Update an existing Kubernetes cluster * [cluster delete](#cluster-delete) — Delete an existing Kubernetes cluster **Node pools** (aliases: `nodepool`, `nodepools`) * [nodepool list](#nodepool-list) — List Kubernetes cluster node pools * [nodepool get](#nodepool-get) — Get Kubernetes cluster node pool details * [nodepool create](#nodepool-create) — Create a new Kubernetes cluster node pool * [nodepool update](#nodepool-update) — Update an existing Kubernetes cluster node pool * [nodepool delete](#nodepool-delete) — Delete an existing Kubernetes cluster node pool **Platform releases** (aliases: `release`, `releases`) * [release list](#release-list) — List Kubernetes platform releases * [release get](#release-get) — Get Kubernetes platform release details **Access** (aliases for `kubeconfig`: `kubeconfig`, `config`) * [kubeconfig get](#kubeconfig-get) — Get a kubeconfig for a Kubernetes cluster * [token](#token) — Print a Kubernetes ExecCredential for the current Nscale credentials *** ## cluster list List Kubernetes clusters, optionally filtered by project, region, network, name, or status. ```bash theme={null} nscale kubernetes cluster list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Only show clusters in this project ID
`--region string`Only show clusters in this region ID
`--network string`Only show clusters attached to this network ID
`--name string`Only show clusters with this exact name
`--provisioning-status string`Only show clusters in this provisioning state — `pending`, `provisioning`, `provisioned`, `deprovisioning`, or `error`
`--health-status string`Only show clusters in this health state — `healthy`, `degraded`, `error`, or `unknown`
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale k8s cluster list --project nscale k8s cluster list --provisioning-status provisioned -q ".[].metadata.id" ``` *** ## cluster get Get details for a specific cluster, including its platform release, API server endpoints, and status. ```bash theme={null} nscale kubernetes cluster get --org ``` ### Flags
FlagDescription
`--org string`Organization ID
`--id string`Cluster ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## cluster create Create a new Kubernetes cluster. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the cluster's name, description, network, SSH certificate authority, platform release, pod and service networks, API server access, API server authentication and authorization, and addons. Two of the prompts set fields that can't be changed after creation: * **SSH certificate authority.** If the network's project has any [SSH certificate authorities](/docs/cli/ssh-cas), the CLI asks whether the workers should trust one and offers a picker. With none in the project, the question is skipped. * **API server authentication and authorization.** The CLI asks whether to configure them; most clusters answer no. Answer yes to choose whether the API server accepts Nscale credentials (the platform default, enabled, or disabled), add up to eight external OpenID Connect issuers, and bind users and groups to the built-in `cluster-admin`, `admin`, `edit`, and `view` cluster roles. For each issuer, the CLI asks for the HTTPS issuer URL, the token audiences, the username claim and the required username prefix, an optional groups claim with its prefix, and an optional CA certificate, read from a PEM file you pick. If you disable Nscale credentials, you must add at least one issuer, otherwise nobody could sign in. Role binding subjects must include the issuer's username or groups prefix. See [Use your own identity provider](/docs/platform-services/managed-kubernetes#use-your-own-identity-provider). The cluster is attached to an existing network. Platform releases are regional, so pick one available in the network's region. Use [`nscale networks list`](/docs/cli/networks#list) and [`release list`](#release-list) to discover the IDs. ```bash theme={null} nscale kubernetes cluster create --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--wait`Block until provisioning finishes
`--wait-timeout duration`How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm cluster creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Payload ```json cluster.json theme={null} { "metadata": { "name": "demo-cluster", "description": "Demo Kubernetes cluster" }, "spec": { "networkId": "", "platformReleaseId": "", "clusterNetwork": { "podCidr": "10.240.0.0/12", "serviceCidr": "10.96.0.0/16" }, "apiServer": { "publicIP": true, "allowedCidrs": ["203.0.113.0/24"] }, "addons": { "hardware": { "enabled": true }, "nodeHealth": { "enabled": true } } } } ``` | Field | Required | Description | | - | - | - | | `metadata.name` | Yes | Cluster name | | `metadata.description` | No | Free-form description | | `spec.networkId` | Yes | Network to attach the cluster to. Cannot be changed after creation | | `spec.platformReleaseId` | Yes | Platform release to run, from [`release list`](#release-list) | | `spec.sshCertificateAuthorityId` | No | [SSH certificate authority](/docs/cli/ssh-cas) that the cluster's workers trust. Cannot be changed after creation | | `spec.clusterNetwork.podCidr` | No | IPv4 CIDR for pod addresses (default `10.240.0.0/12`) | | `spec.clusterNetwork.serviceCidr` | No | IPv4 CIDR for service addresses (default `10.96.0.0/16`) | | `spec.apiServer.publicIP` | No | Expose the API server on a public endpoint (default `false`) | | `spec.apiServer.allowedCidrs` | No | Up to 32 source IPv4 CIDRs allowed to reach the API server, including private endpoints (default `0.0.0.0/0`) | | `spec.apiServer.authentication`, `spec.apiServer.authorization` | No | Let people sign in with your own OpenID Connect provider and bind them to built-in roles. Cannot be changed after creation. See [Use your own identity provider](/docs/platform-services/managed-kubernetes#use-your-own-identity-provider) | | `spec.addons.hardware.enabled` | No | Install the drivers and plugins that GPUs and the HPC network need (default `true`). The core profile is always installed | | `spec.addons.nodeHealth.enabled` | No | Detect and report problems with the cluster's nodes (default `true`). Only applies when the platform release provides it | ### Examples ```bash theme={null} nscale k8s cluster create --file cluster.json nscale k8s cluster create --stdin < cluster.json nscale k8s cluster create --file cluster.json --yes --wait ``` *** ## cluster update Update an existing cluster. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the cluster as it stands. The payload has the same shape as [`cluster create`](#cluster-create) and replaces the cluster's desired state, so include every field you want to keep. `spec.networkId`, `spec.sshCertificateAuthorityId`, and the API server's `authentication` and `authorization` cannot change. The prompts carry these fields over from the cluster unchanged. The update is applied asynchronously. ```bash theme={null} nscale kubernetes cluster update --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--id string`Cluster ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--wait`Block until the update finishes
`--wait-timeout duration`How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm cluster update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale k8s cluster update --file cluster.json nscale k8s cluster update --stdin < cluster.json nscale k8s cluster update --file cluster.json --yes --wait ``` *** ## cluster delete Delete an existing cluster, along with its node pools. Teardown is asynchronous. > [!WARNING] > > Deleting a cluster is permanent. All of its node pools, nodes, and ephemeral data are removed. ```bash theme={null} nscale kubernetes cluster delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--org string` | Organization ID | | `--id string` | Cluster ID | | `--wait` | Block until deletion finishes | | `--wait-timeout duration` | How long `--wait` polls before giving up (default `30m0s`) | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Examples ```bash theme={null} nscale k8s cluster delete nscale k8s cluster delete --yes --wait ``` *** ## nodepool list List the node pools in the organization. Pass `--cluster` to see only the pools of one cluster. ```bash theme={null} nscale kubernetes nodepool list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--cluster string`Only show node pools in this cluster ID
`--project string`Only show node pools in this project ID
`--region string`Only show node pools in this region ID
`--name string`Only show node pools with this exact name
`--provisioning-status string`Only show node pools in this provisioning state — `pending`, `provisioning`, `provisioned`, `deprovisioning`, or `error`
`--health-status string`Only show node pools in this health state — `healthy`, `degraded`, `error`, or `unknown`
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale k8s nodepool list nscale k8s nodepool list --cluster ``` *** ## nodepool get Get details for a specific node pool. ```bash theme={null} nscale kubernetes nodepool get --org ``` ### Flags
FlagDescription
`--org string`Organization ID
`--id string`Node pool ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## nodepool create Create a new node pool in a cluster. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the cluster, name, description, capacity source, flavor or reservation, replica count, labels, and taints. Enter labels as a comma-separated `key=value` list, for example `nscale.com/team=ml,gpu`; a key on its own sets an empty value. To set a reservation pool's placement policy, use a file. The flavor picker leaves out [pinned-only flavors](/docs/cli/flavors#pinned-only-flavors), which only reservations can use. Workers come either from a compute [flavor](/docs/cli/flavors) or from reserved capacity in a [reservation](/docs/cli/reservations), chosen with `spec.provisioningMode`. For how the two kinds of pool differ, see [Compute pools and reservation pools](/docs/platform-services/managed-kubernetes#compute-pools-and-reservation-pools). ```bash theme={null} nscale kubernetes nodepool create --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--wait`Block until provisioning finishes
`--wait-timeout duration`How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm node pool creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Payload A node pool backed by a compute flavor: ```json nodepool.json theme={null} { "metadata": { "name": "gpu-workers", "description": "GPU node pool" }, "spec": { "clusterId": "", "provisioningMode": "compute", "replicas": 2, "compute": { "flavorId": "" }, "labels": { "accelerator": "nvidia-h100" }, "taints": [ { "key": "nvidia.com/gpu", "value": "true", "effect": "NoSchedule" } ] } } ``` A node pool drawing on reserved capacity: ```json nodepool-reservation.json theme={null} { "metadata": { "name": "reserved-workers" }, "spec": { "clusterId": "", "provisioningMode": "reservation", "replicas": 2, "reservation": { "reservationId": "", "constraints": { "policy": "spread", "maxSkew": 1, "whenUnsatisfiable": "fail" } } } } ``` | Field | Required | Description | | - | - | - | | `metadata.name` | Yes | Node pool name | | `metadata.description` | No | Free-form description | | `spec.clusterId` | Yes | Cluster the node pool belongs to | | `spec.provisioningMode` | Yes | Capacity source — `compute` or `reservation` | | `spec.replicas` | Yes | Number of workers. For a reservation pool, the number of hosts to take from the reservation | | `spec.compute.flavorId` | When `compute` | Compute flavor for the workers | | `spec.reservation.reservationId` | When `reservation` | Reservation to draw capacity from | | `spec.reservation.constraints.policy` | No | [Placement policy](/docs/compute/placements#placement-policy) — `pack` fills topology domains in turn, `spread` distributes hosts across them. Cannot be changed after creation | | `spec.reservation.constraints.maxSkew` | No | Largest allowed difference in host count between domains. `spread` only | | `spec.reservation.constraints.minDomains` | No | Minimum number of domains that receive a host. `spread` only | | `spec.reservation.constraints.whenUnsatisfiable` | No | `fail` rejects a spread that can't be satisfied, `bestEffort` picks the closest layout. `spread` only | | `spec.labels` | No | Up to 64 Kubernetes labels applied to the workers, as key-value pairs | | `spec.taints` | No | Up to 64 Kubernetes taints applied to the workers | | `spec.taints[].key` | Yes | Taint key | | `spec.taints[].value` | No | Taint value | | `spec.taints[].effect` | Yes | `NoSchedule`, `PreferNoSchedule`, or `NoExecute` | Labels and taints are applied when a worker joins the cluster, and are not kept in sync on running nodes afterward. ### Examples ```bash theme={null} nscale k8s nodepool create --file nodepool.json nscale k8s nodepool create --stdin < nodepool.json nscale k8s nodepool create --file nodepool.json --yes --wait ``` *** ## nodepool update Update an existing node pool, for example to resize it or change its taints. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the node pool as it stands. The payload has the same shape as [`nodepool create`](#nodepool-create) and replaces the node pool's desired state, so include every field you want to keep. The prompts ask for the same fields as `nodepool create` except the cluster, pre-filled with the pool's current values, including its labels. The cluster and the placement policy carry over unchanged. The update is applied asynchronously. Changing labels or taints rolls the pool's existing workers, replacing them with new ones that carry the new values. The labels prompt warns you of this. > [!NOTE] > > Only compute pools can be changed. A reservation pool's host count, placement policy, taints, and labels are fixed when it's created. To change any of them, [create a new pool](#nodepool-create) and delete the old one. ```bash theme={null} nscale kubernetes nodepool update --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--id string`Node pool ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--wait`Block until the update finishes
`--wait-timeout duration`How long `--wait` polls before giving up (default `30m0s`)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm node pool update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale k8s nodepool update --file nodepool.json nscale k8s nodepool update --stdin < nodepool.json nscale k8s nodepool update --file nodepool.json --yes --wait ``` *** ## nodepool delete Delete a node pool, along with the workers it runs. Teardown is asynchronous. ```bash theme={null} nscale kubernetes nodepool delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--org string` | Organization ID | | `--id string` | Node pool ID | | `--wait` | Block until deletion finishes | | `--wait-timeout duration` | How long `--wait` polls before giving up (default `30m0s`) | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Examples ```bash theme={null} nscale k8s nodepool delete nscale k8s nodepool delete --yes --wait ``` *** ## release list List the platform releases offered to the organization, including releases shared with every organization. Each release provides a Kubernetes version, the CPU architectures it supports, and the versions of its addon components. To see only the releases a new cluster should use, pass `--deprecated=false --withdrawn=false`. ```bash theme={null} nscale kubernetes release list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Only show releases available in this region ID
`--architecture string`Only show releases supporting this CPU architecture — `x86_64` or `aarch64`
`--deprecated`Only show deprecated releases; pass `--deprecated=false` for only non-deprecated ones
`--withdrawn`Only show withdrawn releases; pass `--withdrawn=false` for only available ones
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale k8s release list --region --deprecated=false --withdrawn=false ``` *** ## release get Get details for a specific platform release. Without an ID, the picker offers every release offered to the organization, including deprecated and withdrawn ones. ```bash theme={null} nscale kubernetes release get --org ``` ### Flags
FlagDescription
`--org string`Organization ID
`--id string`Platform release ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## kubeconfig get Assemble a `kubectl` configuration for a cluster. By default the kubeconfig is written to stdout. Pass `--output` to write it to a file, or `--merge` to fold it into the kubeconfig `kubectl` already reads. The kubeconfig carries no credentials of its own. It names [`nscale kubernetes token`](#token) as an exec credential plugin, so `kubectl` asks the CLI for a fresh token whenever it needs one. Sharing the file grants nobody access, and it does not go stale when your token rotates. If you pass `--user` or `--context`, the generated kubeconfig passes them on to `nscale kubernetes token`. > [!NOTE] > > `kubectl` runs `nscale` to get a token, so the CLI must be on your `PATH` wherever you use the kubeconfig. ```bash theme={null} nscale kubernetes kubeconfig get --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--org string` | Organization ID | | `--cluster string` | Cluster ID. Can also be passed as a positional argument | | `--endpoint string` | API server endpoint to use — `public` or `private`. Defaults to the public endpoint, falling back to the private one | | `-o, --output string` | Write the kubeconfig to this file instead of stdout. With `--merge`, merge into this file instead of the default kubeconfig | | `--merge` | Merge into the kubeconfig `kubectl` reads (`$KUBECONFIG`, or `~/.kube/config`) rather than emitting a standalone one, leaving its other clusters untouched | | `--set-current-context` | When merging, switch the current context to the new one; pass `--set-current-context=false` to leave it alone (default `true`) | | `--context-name string` | Name for the generated cluster, user, and context entries (default `nks--`) | ### Examples ```bash theme={null} # Merge into ~/.kube/config and switch to the new context nscale k8s kubeconfig get --merge kubectl get nodes # Write a standalone kubeconfig nscale k8s kubeconfig get --output kubeconfig.yaml KUBECONFIG=kubeconfig.yaml kubectl get nodes ``` Running the command again for the same cluster replaces its entries rather than duplicating them. *** ## token Print the current Nscale access token as a `client.authentication.k8s.io` ExecCredential. This command is run by `kubectl`, not by hand: the kubeconfig written by [`kubeconfig get`](#kubeconfig-get) names it as an exec credential plugin. It does not need an organization. Credentials are refreshed the same way as for every other command, and `NSCALE_SERVICE_TOKEN` is honored for CI. ```bash theme={null} nscale kubernetes token ``` # Load balancers Source: https://docs.nscale.com/docs/cli/load-balancers Manage load balancers that spread TCP and UDP traffic across backends on a network. A load balancer takes a virtual IP (VIP) on one of your [networks](/docs/cli/networks), and optionally a public IP, and forwards traffic from its listeners to a pool of backend members. Every command acts in the organization given by `--org`, or the one saved in your [context](/docs/cli/contexts). **Aliases:** `load-balancers`, `loadbalancers`, `lb` Commands that act on one load balancer take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List load balancers * [get](#get) — Get load balancer details * [create](#create) — Create a new load balancer * [update](#update) — Update an existing load balancer * [delete](#delete) — Delete an existing load balancer *** ## list List load balancers, optionally filtered by project, region, or network. The table shows each load balancer's ID, name, VIP, public IP, and number of listeners. ```bash theme={null} nscale load-balancers list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--region string`Region ID
`--network string`Network ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale load-balancers list --org --network # Print each load balancer's ID and provisioned VIP nscale lb list -q '.[].metadata.id' -q '.[].status.vipAddress' ``` *** ## get Get details for a specific load balancer, including its listeners and the VIP and public IP it was given. ```bash theme={null} nscale load-balancers get --org ``` ### Flags
FlagDescription
`--id string`Load balancer ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} # List each listener as name protocol/port nscale load-balancers get \ -q '.spec.listeners[] | "\(.name) \(.protocol)/\(.port)"' ``` *** ## create Create a new load balancer. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, network, whether to allocate a public IP, and an optional VIP, then opens a listener editor where you add each listener and its pool members. The load balancer belongs to the project and region of the network you attach it to. Use [`nscale networks list`](/docs/cli/networks#list) to find the network ID. ```bash theme={null} nscale load-balancers create [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm load balancer creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Payload This example has two listeners: TCP port 80 with a health check, open to any source, and UDP port 53. ```json loadbalancer.json theme={null} { "metadata": { "name": "demo-load-balancer", "description": "Demo load balancer" }, "spec": { "networkId": "efe3c4ba-636c-403b-a073-770fb6fcc132", "publicIP": true, "listeners": [ { "name": "http", "protocol": "tcp", "port": 80, "idleTimeoutSeconds": 120, "allowedCidrs": ["0.0.0.0/0"], "pool": { "healthCheck": { "intervalSeconds": 10, "timeoutSeconds": 5, "healthyThreshold": 3, "unhealthyThreshold": 3 }, "members": [ { "address": "10.0.0.10", "port": 8080 } ] } }, { "name": "dns", "protocol": "udp", "port": 53, "pool": { "members": [ { "address": "10.0.0.21", "port": 53 } ] } } ] } } ``` | Field | Required | Description | | - | - | - | | `metadata.name` | Yes | Load balancer name: lower-case letters, digits, and hyphens, not starting or ending with a hyphen | | `metadata.description` | No | Free-text description | | `spec.networkId` | Yes | Network to place the load balancer on. Cannot be changed later. | | `spec.vipAddress` | No | IPv4 address to request as the VIP. It must fall within the network's CIDR. If omitted, one is picked from the network. Cannot be changed later. | | `spec.publicIP` | No | Allocate a public IP address for the load balancer | | `spec.listeners` | Yes | At least one listener | | `listeners[].name` | Yes | Listener name, unique within the load balancer | | `listeners[].protocol` | Yes | `tcp` or `udp` | | `listeners[].port` | Yes | Port the load balancer listens on (1 to 65535) | | `listeners[].idleTimeoutSeconds` | No | Seconds before an idle connection is closed (1 to 86400). TCP only; defaults to 60. | | `listeners[].allowedCidrs` | No | IPv4 CIDRs allowed to connect. If omitted, any source can connect. | | `listeners[].pool.members` | Yes | Backends, each an IPv4 `address` and a `port` (1 to 65535). The array is required but can be empty. | | `listeners[].pool.healthCheck` | No | `intervalSeconds` and `timeoutSeconds` (1 to 300), `healthyThreshold` and `unhealthyThreshold` (1 to 10) | | `listeners[].pool.proxyProtocolV2` | No | Prefix each connection with a PROXY protocol v2 header carrying the client address | Some constraints aren't obvious from the payload: * **Listener names are DNS labels.** They start with a lower-case letter, contain only lower-case letters, digits, and hyphens, don't end with a hyphen, and are at most 63 characters (`^[a-z]([-a-z0-9]*[a-z0-9])?$`). * **Two listeners can't share a protocol and port.** TCP 53 and UDP 53 can coexist; two TCP 80 listeners can't. * **`idleTimeoutSeconds` is not supported for UDP listeners.** Leave it out of UDP listeners. * **`allowedCidrs` and member addresses are IPv4 only.** * **The network and requested VIP are fixed at creation.** To move a load balancer to another network or VIP, create a new one. ### Examples ```bash theme={null} nscale load-balancers create --file loadbalancer.json nscale load-balancers create --stdin < loadbalancer.json cat loadbalancer.json | nscale load-balancers create --stdin # Preview the request without creating anything nscale load-balancers create --file loadbalancer.json --dry-run ``` *** ## update Update an existing load balancer. Accepts input from a JSON file or stdin. With neither, the CLI prompts for the name, description, and public IP, then opens the listener editor, all pre-filled from the load balancer as it stands. The payload replaces the load balancer's metadata, `publicIP`, and listeners, so include every listener you want to keep. It accepts only `metadata`, `spec.publicIP`, and `spec.listeners`. The network and requested VIP are fixed at creation, and the CLI rejects a payload that contains `spec.networkId` or `spec.vipAddress`, so remove them from a create payload before you reuse it. ```bash theme={null} nscale load-balancers update [flags] ``` ### Flags
FlagDescription
`--id string`Load balancer ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm load balancer update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale load-balancers update --file loadbalancer.json nscale load-balancers update --stdin < loadbalancer.json # Reuse a create payload: drop the create-only fields first jq 'del(.spec.networkId, .spec.vipAddress)' loadbalancer.json \ | nscale load-balancers update --stdin ``` *** ## delete Delete an existing load balancer. ```bash theme={null} nscale load-balancers delete --org [flags] ``` ### Flags
FlagDescription
`--id string`Load balancer ID
`--org string`Organization ID
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm load balancer delete
### Example ```bash theme={null} nscale load-balancers delete --yes ``` *** ## Related > **[Networks (CLI)](/docs/cli/networks)** > > Every load balancer sits on a network and takes its VIP from the network's CIDR. > **[VPC networks](/docs/network/vpc-networks)** > > How VPC networks isolate your resources, and how they are scoped. > **[Security groups](/docs/network/security-groups)** > > Control the traffic that reaches your backend instances. # Login Source: https://docs.nscale.com/docs/cli/login Authenticate with Nscale using browser-based device authorization. Authenticate the CLI with your Nscale account. This opens a browser window to complete the login flow and stores your credentials locally. ```bash theme={null} nscale login ``` The CLI also prints the verification URL and a one-time code. If the browser does not open, visit the URL manually and enter the code. Once authenticated, your credentials are saved and reused automatically for subsequent commands. By default they are stored under the `default` user; pass the global `-u, --user` flag to save them under another name, for example to keep credentials for several accounts side by side: ```bash theme={null} nscale login --user ``` For CI/CD environments where browser-based login isn't possible, use the `NSCALE_SERVICE_TOKEN` environment variable instead: ```bash theme={null} export NSCALE_SERVICE_TOKEN= nscale instances list --org ``` See [Service Accounts](/docs/cli/serviceaccounts) for how to create and manage service account tokens. # Logout Source: https://docs.nscale.com/docs/cli/logout Log out of the CLI and remove stored credentials. Log out of the CLI. This removes the stored credentials for the current user. ```bash theme={null} nscale logout ``` To log out a specific user profile, use the global `-u, --user` flag. Without it, the CLI logs out the user selected by the active [context](/docs/cli/contexts), or `default`: ```bash theme={null} nscale logout --user ``` # Networks Source: https://docs.nscale.com/docs/cli/networks Manage VPC networks. **Aliases:** `networks`, `net`, `vpc` Commands that act on one network take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List networks * [get](#get) — Get network details * [create](#create) — Create a new network * [update](#update) — Update an existing network * [delete](#delete) — Delete a network *** ## list List VPC networks, optionally filtered by organization, project, or region. ```bash theme={null} nscale networks list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale networks list --org --region ``` *** ## get Get details for a specific network. ```bash theme={null} nscale networks get --org ``` ### Flags
FlagDescription
`--id string`Network ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new VPC network. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the network details. ```bash theme={null} nscale networks create [flags] ``` ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale networks create --file network.json nscale networks create --stdin < network.json cat network.json | nscale networks create --stdin ``` *** ## update Update an existing network. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the network as it stands. ```bash theme={null} nscale networks update [flags] ``` ### Flags
FlagDescription
`--id string`Network ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale networks update --file network.json nscale networks update --stdin < network.json cat network.json | nscale networks update --stdin ``` *** ## delete Delete an existing network. ```bash theme={null} nscale networks delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Network ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | *** ## Related > **[VPC Networks (Console)](/docs/network/vpc-networks)** > > Create and manage VPC networks via the Console UI. > **[Load balancers (CLI)](/docs/cli/load-balancers)** > > Load balancers expose services on a network; restrict listener sources with allowed CIDRs. # Object storage Source: https://docs.nscale.com/docs/cli/object-storage Manage object storage endpoints, identity policies, and access keys. **Aliases:** `object-storage`, `os` Commands that act on one endpoint, including the policy and access key commands, take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List object storage endpoints * [classes](#classes) — List object storage endpoint classes * [get](#get) — Get object storage endpoint details * [create](#create) — Create a new object storage endpoint * [delete](#delete) — Delete an object storage endpoint * [list-policies](#list-policies) — List identity policies for an endpoint * [get-policy-document](#get-policy-document) — Show the JSON policy document for an identity policy * [create-policy](#create-policy) — Create a new identity policy on an endpoint * [update-policy](#update-policy) — Update an existing identity policy * [delete-policy](#delete-policy) — Delete an identity policy from an endpoint * [list-access-keys](#list-access-keys) — List access keys for an endpoint * [create-access-key](#create-access-key) — Create a new access key for an endpoint * [delete-access-key](#delete-access-key) — Delete an access key from an endpoint *** ## list List object storage endpoints, optionally filtered by organization, project, or region. ```bash theme={null} nscale object-storage list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale object-storage list --org --region ``` *** ## classes List the object storage endpoint classes you can create endpoints in. A class sets the region an endpoint lives in and the endpoint types it supports. Pass its ID as `spec.objectStorageEndpointClassId` when you [create](#create) an endpoint. The table shows each class's ID, name, region, and endpoint types. ```bash theme={null} nscale object-storage classes [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--region string`Region ID (defaults to all regions)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale object-storage classes --region nscale object-storage classes --region -q '.[].metadata.id' ``` *** ## get Get details for a specific object storage endpoint. ```bash theme={null} nscale object-storage get --org ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new object storage endpoint. Accepts input from a JSON file or stdin. ```bash theme={null} nscale object-storage create [flags] ``` ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale object-storage create --file endpoint.json nscale object-storage create --stdin < endpoint.json cat endpoint.json | nscale object-storage create --stdin ``` *** ## delete Delete an existing object storage endpoint. ```bash theme={null} nscale object-storage delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Object storage endpoint ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale object-storage delete --org --yes ``` *** ## list-policies List identity policies for an object storage endpoint. ```bash theme={null} nscale object-storage list-policies --org ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## get-policy-document Show the JSON policy document for an identity policy on an object storage endpoint. ```bash theme={null} nscale object-storage get-policy-document --name --org ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--name string`Identity policy name
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create-policy Create a new identity policy on an object storage endpoint. The policy document is read from a JSON file or stdin. ```bash theme={null} nscale object-storage create-policy --name [flags] ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--name string`Identity policy name
`--org string`Organization ID
`-f, --file string`Path to a JSON policy document file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale object-storage create-policy --name read-only --file policy.json cat policy.json | nscale object-storage create-policy --name read-only --stdin ``` *** ## update-policy Update an existing identity policy on an object storage endpoint. The policy document is read from a JSON file or stdin. ```bash theme={null} nscale object-storage update-policy --name [flags] ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--name string`Identity policy name
`--org string`Organization ID
`-f, --file string`Path to a JSON policy document file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale object-storage update-policy --name read-only --file policy.json cat policy.json | nscale object-storage update-policy --name read-only --stdin ``` *** ## delete-policy Delete an identity policy from an object storage endpoint. ```bash theme={null} nscale object-storage delete-policy --name --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Object storage endpoint ID | | `--name string` | Identity policy name | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale object-storage delete-policy --name read-only --org --yes ``` *** ## list-access-keys List access keys for an object storage endpoint. ```bash theme={null} nscale object-storage list-access-keys --org ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create-access-key Create a new access key for an object storage endpoint, optionally associated with an identity policy. ```bash theme={null} nscale object-storage create-access-key --name [flags] ``` ### Flags
FlagDescription
`--id string`Object storage endpoint ID
`--name string`Access key name
`--policy string`Identity policy name to associate with the access key
`--org string`Organization ID
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale object-storage create-access-key --name my-key --policy read-only ``` *** ## delete-access-key Delete an access key from an object storage endpoint. ```bash theme={null} nscale object-storage delete-access-key --access-key-id --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Object storage endpoint ID | | `--access-key-id string` | Access key ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale object-storage delete-access-key --access-key-id --org --yes ``` *** ## Related > **[S3 API (CLI)](/docs/cli/s3api)** > > Manage buckets and objects inside an endpoint. > **[Object Storage (Console)](/docs/storage/object-storage)** > > Create and manage object storage via the Console UI. # Organizations Source: https://docs.nscale.com/docs/cli/organizations List organizations your account has access to. **Aliases:** `organizations`, `org` ## Subcommands * [list](#list) — List organizations *** ## list List all organizations associated with your account. **Aliases:** `list`, `ls` ```bash theme={null} nscale organizations list [flags] ``` ### Flags
FlagDescription
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale organizations list --json ``` # Overview Source: https://docs.nscale.com/docs/cli/overview The CLI provides a powerful, automation-friendly interface to all Nscale resources and services. ## Installation You can install the CLI using any of the following methods: ### Download binary Download the binary for your operating system from the [releases page](https://github.com/nscaledev/homebrew-tap/releases). ### Homebrew (for macOS users) You can install the CLI using Homebrew: ```bash theme={null} # Tap our Homebrew repository brew tap nscaledev/nscale # Install the CLI brew install nscale ``` Alternatively, you can combine both steps into a single command: ```bash theme={null} brew install nscaledev/tap/nscale ``` ## Authentication Before using any commands that interact with Nscale resources, authenticate with: ```bash theme={null} nscale login ``` This opens a browser window to complete authentication. On success, your credentials are stored locally. To log out: ```bash theme={null} nscale logout ``` ### Credential precedence The CLI resolves which credentials to use in this order, from highest to lowest priority: 1. **`NSCALE_SERVICE_TOKEN` environment variable** — when set, the token is used directly and every source below is ignored (no keyring lookup happens at all). 2. **`-u, --user` flag, when explicitly passed** — selects that named entry from the local keyring (the one created by `nscale login`) and takes precedence over any active context. 3. **Active context's user** — the `user` field of the context selected via `--context` or previously set with `nscale contexts use`. Used whenever `-u` is not passed on the command line. 4. **`default` keyring entry** — the fallback when no context is active and `-u` was not passed. > [!WARNING] > > If `NSCALE_SERVICE_TOKEN` is set in your shell, it silently overrides `nscale login`, `--user`, and any context — even if the token belongs to a different organization than you expect. When a command behaves unexpectedly (wrong org, "unauthorized", missing resources), check this first: > > ```bash theme={null} > echo "$NSCALE_SERVICE_TOKEN" > ``` > > Unset it with `unset NSCALE_SERVICE_TOKEN` to fall back to your stored credentials. ## Global flags These flags are available on every command: | Flag | Description | | - | - | | `--org string` | Organization ID — applies to all commands that need an organization context. Falls back to the active context | | `--ci` | Indicates the CLI is running in a CI environment (also set via `CI` env var). Prompts and confirmations fail instead of waiting for input | | `--context string` | Specify the context to use | | `-u, --user string` | Specify the user credentials to use (default: `"default"`) | | `--format string` | Output audience: `human`, `agent`, `json`, `quiet`, or `script`. Detected when unset — see [Output formats](#output-formats) | | `--no-truncate` | Show table values in full instead of clipping them to the terminal width | | `-h, --help` | Show help for any command | ## Environment variables | Variable | Description | | - | - | | `CI` | Set to `true` or `1` to behave as if `--ci` were passed. An explicit `--ci` flag takes precedence | | `NSCALE_OUTPUT_FORMAT` | Override the detected output audience. Same values as `--format`; `--format` wins | | `NSCALE_SERVICE_TOKEN` | Service token for authorization — bypasses stored credentials, useful for CI/CD | ## Contexts Contexts let you switch between different organizations and user configurations without re-specifying flags on every command. ```bash theme={null} # Create or update a context nscale contexts set my-context --org # Switch to a context nscale contexts use my-context # List all contexts nscale contexts list ``` ## Output formats By default, `list` commands print a table and commands that return one resource print it as JSON. Most commands that return data also accept `--json`, which emits the full JSON payload, and [`-q`](/docs/cli/query-output), which extracts fields with a jq filter: ```bash theme={null} nscale instances list --org --json ``` `--json` and `-q` are mutually exclusive — pick whichever fits your downstream tooling. Both take precedence over `--format`. ### Choosing a format with `--format` `--format` (or the `NSCALE_OUTPUT_FORMAT` environment variable; `--format` wins) sets how every command in the invocation renders its output: | Format | Output | | - | - | | `human` | Styled tables and pretty-printed, highlighted JSON. The default at a terminal | | `agent` | Lists as TSV with a lowercase header row, nothing truncated. The default when the CLI detects it is running under a coding agent | | `json` | Every command emits JSON, as if `--json` were passed to each | | `quiet` | Plain output with all decoration dropped | | `script` | Plain text with no ANSI styling and compact JSON. The default when output is piped or `--ci` is set | When `--format` is unset, the CLI detects the audience from the agent harness, the terminal, or the pipe. Detection only picks how output is rendered: it never implies `--yes`, skips a confirmation, or changes what a command does. A human table clips long values to the terminal width. Pass `--no-truncate` to show them in full, at the cost of a table wider than the terminal. Only tables clip: `agent`, `json`, and `-q` output never does. ### Output streams and exit status Data goes to stdout; diagnostics, prompts, and warnings go to stderr, so `nscale ... --json | jq` is always safe. Errors are printed to stderr as `Error: ` and the command exits with status 1; success exits with 0. ## Input formats `create` and `update` commands accept input from a JSON file (`--file`) or standard input (`--stdin`): ```bash theme={null} nscale instances create --file instance.json cat instance.json | nscale instances create --stdin ``` Use `--dry-run` to preview the request payload without making any changes: ```bash theme={null} nscale instances create --file instance.json --dry-run ``` ## Interactive mode When running at a terminal outside of a CI environment, the CLI falls back to interactive prompts for any missing parameters. This means you can run commands without flags and be guided through the required inputs step by step. Commands that act on one resource take its ID either as a positional argument (`nscale instances get `) or with `--id`; passing both is an error unless they match. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. For example, `list` commands will present an organization picker if `--org` is not provided: ![Instances list with interactive org picker](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cli/instances-list.gif?s=6a271748239898f8261cf6877cf51e23) `create` commands will prompt for each required field when no `--file` or `--stdin` input is given: ![Instances create with interactive field prompts](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cli/instances-create.gif?s=349f3ced9c40879c7ab662dd94a01340) To suppress interactive prompts (e.g. in scripts), pass `--ci` or set the `CI` environment variable. With prompts suppressed, a missing value is an error, and so is a confirmation: commands that ask before acting (most deletes and other mutations) fail unless you also pass `--yes`: ```bash theme={null} nscale instances delete --yes --ci ``` ## Shell completion ### Bash ```bash theme={null} # Load completions for current session source <(nscale completion bash) # To load completions for every new session, execute once: # Linux: sudo nscale completion bash > /etc/bash_completion.d/nscale # macOS: # First, ensure bash-completion is installed # brew install bash-completion nscale completion bash > $(brew --prefix)/etc/bash_completion.d/nscale # Then add to ~/.bash_profile: # [[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh" ``` ### Zsh ```bash theme={null} # Load completions for current session source <(nscale completion zsh) # To load completions for every session, execute once: # First, check your fpath directories to find the right location: echo $fpath # Then, create a directory for completions if it doesn't exist: mkdir -p ~/.zsh/completions nscale completion zsh > ~/.zsh/completions/_nscale # If shell completion is not already enabled in your environment, # you will need to enable it. You can execute the following once: echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc echo 'autoload -Uz compinit && compinit' >> ~/.zshrc # You will need to source your ~/.zshrc or start a new shell for this setup to take effect. source ~/.zshrc ``` ### Fish ```bash theme={null} # Load completions for current session nscale completion fish | source # To load completions for every session, execute once: mkdir -p ~/.config/fish/completions nscale completion fish > ~/.config/fish/completions/nscale.fish ``` ### PowerShell ```powershell theme={null} # Load completions for current session nscale completion powershell | Out-String | Invoke-Expression # To load completions for every new session, run: nscale completion powershell > nscale.ps1 # and source this file from your PowerShell profile. ``` ## Query output with `-q` Most commands that return data accept `-q, --query`, which runs the JSON response through a [jq](https://jqlang.github.io/jq/) filter so you can extract a field or reshape the output without piping into a second process. See [Query output with `-q`](/docs/cli/query-output) for examples. ## Available commands These pages track the latest CLI release. If a command below is not recognized, check your version with [`nscale version`](/docs/cli/version) and upgrade — `brew upgrade nscale`, or download a newer binary from the [releases page](https://github.com/nscaledev/homebrew-tap/releases). | Command | Description | | - | - | | [`contexts`](/docs/cli/contexts) | Manage CLI contexts | | [`docs`](/docs/cli/docs) | Print the CLI's own documentation | | [`filestorage`](/docs/cli/filestorage) | Manage file storage resources | | [`flavors`](/docs/cli/flavors) | List available compute flavors | | [`groups`](/docs/cli/groups) | Manage groups | | [`images`](/docs/cli/images) | Manage compute images | | [`inferencing`](/docs/cli/inferencing) | Manage inferencing resources | | [`instances`](/docs/cli/instances) | Manage compute instances | | [`kubernetes`](/docs/cli/kubernetes) | Manage Kubernetes clusters, node pools, and kubeconfigs | | [`load-balancers`](/docs/cli/load-balancers) | Manage load balancers | | [`login`](/docs/cli/login) | Authenticate with Nscale | | [`logout`](/docs/cli/logout) | Log out of the CLI | | [`networks`](/docs/cli/networks) | Manage VPC networks | | [`object-storage`](/docs/cli/object-storage) | Manage object storage endpoints, policies, and access keys | | [`organizations`](/docs/cli/organizations) | List organizations | | [`placements`](/docs/cli/placements) | Manage GPU placements | | [`projects`](/docs/cli/projects) | Manage projects | | [`regions`](/docs/cli/regions) | List available regions | | [`reservations`](/docs/cli/reservations) | Manage GPU reservations | | [`roles`](/docs/cli/roles) | List available roles | | [`s3api`](/docs/cli/s3api) | Manage buckets and objects on object storage endpoints | | [`securitygroups`](/docs/cli/securitygroups) | Manage security groups | | [`serviceaccounts`](/docs/cli/serviceaccounts) | Manage service accounts | | [`ssh-cas`](/docs/cli/ssh-cas) | Manage SSH certificate authorities | | [`users`](/docs/cli/users) | Manage users | | [`version`](/docs/cli/version) | Display the CLI version | # Placements Source: https://docs.nscale.com/docs/cli/placements Manage GPU placements. **Aliases:** `placements`, `placement` Commands that act on one placement take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. The `server-*` commands also open a picker for `--server` if you omit it. ## Subcommands * [list](#list) — List placements * [get](#get) — Get placement details * [create](#create) — Create a new placement * [update](#update) — Change a placement's image or update strategy * [delete](#delete) — Delete a placement * [servers](#servers) — List servers in a placement * [server-reboot](#server-reboot) — Reboot a server in a placement * [server-stop](#server-stop) — Stop a server in a placement * [server-reconcile](#server-reconcile) — Rebuild a drifted server onto the placement's image *** ## list List placements, optionally filtered by organization, project, or reservation. ```bash theme={null} nscale placements list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--reservation string`Reservation ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale placements list --org --reservation ``` *** ## get Get details for a specific placement. ```bash theme={null} nscale placements get --org ``` ### Flags
FlagDescription
`--id string`Placement ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new placement. Accepts input from a JSON file or stdin, with an optional cloud-init configuration for the placed servers. Placements require an SSH certificate authority. Set it in the payload's `spec.serverSpec.sshCertificateAuthorityId` field or pass `--ssh-ca-id`. Use [`nscale ssh-cas list`](/docs/cli/ssh-cas#list) to find the ID. ```bash theme={null} nscale placements create [flags] ``` ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--cloud-init-path string`Path to a cloud-init YAML file
`--ssh-ca-id string`SSH certificate authority ID to bind
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm placement creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale placements create --file placement.json nscale placements create --stdin < placement.json cat placement.json | nscale placements create --stdin nscale placements create --file placement.json --cloud-init-path cloud-init.yaml nscale placements create --file placement.json --ssh-ca-id ``` *** ## update Change a placement's server image or update strategy. The CLI reads the placement, changes only the fields you pass, and writes it back, keeping every other field. Pass `--image`, `--strategy`, or both. All other placement fields are fixed after creation. Changing the image marks the placement's servers as drifted. How they move onto the new image depends on the update strategy: * **`manual`** (the default for a new placement): servers keep their current image until you rebuild each one with [`server-reconcile`](#server-reconcile). * **`rolling`**: the service rebuilds drifted servers for you, at most `--max-unavailable` at a time. `--strategy rolling` requires `--max-unavailable`, and `--max-unavailable` is only accepted with `--strategy rolling`. If you omit `--strategy`, the placement keeps the strategy it already has, so an image change on a `rolling` placement starts a rollout. > [!WARNING] > > Rebuilding a server onto a new image wipes its local disk. Under `rolling`, that happens to every server, `--max-unavailable` at a time, as soon as the update is accepted. Back up anything on local disk before you change the image. ```bash theme={null} nscale placements update [flags] ``` ### Flags
FlagDescription
`--id string`Placement ID
`--org string`Organization ID
`--image string`Image ID to converge the servers onto
`--strategy string`Update strategy: `manual` or `rolling`. The API's spellings, `Manual` and `RollingUpdate`, also work.
`--max-unavailable string`Servers rebuilt at once under `--strategy rolling`: a count (`1`) or a percentage of the placement's servers (`25%`, rounded up)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm placement update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} # Roll a new image out, one server at a time nscale placements update --image --strategy rolling --max-unavailable 1 --yes # Change the image but rebuild servers yourself with server-reconcile nscale placements update --image --strategy manual --yes # Preview the request body without sending it nscale placements update --image --dry-run ``` *** ## delete Delete an existing placement. ```bash theme={null} nscale placements delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Placement ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions without persisting | | `-y, --yes` | Automatically confirm placement delete | ### Example ```bash theme={null} nscale placements delete --org --yes ``` *** ## servers List the servers in a placement. ```bash theme={null} nscale placements servers --org ``` ### Flags
FlagDescription
`--id string`Placement ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example After an image change under the `manual` strategy, list the servers that haven't moved onto the new image yet: ```bash theme={null} nscale placements servers \ -q '.[] | select(.status.driftState == "Drifted") | .metadata.id' ``` *** ## server-reboot Reboot an existing server in a placement. Use `--hard` for a hard reboot. ```bash theme={null} nscale placements server-reboot --server --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Placement ID | | `--server string` | Server ID | | `--org string` | Organization ID | | `--hard` | Use hard reboot | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm server reboot | ### Example ```bash theme={null} nscale placements server-reboot --server --org --yes ``` *** ## server-stop Stop an existing server in a placement. ```bash theme={null} nscale placements server-stop --server --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Placement ID | | `--server string` | Server ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions without persisting | | `-y, --yes` | Automatically confirm server stop | ### Example ```bash theme={null} nscale placements server-stop --server --org --yes ``` *** ## server-reconcile Rebuild one drifted server onto the placement's image. The server stays on the same host, but its local disk contents are lost. Use this after an image change under the `manual` [update strategy](#update) to move servers onto the new image one at a time. If the server already runs the placement's image, nothing changes. ```bash theme={null} nscale placements server-reconcile --server --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Placement ID | | `--server string` | Server ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions without persisting | | `-y, --yes` | Automatically confirm server reconcile | ### Example ```bash theme={null} nscale placements server-reconcile --server --org --yes ``` *** ## Related > **[Reservations](/docs/cli/reservations)** > > Reserve GPU capacity and check available reservation units. # Projects Source: https://docs.nscale.com/docs/cli/projects Manage projects within an organization. Projects help organize resources within an organization. Commands that act on one project take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List projects * [get](#get) — Get project details * [create](#create) — Create a new project * [update](#update) — Update an existing project * [delete](#delete) — Delete a project *** ## list List projects in an organization. ```bash theme={null} nscale projects list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## get Get details for a specific project. ```bash theme={null} nscale projects get --org ``` ### Flags
FlagDescription
`--id string`Project ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new project in the specified organization. Supports interactive mode or JSON input. ```bash theme={null} nscale projects create --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale projects create --org --file project.json nscale projects create --org --stdin < project.json cat project.json | nscale projects create --org --stdin # Interactive mode nscale projects create ``` *** ## update Update an existing project. ```bash theme={null} nscale projects update --org [flags] ``` ### Flags
FlagDescription
`--id string`Project ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale projects update --org --file project.json nscale projects update --org --stdin < project.json cat project.json | nscale projects update --org --stdin # Interactive mode nscale projects update ``` *** ## delete Delete an existing project. ```bash theme={null} nscale projects delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Project ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | # Query output with -q Source: https://docs.nscale.com/docs/cli/query-output Use jq filters to extract or reshape JSON responses without a second process. `-q, --query` runs the JSON response through a [jq](https://jqlang.github.io/jq/) filter and prints the results as raw values, one per line. It is mutually exclusive with `--json`. On a list command, the filter always runs against a bare JSON array of resources, so `.[].metadata.id` works on every list command. This holds even where `--json` wraps the array: `inferencing list-models` and `inferencing list-endpoints` emit `{"data":[...]}` under `--json`, but `-q` still sees the array: ```bash theme={null} nscale inferencing list-models -q ".[].id" ``` On a command that returns one resource, the filter runs against that resource: ```bash theme={null} nscale instances get -q ".status.status" ``` ## Extract a single field Get just the IDs from a list response: ```bash theme={null} nscale instances list -q ".[].metadata.id" ``` Each filter result is printed on its own line, so the output flows naturally into shell loops: ```bash theme={null} for id in $(nscale instances list -q ".[].metadata.id"); do nscale instances stop "$id" --yes done ``` ## Reshape the output Filters can transform the response into a new structure. Results that are not scalars (objects and arrays) print as compact JSON, one per line. The following collects each instance's `id` and `name` into a single array: ```bash theme={null} nscale instances list -q "[.[] | {id: .metadata.id, name: .metadata.name}]" ``` ```json theme={null} [{"id":"bed4405e-bd2f-491a-a515-3612e6d4230f","name":"instance-1"},{"id":"f1facb11-d3de-417f-92c0-dc582cea4c80","name":"instance-2"}] ``` Filter first, then project: ```bash theme={null} nscale instances list -q '.[] | select(.status.status == "Active") | .metadata.id' ``` ## Combine with an external `jq` The output of `-q` is still valid JSON when the filter produces JSON, so you can pipe it into `jq` (or any other JSON-aware tool) for further processing: ```bash theme={null} nscale projects list -q "[.[] | {id: .metadata.id, groupIDs: .spec.groupIDs}]" | jq "[.[] | .id]" ``` ## Multiple filters `-q` can be repeated. The filters' results are zipped into one line per item: one result from each filter per line, space-separated, which is handy for tabular output: ```bash theme={null} nscale instances list -q ".[].metadata.id" -q ".[].metadata.name" -q ".[].status.status" ``` ```text theme={null} bed4405e-bd2f-491a-a515-3612e6d4230f instance-1 Active f1facb11-d3de-417f-92c0-dc582cea4c80 instance-2 Active ``` Output stops as soon as any filter runs out of results. When that happens, a warning is printed on stderr, unless the filter that ran out is the first one: a short first filter is deliberate, as in this example, which prints the count next to the first ID: ```bash theme={null} nscale instances list -q "length" -q ".[].metadata.id" ``` ## When a filter fails An invalid filter makes the command exit with status 1. After a `create` or `update`, the resource has already been saved by then, so the CLI prints the full payload to stdout and the error on stderr explains that only the filter failed. # Regions Source: https://docs.nscale.com/docs/cli/regions List available Nscale regions. ## Subcommands * [list](#list) — List regions *** ## list List available regions, optionally filtered by organization. ```bash theme={null} nscale regions list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale regions list --org --json ``` # Reservations Source: https://docs.nscale.com/docs/cli/reservations Manage GPU reservations. **Aliases:** `reservations`, `reservation`, `res` Commands that act on one reservation take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List reservations * [get](#get) — Get reservation details * [capacity](#capacity) — List available reservation units * [topology](#topology) — Show organization topology * [create](#create) — Create a new reservation * [delete](#delete) — Delete a reservation *** ## list List reservations, optionally filtered by organization, project, or region. ```bash theme={null} nscale reservations list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale reservations list --org --region ``` *** ## get Get details for a specific reservation. ```bash theme={null} nscale reservations get --org ``` ### Flags
FlagDescription
`--id string`Reservation ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## capacity List available reservation units, optionally filtered by region, accelerator model, or unit type. Useful for checking capacity before creating a reservation. **Alias:** `units` ```bash theme={null} nscale reservations capacity [flags] ``` ### Flags
FlagDescription
`--region string`Region ID
`--accelerator string`Accelerator model, for example `GB300`
`--unit string`Reservation unit, for example `NVL72`
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale reservations capacity --region --accelerator GB300 ``` *** ## topology Show the bare-metal capacity allocated to your organization, laid out by region, pod, NVLink domain, and host, with the reservations and placements that hold it. This is the CLI counterpart to the Console's [Topology View](/docs/compute/topology-view). Filter by project, region, reservation, accelerator model, or unit type to narrow the output. In human output, each reservation unit names its machine flavor, including [pinned-only flavors](/docs/cli/flavors#pinned-only-flavors) that only reserved capacity can use. ```bash theme={null} nscale reservations topology [flags] ``` > [!NOTE] > > **Organization-level access required.** Like the Topology View, this command needs organization-level read access to reservation topology, for example the **reservation-capacity-reader** role assigned at organization level. See [Roles and groups](/docs/manage/roles-and-groups#reservations). If topology isn't enabled for your organization, the command fails with `the "topology" command is not available for organization `. ### Flags
FlagDescription
`--project string`Project ID
`--region string`Region ID
`--reservation string`Reservation ID
`--accelerator string`Accelerator model, for example `GB300`
`--unit string`Reservation unit, for example `NVL72`
`--view string`Human output view: `tree` or `grid` (default `tree`). Has no effect on `--json` or `-q` output
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} # Tree view of everything allocated to the organization nscale reservations topology --org # Grid view of one reservation's hosts nscale reservations topology --reservation --view grid # GB300 capacity in one region, as JSON nscale reservations topology --region --accelerator GB300 --json ``` *** ## create Create a new reservation. Accepts input from a JSON file or stdin. ```bash theme={null} nscale reservations create [flags] ``` ### Flags
FlagDescription
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale reservations create --file reservation.json nscale reservations create --stdin < reservation.json cat reservation.json | nscale reservations create --stdin ``` *** ## delete Delete an existing reservation. ```bash theme={null} nscale reservations delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Reservation ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale reservations delete --org --yes ``` *** ## Related > **[Placements](/docs/cli/placements)** > > Place workloads onto reserved capacity and manage their servers. > **[Topology View](/docs/compute/topology-view)** > > See allocated capacity as a map in the Console. # Roles Source: https://docs.nscale.com/docs/cli/roles List the roles available in an organization. Roles define the permissions that can be granted within an organization. Permissions are not assigned to users directly — a role is attached to a [group](/docs/cli/groups), and every user in that group inherits it. Roles are predefined, so this command is read-only. Use it to look up the role IDs you need for the `spec.roleIDs` field when creating or updating a group. For how groups and roles fit together, see [Groups and roles](/docs/manage/roles-and-groups). ## Subcommands * [list](#list) — List roles *** ## list List the roles available in an organization, with their names and descriptions. **Aliases:** `list`, `ls` ```bash theme={null} nscale roles list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} # List all roles in an organization nscale roles list --org # Extract the ID and name of each role nscale roles list --org -q ".[].metadata.id" -q ".[].metadata.name" ``` # S3 API Source: https://docs.nscale.com/docs/cli/s3api Manage buckets and objects on S3-compatible object storage endpoints. `nscale s3api` is an S3 client built into the CLI. For the operations it supports, it follows [`aws s3api`](https://docs.aws.amazon.com/cli/latest/reference/s3api/), plus `presign` from `aws s3`: the same flag names and the same PascalCase response bodies. Use it to work with buckets and objects on an [Object Storage](/docs/storage/object-storage) endpoint without installing or configuring the AWS CLI. **Aliases:** `s3api`, `s3` > [!NOTE] > > To create object storage endpoints, identity policies, and access keys, use [`nscale object-storage`](/docs/cli/object-storage). `nscale s3api` works with the buckets and objects inside an endpoint. ## Quick start **1. Save a profile** Run `configure` and follow the prompts. It asks for a profile name (default `default`), lets you pick an organization and object storage endpoint, and then either creates a new access key or takes the ID and secret of an existing one. ```bash theme={null} nscale s3api configure ``` **2. Run commands** Commands use the `default` profile automatically. Pass `--profile` to use another one. ```bash theme={null} nscale s3api create-bucket --bucket my-bucket nscale s3api put-object --bucket my-bucket --key data.csv --body ./data.csv nscale s3api list-objects-v2 --bucket my-bucket -q '.Contents[]?.Key' ``` ## Endpoint and credentials Every `s3api` command accepts these flags to choose the endpoint and credentials: | Flag | Description | | - | - | | `--profile string` | Profile to use. A profile saved with [`configure`](#configure) is checked first, then an AWS shared-config profile of the same name | | `--id string` | Object storage endpoint ID. The CLI looks up the endpoint's public URL through the Nscale API, so you must be logged in | | `--endpoint-url string` | Object storage endpoint URL, used as given. Mutually exclusive with `--id` | | `--org string` | Organization ID, used to look up the endpoint by `--id` or to pick one interactively | The CLI resolves credentials and the endpoint in this order: 1. **Saved profile.** If a profile named by `--profile` (or `default` when `--profile` is not set) exists in `object-storage-profiles.yaml`, its access key and endpoint URL are used. `--endpoint-url` or `--id` override the saved endpoint URL. 2. **AWS credential chain.** Otherwise, credentials come from the AWS default chain, the same as the AWS CLI: the AWS profile named by `--profile` or `AWS_PROFILE`, the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables, and the files in `~/.aws`. The endpoint comes from `--endpoint-url` or `--id`, then from an `endpoint_url` in the AWS profile or `AWS_ENDPOINT_URL`. If none is set, the CLI prompts you to pick an endpoint. Saved profiles live in `object-storage-profiles.yaml` in the CLI config directory: `~/.config/nscale/` on macOS and Linux (or `$XDG_CONFIG_HOME/nscale/` when set), and `%AppData%\nscale\` on Windows. The file stores access key secrets in plain text and is readable only by your user. ```yaml theme={null} default: access_key_id: access_key_secret: endpoint_url: https:// ``` ## Output `s3api` commands print the S3 response object as JSON, exactly as the AWS SDK returns it: PascalCase keys and no `metadata`/`spec`/`status` envelope. Use `-q` with a jq filter to pick out fields: ```bash theme={null} # Bucket names, one per line nscale s3api list-buckets -q '.Buckets[]?.Name' # Keys and sizes under a prefix nscale s3api list-objects-v2 --bucket my-bucket --prefix logs/ -q '.Contents[]?.Key' -q '.Contents[]?.Size' ``` S3 leaves empty lists out of the response, so a listing with no matches has no `Contents` field and `.Contents[]` fails. Use `.Contents[]?` in scripts that may list an empty prefix. Commands that change bucket configuration (`put-bucket-*`, `delete-bucket-lifecycle`, `delete-bucket-tagging`) and `delete-bucket` print a confirmation message instead of a response body. `get-object` streams the object itself to stdout unless you pass `--outfile`. ## Input values Flags that take a structured value, such as `--delete`, `--multipart-upload`, `--lifecycle-configuration`, `--versioning-configuration`, `--create-bucket-configuration`, and `--tagging` on the bucket and object tagging commands, accept either inline JSON in the AWS SDK shape or a `file://` path to a file that holds it: ```bash theme={null} nscale s3api put-bucket-versioning --bucket my-bucket --versioning-configuration '{"Status":"Enabled"}' nscale s3api delete-objects --bucket my-bucket --delete file://delete.json --yes ``` Date and time flags take RFC3339 timestamps, for example `2026-01-31T12:00:00Z`. ## Pagination The list commands follow the AWS CLI pagination model and fetch every page by default: * `--max-items` caps the total number of items returned across all pages. * `--page-size` caps the number of items requested in each call to the endpoint. * `--starting-token` resumes a listing from the continuation token in a previous response, such as `NextContinuationToken` from `list-objects-v2`, `NextMarker` from `list-objects`, or `NextToken` from `list-object-versions` and `list-multipart-uploads`. ```bash theme={null} nscale s3api list-objects-v2 --bucket my-bucket --max-items 100 ``` ## Subcommands Each command lists its common flags first. The rest, such as server-side encryption, ACLs, Object Lock, and requester-pays settings, are under **Advanced flags**. > [!NOTE] > > Advanced flags are passed to the S3 API as given. Nscale Object Storage does not implement every S3 feature, for example SSE-C, public ACLs, lifecycle rules, and suspending versioning. See [S3 API compatibility](/docs/storage/object-storage#s3-api-compatibility). **Setup** * [configure](#configure) — Save an s3api profile (endpoint and access key) for reuse **Buckets** * [list-buckets](#list-buckets) — List buckets owned by the authenticated account * [create-bucket](#create-bucket) — Create a new bucket * [head-bucket](#head-bucket) — Check whether a bucket exists and is accessible * [get-bucket-location](#get-bucket-location) — Get the region a bucket resides in * [delete-bucket](#delete-bucket) — Delete an empty bucket **Bucket configuration** * [get-bucket-versioning](#get-bucket-versioning) — Get the versioning state of a bucket * [put-bucket-versioning](#put-bucket-versioning) — Set the versioning state of a bucket * [get-bucket-lifecycle-configuration](#get-bucket-lifecycle-configuration) — Get the lifecycle configuration of a bucket * [put-bucket-lifecycle-configuration](#put-bucket-lifecycle-configuration) — Set the lifecycle configuration of a bucket * [delete-bucket-lifecycle](#delete-bucket-lifecycle) — Delete the lifecycle configuration of a bucket * [get-bucket-tagging](#get-bucket-tagging) — Get the tag set of a bucket * [put-bucket-tagging](#put-bucket-tagging) — Set the tags of a bucket * [delete-bucket-tagging](#delete-bucket-tagging) — Delete the tags from a bucket **Objects** * [list-objects-v2](#list-objects-v2) — List objects in a bucket (S3 ListObjectsV2) * [list-objects](#list-objects) — List objects in a bucket (legacy S3 ListObjects V1) * [list-object-versions](#list-object-versions) — List object versions and delete markers in a bucket * [put-object](#put-object) — Add an object to a bucket, streaming the body from a file or stdin * [get-object](#get-object) — Retrieve an object from a bucket, streaming it to a file or stdout * [head-object](#head-object) — Retrieve metadata from an object without returning the object itself * [copy-object](#copy-object) — Create a copy of an object already stored in the bucket * [delete-object](#delete-object) — Remove an object from a bucket * [delete-objects](#delete-objects) — Delete multiple objects from a bucket in a single request * [presign](#presign) — Generate a pre-signed URL for an object **Object tagging** * [get-object-tagging](#get-object-tagging) — Get the tag-set of an object * [put-object-tagging](#put-object-tagging) — Set the tag-set of an object * [delete-object-tagging](#delete-object-tagging) — Remove the entire tag-set from an object **Multipart uploads** * [create-multipart-upload](#create-multipart-upload) — Initiate a multipart upload and return its upload ID * [upload-part](#upload-part) — Upload a part in a multipart upload * [upload-part-copy](#upload-part-copy) — Upload a part by copying data from an existing object * [list-parts](#list-parts) — List the parts uploaded for a specific multipart upload * [list-multipart-uploads](#list-multipart-uploads) — List in-progress multipart uploads in a bucket * [complete-multipart-upload](#complete-multipart-upload) — Complete a multipart upload by assembling its uploaded parts * [abort-multipart-upload](#abort-multipart-upload) — Abort a multipart upload and discard its uploaded parts *** ## configure Save an s3api profile so later commands can run with just `--profile`. Run it interactively to be prompted for the profile name, the endpoint, and the access key. When the endpoint is picked from your organization or passed with `--id`, `configure` can create a new access key for you; the secret is saved to the profile and not printed. To run it without prompts, pass `--profile`, an endpoint (`--endpoint-url` or `--id`), `--key-id`, and `--key-secret`. Read the secret from an environment variable rather than typing it inline, so it does not end up in your shell history. An existing profile with the same name is overwritten; interactively, you are asked to confirm first. ```bash theme={null} nscale s3api configure [flags] ``` ### Flags
FlagDescription
`--key-id string`Access key ID (skips the access-key prompt)
`--key-secret string`Access key secret (skips the access-key prompt)
### Examples ```bash theme={null} # Interactive: pick an endpoint and create an access key nscale s3api configure # Non-interactive, with an existing access key from the environment nscale s3api configure --profile prod --id \ --key-id "$ACCESS_KEY_ID" --key-secret "$ACCESS_KEY_SECRET" ``` *** ## list-buckets List the buckets owned by the access key's account. ```bash theme={null} nscale s3api list-buckets [flags] ``` ### Flags
FlagDescription
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--prefix string`Limit the response to bucket names with this prefix
`--starting-token string`Pagination token marking where a previous listing should resume
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale s3api list-buckets nscale s3api list-buckets --prefix logs- -q '.Buckets[]?.Name' ``` *** ## create-bucket Create a new bucket. ```bash theme={null} nscale s3api create-bucket --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket to create
`--acl string`The canned ACL to apply to the bucket (`private` | `public-read` | `public-read-write` | `authenticated-read`)
`--create-bucket-configuration string`The configuration for the bucket, as JSON
`--object-lock-enabled-for-bucket`Enable S3 Object Lock for the new bucket
`--object-ownership string`Object ownership for the bucket (`BucketOwnerPreferred` | `ObjectWriter` | `BucketOwnerEnforced`)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api create-bucket --bucket my-bucket ``` *** ## head-bucket Check whether a bucket exists and you have permission to access it. The command fails if the bucket does not exist or is not accessible. ```bash theme={null} nscale s3api head-bucket --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket to check
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api head-bucket --bucket my-bucket ``` *** ## get-bucket-location Get the region a bucket resides in. ```bash theme={null} nscale s3api get-bucket-location --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api get-bucket-location --bucket my-bucket -q '.LocationConstraint' ``` *** ## delete-bucket Delete a bucket. The bucket must be empty: delete its objects first, including every object version when versioning is enabled. ```bash theme={null} nscale s3api delete-bucket --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket to delete
`-y, --yes`Automatically confirm bucket deletion
### Example ```bash theme={null} nscale s3api delete-bucket --bucket my-bucket --yes ``` *** ## get-bucket-versioning Get the versioning state of a bucket. ```bash theme={null} nscale s3api get-bucket-versioning --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api get-bucket-versioning --bucket my-bucket -q '.Status' ``` *** ## put-bucket-versioning Set the versioning state of a bucket. Nscale Object Storage supports enabling versioning but not suspending it once enabled. `--versioning-configuration` takes JSON in the SDK `VersioningConfiguration` shape, or a `file://` reference to it. ```bash theme={null} nscale s3api put-bucket-versioning --bucket --versioning-configuration [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--versioning-configuration string`**Required.** Versioning state, as JSON matching the SDK VersioningConfiguration shape or a `file://` reference
> **Advanced flags** > > > > > > > > > > >
FlagDescription
`--checksum-algorithm string`Algorithm used to create the request checksum (`CRC32` | `CRC32C` | `CRC64NVME` | `SHA1` | `SHA256`)
`--content-md5 string`Base64-encoded 128-bit MD5 digest for an integrity check
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--mfa string`MFA device serial number, a space, and the current MFA code
### Example ```bash theme={null} nscale s3api put-bucket-versioning --bucket my-bucket --versioning-configuration '{"Status":"Enabled"}' ``` *** ## get-bucket-lifecycle-configuration > [!WARNING] > > Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see [S3 API compatibility](/docs/storage/object-storage#s3-api-compatibility). Get the lifecycle configuration of a bucket. ```bash theme={null} nscale s3api get-bucket-lifecycle-configuration --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api get-bucket-lifecycle-configuration --bucket my-bucket -q '.Rules[].ID' ``` *** ## put-bucket-lifecycle-configuration > [!WARNING] > > Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see [S3 API compatibility](/docs/storage/object-storage#s3-api-compatibility). Set the lifecycle configuration of a bucket, replacing any existing rules. `--lifecycle-configuration` takes JSON in the SDK `BucketLifecycleConfiguration` shape, or a `file://` reference to it. ```bash theme={null} nscale s3api put-bucket-lifecycle-configuration --bucket --lifecycle-configuration [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--checksum-algorithm string`Algorithm used to create the request checksum (`CRC32` | `CRC32C` | `CRC64NVME` | `SHA1` | `SHA256`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--lifecycle-configuration string`Lifecycle rules, as JSON matching the SDK BucketLifecycleConfiguration shape or a `file://` reference
`--transition-default-minimum-object-size string`Default minimum object size behaviour (`varies_by_storage_class` | `all_storage_classes_128K`)
### Examples ```bash theme={null} # Expire objects under logs/ after 30 days nscale s3api put-bucket-lifecycle-configuration --bucket my-bucket \ --lifecycle-configuration '{"Rules":[{"ID":"expire-logs","Status":"Enabled","Filter":{"Prefix":"logs/"},"Expiration":{"Days":30}}]}' nscale s3api put-bucket-lifecycle-configuration --bucket my-bucket --lifecycle-configuration file://lifecycle.json ``` *** ## delete-bucket-lifecycle > [!WARNING] > > Nscale Object Storage does not support lifecycle configuration. This command is for other S3-compatible endpoints; see [S3 API compatibility](/docs/storage/object-storage#s3-api-compatibility). Delete the lifecycle configuration of a bucket. ```bash theme={null} nscale s3api delete-bucket-lifecycle --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--expected-bucket-owner string`Account ID of the expected bucket owner
### Example ```bash theme={null} nscale s3api delete-bucket-lifecycle --bucket my-bucket ``` *** ## get-bucket-tagging Get the tag set of a bucket. ```bash theme={null} nscale s3api get-bucket-tagging --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api get-bucket-tagging --bucket my-bucket -q '.TagSet[] | "\(.Key)=\(.Value)"' ``` *** ## put-bucket-tagging Set the tags of a bucket, replacing any existing tags. Pass the tags as `key=value` pairs with `--tags`, or as JSON in the SDK `Tagging` shape with `--tagging`. Use `--tagging` when a value contains a comma. ```bash theme={null} nscale s3api put-bucket-tagging --bucket (--tags | --tagging ) [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--checksum-algorithm string`Algorithm used to create the request checksum (`CRC32` | `CRC32C` | `CRC64NVME` | `SHA1` | `SHA256`)
`--content-md5 string`Base64-encoded 128-bit MD5 digest of the data
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--tagging string`Tag-set, as JSON matching the SDK Tagging shape or a `file://` reference; required unless `--tags` is given
`--tags string`Tag-set shorthand as `key=value` pairs, or a `file://` reference to them; an alternative to `--tagging`. Use `--tagging` for values that contain a comma
### Examples ```bash theme={null} nscale s3api put-bucket-tagging --bucket my-bucket --tags 'env=prod,team=data' nscale s3api put-bucket-tagging --bucket my-bucket --tagging '{"TagSet":[{"Key":"env","Value":"prod"}]}' ``` *** ## delete-bucket-tagging Delete the tags from a bucket. ```bash theme={null} nscale s3api delete-bucket-tagging --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--expected-bucket-owner string`Account ID of the expected bucket owner
### Example ```bash theme={null} nscale s3api delete-bucket-tagging --bucket my-bucket ``` *** ## list-objects-v2 List the objects in a bucket with the S3 ListObjectsV2 operation. Use `--prefix` to list a "directory" and `--delimiter /` to group deeper keys into `CommonPrefixes`. ```bash theme={null} nscale s3api list-objects-v2 --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket to list objects from
`--delimiter string`Character used to group keys into common prefixes
`--encoding-type string`Encoding used for object keys in the response (`url`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--fetch-owner`Return the owner field for each key
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--prefix string`Limit the response to keys that begin with this prefix
`--request-payer string`Confirms the requester will be charged for the request (`requester`)
`--start-after string`Start listing after this key
`--starting-token string`Pagination token marking where a previous listing should resume
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale s3api list-objects-v2 --bucket my-bucket nscale s3api list-objects-v2 --bucket my-bucket --prefix logs/ --delimiter / -q '.CommonPrefixes[]?.Prefix' nscale s3api list-objects-v2 --bucket my-bucket --max-items 100 -q '.Contents[]?.Key' ``` *** ## list-objects List the objects in a bucket with the legacy S3 ListObjects (V1) operation. Prefer [`list-objects-v2`](#list-objects-v2) unless a tool depends on the V1 response shape. ```bash theme={null} nscale s3api list-objects --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket to list objects from
`--delimiter string`Character used to group keys into common prefixes
`--encoding-type string`Encoding used for object keys in the response (`url`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--marker string`Key to start listing from
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--prefix string`Limit the response to keys that begin with this prefix
`--request-payer string`Confirms the requester will be charged for the request (`requester`)
`--starting-token string`Pagination token marking where a previous listing should resume
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api list-objects --bucket my-bucket --prefix logs/ ``` *** ## list-object-versions List every version of the objects in a bucket, and any delete markers. ```bash theme={null} nscale s3api list-object-versions --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket to list object versions from
`--delimiter string`Character used to group keys into common prefixes
`--encoding-type string`Encoding used for object keys in the response (`url`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--key-marker string`Key to start listing from
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--prefix string`Limit the response to keys that begin with this prefix
`--request-payer string`Confirms the requester will be charged for the request (`requester`)
`--starting-token string`Pagination token marking where a previous listing should resume
`--version-id-marker string`Version ID to start listing from
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale s3api list-object-versions --bucket my-bucket --prefix data.csv nscale s3api list-object-versions --bucket my-bucket -q '.Versions[]?.VersionId' ``` *** ## put-object Upload an object to a bucket. The body streams from the file named by `--body`, or from stdin when `--body -` is passed, so large files are not read into memory. Omitting `--body` creates an empty object. ```bash theme={null} nscale s3api put-object --bucket --key [--body ] [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The target bucket
`--key string`**Required.** The object key
`--body string`Path to the object data; `-` reads from stdin (streamed, not buffered); omitted uploads an empty object
`--content-type string`Standard MIME type describing the content format
`--metadata string`Metadata to store with the object, as JSON or `key=value` pairs (or a `file://` reference)
`--tagging string`Tag-set for the object, URL query encoded
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--acl string`Canned ACL to apply to the object
`--bucket-key-enabled`Toggle an S3 Bucket Key for SSE-KMS encryption
`--cache-control string`Caching behaviour along the request/reply chain
`--checksum-algorithm string`Algorithm used to create the object checksum
`--checksum-crc32 string`Base64 CRC32 checksum for data integrity
`--checksum-crc32-c string`Base64 CRC32C checksum for data integrity
`--checksum-crc64-nvme string`Base64 CRC64NVME checksum for data integrity
`--checksum-md5 string`Base64 MD5 checksum for data integrity
`--checksum-sha1 string`Base64 SHA1 checksum for data integrity
`--checksum-sha256 string`Base64 SHA256 checksum for data integrity
`--content-disposition string`Presentational information for the object
`--content-encoding string`Content encodings applied to the object
`--content-language string`The language the content is in
`--content-length int`Size of the body in bytes
`--content-md5 string`Base64-encoded 128-bit MD5 digest for an integrity check
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--expires string`Date/time the object is no longer cacheable (RFC3339)
`--grant-full-control string`Grants READ, READ\_ACP, and WRITE\_ACP permissions on the object
`--grant-read string`Allows grantee to read the object and its metadata
`--grant-read-acp string`Allows grantee to read the object ACL
`--grant-write-acp string`Allows grantee to write the object ACL
`--if-match string`Upload only if the provided ETag matches the existing object
`--if-none-match string`Upload only if the object key does not already exist
`--object-lock-legal-hold-status string`Whether a legal hold applies to the object (`ON` | `OFF`)
`--object-lock-mode string`Object Lock mode to apply to the object (`GOVERNANCE` | `COMPLIANCE`)
`--object-lock-retain-until-date string`When the object's Object Lock expires (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--server-side-encryption string`Server-side encryption algorithm to use (`AES256` | `aws:kms` | `aws:kms:dsse`)
`--sse-customer-algorithm string`Algorithm to use when encrypting the object (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
`--ssekms-encryption-context string`Base64-encoded KMS encryption context for the object
`--ssekms-key-id string`KMS key ID to use for object encryption
`--storage-class string`Storage class for the object. Default: `STANDARD`
`--website-redirect-location string`Redirect requests for this object to another object or URL
`--write-offset-bytes int`Offset for appending data to an existing object
### Examples ```bash theme={null} nscale s3api put-object --bucket my-bucket --key data.csv --body ./data.csv --content-type text/csv # Stream from another command tar -cz ./results | nscale s3api put-object --bucket my-bucket --key results.tar.gz --body - # Store metadata and tags with the object nscale s3api put-object --bucket my-bucket --key report.pdf --body ./report.pdf \ --metadata 'owner=data-team' --tagging 'env=prod&team=data' ``` *** ## get-object Download an object. Without `--outfile`, or with `--outfile -`, the object streams to stdout and nothing else is printed. With `--outfile`, the object is written to that file and the response metadata is printed as JSON. `--json` and `-q` require `--outfile`. ```bash theme={null} nscale s3api get-object --bucket --key [--outfile ] [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket containing the object
`--key string`**Required.** The key of the object to get
`--outfile string`Path to write the object to; `-` or omitted streams to stdout
`--part-number int32`Part number of the object being read
`--range string`Download only the specified byte range of the object
`--version-id string`Reference a specific version of the object
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--checksum-mode string`Enable checksum retrieval (`ENABLED`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--if-match string`Return the object only if its ETag matches this value
`--if-modified-since string`Return the object only if modified since this time (RFC3339)
`--if-none-match string`Return the object only if its ETag differs from this value
`--if-unmodified-since string`Return the object only if not modified since this time (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--response-cache-control string`Sets the Cache-Control header of the response
`--response-content-disposition string`Sets the Content-Disposition header of the response
`--response-content-encoding string`Sets the Content-Encoding header of the response
`--response-content-language string`Sets the Content-Language header of the response
`--response-content-type string`Sets the Content-Type header of the response
`--response-expires string`Sets the Expires header of the response (RFC3339)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Examples ```bash theme={null} nscale s3api get-object --bucket my-bucket --key data.csv --outfile ./data.csv # Stream to another command nscale s3api get-object --bucket my-bucket --key data.csv | head # Download the first kilobyte of a specific version nscale s3api get-object --bucket my-bucket --key data.csv --version-id --range bytes=0-1023 --outfile ./head.csv ``` *** ## head-object Get an object's metadata, such as its size, ETag, content type, and user metadata, without downloading it. ```bash theme={null} nscale s3api head-object --bucket --key [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket containing the object
`--key string`**Required.** The object key
`--part-number int32`Part number of the object being read
`--range string`HTTP Range header for the requested byte range
`--version-id string`Reference a specific version of the object
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--checksum-mode string`Enable checksum retrieval (`ENABLED`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--if-match string`Return the object only if its ETag matches this value
`--if-modified-since string`Return the object only if modified since this time (RFC3339)
`--if-none-match string`Return the object only if its ETag differs from this value
`--if-unmodified-since string`Return the object only if not modified since this time (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--response-cache-control string`Sets the Cache-Control header of the response
`--response-content-disposition string`Sets the Content-Disposition header of the response
`--response-content-encoding string`Sets the Content-Encoding header of the response
`--response-content-language string`Sets the Content-Language header of the response
`--response-content-type string`Sets the Content-Type header of the response
`--response-expires string`Sets the Expires header of the response (RFC3339)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Example ```bash theme={null} nscale s3api head-object --bucket my-bucket --key data.csv -q '.ContentLength' ``` *** ## copy-object Copy an object that is already stored in object storage. `--copy-source` names the source as `bucket/key`, optionally with `?versionId=`; pass the key unencoded, since the CLI URL-encodes it for you. ```bash theme={null} nscale s3api copy-object --bucket --key --copy-source [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The destination bucket
`--copy-source string`**Required.** The source object as `bucket/key[?versionId=...]`, given raw/unencoded — the key is URL-encoded for you
`--key string`**Required.** The key of the destination object
`--content-type string`Standard MIME type describing the object data
`--metadata string`Metadata to store with the object, as JSON or `key=value` pairs (with `--metadata-directive REPLACE`)
`--tagging string`Tag-set for the destination object, URL query encoded
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--acl string`Canned ACL to apply to the object
`--bucket-key-enabled`Toggle an S3 Bucket Key for SSE-KMS encryption
`--cache-control string`Caching behaviour along the request/reply chain
`--checksum-algorithm string`Algorithm S3 uses to create the object checksum
`--content-disposition string`Presentational information for the object
`--content-encoding string`Content encodings applied to the object
`--content-language string`The language the content is in
`--copy-source-if-match string`Copy only if the source ETag matches this value
`--copy-source-if-modified-since string`Copy only if the source was modified since this time (RFC3339)
`--copy-source-if-none-match string`Copy only if the source ETag differs from this value
`--copy-source-if-unmodified-since string`Copy only if the source was not modified since this time (RFC3339)
`--copy-source-sse-customer-algorithm string`Algorithm to use when decrypting the source object (SSE-C)
`--copy-source-sse-customer-key string`Customer-provided key to decrypt the source object (SSE-C)
`--copy-source-sse-customer-key-md5 string`128-bit MD5 digest of the source SSE-C key
`--expected-bucket-owner string`Account ID of the expected destination bucket owner
`--expected-source-bucket-owner string`Account ID of the expected source bucket owner
`--expires string`Date/time the object is no longer cacheable (RFC3339)
`--grant-full-control string`Grants READ, READ\_ACP, and WRITE\_ACP permissions on the object
`--grant-read string`Allows grantee to read the object and its metadata
`--grant-read-acp string`Allows grantee to read the object ACL
`--grant-write-acp string`Allows grantee to write the object ACL
`--if-match string`Copy only if the destination object ETag matches this value
`--if-none-match string`Copy only if the destination key does not already exist
`--metadata-directive string`Whether metadata is copied from the source or replaced (`COPY` | `REPLACE`)
`--object-lock-legal-hold-status string`Whether a legal hold applies to the copy (`ON` | `OFF`)
`--object-lock-mode string`Object Lock mode to apply to the copy (`GOVERNANCE` | `COMPLIANCE`)
`--object-lock-retain-until-date string`When the copy's Object Lock expires (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--server-side-encryption string`Server-side encryption algorithm to use (`AES256` | `aws:kms` | `aws:kms:dsse`)
`--sse-customer-algorithm string`Algorithm to use when encrypting the destination object (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
`--ssekms-encryption-context string`Base64-encoded KMS encryption context for the destination object
`--ssekms-key-id string`KMS key ID to use for object encryption
`--storage-class string`Storage class for the copied object
`--tagging-directive string`Whether the tag-set is copied from the source or replaced (`COPY` | `REPLACE`)
`--website-redirect-location string`Redirect requests for this copy to another object or URL
### Examples ```bash theme={null} nscale s3api copy-object --bucket backup-bucket --key data.csv --copy-source my-bucket/data.csv # Replace the metadata on the copy nscale s3api copy-object --bucket my-bucket --key data.csv --copy-source my-bucket/data.csv \ --metadata-directive REPLACE --content-type text/csv --metadata 'owner=data-team' ``` *** ## delete-object Delete an object. In a versioned bucket, this adds a delete marker unless you pass `--version-id` to delete a specific version. ```bash theme={null} nscale s3api delete-object --bucket --key [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket containing the object
`--key string`**Required.** The key of the object to delete
`--version-id string`Reference a specific version of the object
`-y, --yes`Automatically confirm object deletion
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > >
FlagDescription
`--bypass-governance-retention`Bypass Governance-mode Object Lock restrictions
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--if-match string`Delete only if the object's ETag matches this value
`--if-match-last-modified-time string`Delete only if the object's last-modified time matches this value (RFC3339)
`--if-match-size int`Delete only if the object size matches this many bytes
`--mfa string`MFA device serial number and code for versioned deletes
`--request-payer string`Confirms the requester will be charged (`requester`)
### Examples ```bash theme={null} nscale s3api delete-object --bucket my-bucket --key data.csv --yes nscale s3api delete-object --bucket my-bucket --key data.csv --version-id --yes ``` *** ## delete-objects Delete multiple objects from a bucket in a single request. `--delete` takes JSON in the SDK `Delete` shape, or a `file://` reference to it. ```bash theme={null} nscale s3api delete-objects --bucket --delete [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket containing the objects
`--delete string`**Required.** Objects to delete, as JSON matching the SDK Delete shape or a `file://` reference
`-y, --yes`Automatically confirm object deletion
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > >
FlagDescription
`--bypass-governance-retention`Bypass Governance-mode Object Lock restrictions
`--checksum-algorithm string`Algorithm used to create the object checksum (`CRC32` | `CRC32C` | `CRC64NVME` | `SHA1` | `SHA256`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--mfa string`MFA device serial number and code for versioned deletes
`--request-payer string`Confirms the requester will be charged (`requester`)
### Examples ```bash theme={null} nscale s3api delete-objects --bucket my-bucket --delete '{"Objects":[{"Key":"a.csv"},{"Key":"b.csv"}]}' --yes nscale s3api delete-objects --bucket my-bucket --delete file://delete.json --yes ``` *** ## presign Generate a pre-signed URL that lets anyone who holds it download the object with a plain HTTP GET until it expires. This is the equivalent of `aws s3 presign`. See [Share objects with pre-signed URLs](/docs/storage/object-storage#share-objects-with-pre-signed-urls) for guidance on using them safely. The URL is signed locally with the resolved credentials, so it stops working early if the access key is deleted or temporary credentials expire. The command prints the bare URL; `--json` and `-q` return it together with its expiry time as `URL` and `ExpiresAt`. ```bash theme={null} nscale s3api presign s3:/// [flags] ``` ### Flags
FlagDescription
`--expires-in int`Number of seconds until the pre-signed URL expires (max 604800). Default: `3600`
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} # Valid for 1 hour (the default) nscale s3api presign s3://my-bucket/report.pdf # Valid for 7 days, the maximum nscale s3api presign s3://my-bucket/report.pdf --expires-in 604800 # Download with the URL, no credentials required curl -fSL -o report.pdf "$(nscale s3api presign s3://my-bucket/report.pdf)" ``` *** ## get-object-tagging Get the tag-set of an object. ```bash theme={null} nscale s3api get-object-tagging --bucket --key [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--key string`**Required.** Object key to get the tagging for
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--request-payer string`Confirms the requester will be charged (`requester`)
`--version-id string`Version ID of the object
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api get-object-tagging --bucket my-bucket --key data.csv -q '.TagSet' ``` *** ## put-object-tagging Set the tag-set of an object, replacing any existing tags. Pass the tags as `key=value` pairs with `--tags`, or as JSON in the SDK `Tagging` shape with `--tagging`. Use `--tagging` when a value contains a comma. ```bash theme={null} nscale s3api put-object-tagging --bucket --key (--tags | --tagging ) [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--key string`**Required.** Name of the object key
`--tagging string`Tag-set, as JSON matching the SDK Tagging shape or a `file://` reference; required unless `--tags` is given
`--tags string`Tag-set shorthand as `key=value` pairs, or a `file://` reference to them; an alternative to `--tagging`. Use `--tagging` for values that contain a comma
`--version-id string`Version ID the tag-set is added to
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > >
FlagDescription
`--checksum-algorithm string`Algorithm used to create the request checksum (`CRC32` | `CRC32C` | `CRC64NVME` | `SHA1` | `SHA256`)
`--content-md5 string`MD5 hash for the request body
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--request-payer string`Confirms the requester will be charged (`requester`)
### Examples ```bash theme={null} nscale s3api put-object-tagging --bucket my-bucket --key data.csv --tags 'env=prod,team=data' nscale s3api put-object-tagging --bucket my-bucket --key data.csv --tagging '{"TagSet":[{"Key":"env","Value":"prod"}]}' ``` *** ## delete-object-tagging Remove the entire tag-set from an object. ```bash theme={null} nscale s3api delete-object-tagging --bucket --key [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The name of the bucket
`--key string`**Required.** Key identifying the object to remove tags from
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--version-id string`Version ID the tag-set is removed from
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api delete-object-tagging --bucket my-bucket --key data.csv ``` *** ## create-multipart-upload Start a multipart upload and return its `UploadId`. Upload the parts with [`upload-part`](#upload-part) or [`upload-part-copy`](#upload-part-copy), then assemble them with [`complete-multipart-upload`](#complete-multipart-upload). The object's metadata, tags, and storage class are set here, not when the upload completes. ```bash theme={null} nscale s3api create-multipart-upload --bucket --key [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket to create the object in
`--key string`**Required.** The object key
`--content-type string`Standard MIME type describing the content format
`--metadata string`Metadata to store with the object, as JSON or `key=value` pairs (or a `file://` reference)
`--tagging string`Tag-set for the object, URL query encoded
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--acl string`Canned ACL to apply to the object
`--bucket-key-enabled`Toggle an S3 Bucket Key for SSE-KMS encryption
`--cache-control string`Caching behaviour along the request/reply chain
`--checksum-algorithm string`Algorithm used to create the object checksum
`--checksum-type string`How the object checksum is calculated across parts (`COMPOSITE` | `FULL_OBJECT`)
`--content-disposition string`Presentational information for the object
`--content-encoding string`Content encodings applied to the object
`--content-language string`The language the content is in
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--expires string`Date/time the object is no longer cacheable (RFC3339)
`--grant-full-control string`Grants READ, READ\_ACP, and WRITE\_ACP permissions on the object
`--grant-read string`Allows grantee to read the object and its metadata
`--grant-read-acp string`Allows grantee to read the object ACL
`--grant-write-acp string`Allows grantee to write the object ACL
`--object-lock-legal-hold-status string`Whether a legal hold applies to the object (`ON` | `OFF`)
`--object-lock-mode string`Object Lock mode to apply to the object (`GOVERNANCE` | `COMPLIANCE`)
`--object-lock-retain-until-date string`When the object's Object Lock expires (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--server-side-encryption string`Server-side encryption algorithm to use (`AES256` | `aws:kms` | `aws:kms:dsse`)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
`--ssekms-encryption-context string`Base64-encoded KMS encryption context for the object
`--ssekms-key-id string`KMS key ID to use for object encryption
`--storage-class string`Storage class for the object. Default: `STANDARD`
`--website-redirect-location string`Redirect requests for this object to another object or URL
### Example ```bash theme={null} UPLOAD_ID=$(nscale s3api create-multipart-upload --bucket my-bucket --key large.bin -q '.UploadId') ``` *** ## upload-part Upload one part of a multipart upload. Part numbers run from 1 to 10000. The body streams from the file named by `--body`, or from stdin with `--body -`. Keep the `ETag` from each response: [`complete-multipart-upload`](#complete-multipart-upload) needs it. ```bash theme={null} nscale s3api upload-part --bucket --key --upload-id --part-number --body [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The target bucket
`--key string`**Required.** The object key
`--part-number int32`**Required.** The part number, between 1 and 10000
`--upload-id string`**Required.** The ID identifying the multipart upload
`--body string`Path to the part data; `-` reads from stdin (streamed, not buffered); omitted uploads an empty part
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--checksum-algorithm string`Algorithm used to create the part checksum
`--checksum-crc32 string`Base64 CRC32 checksum for data integrity
`--checksum-crc32-c string`Base64 CRC32C checksum for data integrity
`--checksum-crc64-nvme string`Base64 CRC64NVME checksum for data integrity
`--checksum-sha1 string`Base64 SHA1 checksum for data integrity
`--checksum-sha256 string`Base64 SHA256 checksum for data integrity
`--content-length int`Size of the body in bytes
`--content-md5 string`Base64-encoded 128-bit MD5 digest for an integrity check
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--request-payer string`Confirms the requester will be charged (`requester`)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the create-multipart-upload request
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Example ```bash theme={null} nscale s3api upload-part --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \ --part-number 1 --body ./large.bin.part1 -q '.ETag' ``` *** ## upload-part-copy Upload one part of a multipart upload by copying data from an existing object. Use `--copy-source-range` to copy only part of the source object. ```bash theme={null} nscale s3api upload-part-copy --bucket --key --upload-id --part-number --copy-source [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The destination bucket
`--copy-source string`**Required.** The source object as `bucket/key[?versionId=...]`, given raw/unencoded — the key is URL-encoded for you
`--key string`**Required.** The key of the destination object
`--part-number int32`**Required.** The part number, between 1 and 10000
`--upload-id string`**Required.** The ID identifying the multipart upload
`--copy-source-range string`The byte range of the source object to copy
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--copy-source-if-match string`Copy only if the source ETag matches this value
`--copy-source-if-modified-since string`Copy only if the source was modified since this time (RFC3339)
`--copy-source-if-none-match string`Copy only if the source ETag differs from this value
`--copy-source-if-unmodified-since string`Copy only if the source was not modified since this time (RFC3339)
`--copy-source-sse-customer-algorithm string`Algorithm to use when decrypting the source object (SSE-C)
`--copy-source-sse-customer-key string`Customer-provided key to decrypt the source object (SSE-C)
`--copy-source-sse-customer-key-md5 string`128-bit MD5 digest of the source SSE-C key
`--expected-bucket-owner string`Account ID of the expected destination bucket owner
`--expected-source-bucket-owner string`Account ID of the expected source bucket owner
`--request-payer string`Confirms the requester will be charged (`requester`)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C)
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Example ```bash theme={null} nscale s3api upload-part-copy --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \ --part-number 2 --copy-source my-bucket/source.bin --copy-source-range bytes=0-104857599 ``` *** ## list-parts List the parts uploaded so far for a multipart upload. ```bash theme={null} nscale s3api list-parts --bucket --key --upload-id [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket the multipart upload targets
`--key string`**Required.** The object key of the multipart upload
`--upload-id string`**Required.** The ID identifying the multipart upload
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--part-number-marker string`Part number after which listing begins
`--starting-token string`Pagination token marking where a previous listing should resume
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > >
FlagDescription
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--request-payer string`Confirms the requester will be charged for the request (`requester`)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the create-multipart-upload request
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Example ```bash theme={null} nscale s3api list-parts --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \ -q '.Parts[]?.PartNumber' -q '.Parts[]?.ETag' ``` *** ## list-multipart-uploads List the multipart uploads in a bucket that have started but not yet been completed or aborted. Incomplete uploads keep their parts stored until you abort them. ```bash theme={null} nscale s3api list-multipart-uploads --bucket [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket to list multipart uploads from
`--delimiter string`Character used to group keys into common prefixes
`--encoding-type string`Encoding used for object keys in the response (`url`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--key-marker string`Key to start listing from
`--max-items int32`Total number of items to return across all pages
`--page-size int32`Number of items to request per service call
`--prefix string`Limit the response to keys that begin with this prefix
`--request-payer string`Confirms the requester will be charged for the request (`requester`)
`--starting-token string`Pagination token marking where a previous listing should resume
`--upload-id-marker string`Upload ID to start listing from (used with `--key-marker`)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api list-multipart-uploads --bucket my-bucket -q '.Uploads[]?.Key' -q '.Uploads[]?.UploadId' ``` *** ## complete-multipart-upload Complete a multipart upload by assembling its parts into one object. `--multipart-upload` lists every part by `PartNumber` and `ETag`, as JSON in the SDK `CompletedMultipartUpload` shape or a `file://` reference to it. The quickest way to build it is from [`list-parts`](#list-parts). ```bash theme={null} nscale s3api complete-multipart-upload --bucket --key --upload-id --multipart-upload [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The target bucket
`--key string`**Required.** The object key
`--multipart-upload string`**Required.** The parts to assemble, as JSON or a `file://` reference
`--upload-id string`**Required.** The ID identifying the multipart upload
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
> **Advanced flags** > > > > > > > > > > > > > > > > > > > > >
FlagDescription
`--checksum-crc32 string`Base64 CRC32 checksum of the full object
`--checksum-crc32-c string`Base64 CRC32C checksum of the full object
`--checksum-crc64-nvme string`Base64 CRC64NVME checksum of the full object
`--checksum-sha1 string`Base64 SHA1 checksum of the full object
`--checksum-sha256 string`Base64 SHA256 checksum of the full object
`--checksum-type string`How the object checksum is calculated across parts (`COMPOSITE` | `FULL_OBJECT`)
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--if-match string`Complete only if the existing object's ETag matches this value
`--if-none-match string`Complete only if the object key does not already exist
`--mpu-object-size int`Expected total size of the assembled object in bytes
`--request-payer string`Confirms the requester will be charged (`requester`)
`--sse-customer-algorithm string`Algorithm to use when encrypting/decrypting with a customer-provided key (SSE-C); must match the upload-part requests
`--sse-customer-key string`Customer-provided encryption key (SSE-C)
`--sse-customer-key-md5 string`128-bit MD5 digest of the SSE-C encryption key
### Examples ```bash theme={null} # Build the parts list from the uploaded parts nscale s3api list-parts --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \ -q '{Parts: [.Parts[]? | {ETag, PartNumber}]}' > parts.json nscale s3api complete-multipart-upload --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" \ --multipart-upload file://parts.json ``` *** ## abort-multipart-upload Abort a multipart upload and discard the parts uploaded so far. ```bash theme={null} nscale s3api abort-multipart-upload --bucket --key --upload-id [flags] ``` ### Flags
FlagDescription
`--bucket string`**Required.** The bucket the multipart upload targets
`--key string`**Required.** The object key of the multipart upload
`--upload-id string`**Required.** The ID identifying the multipart upload to abort
`--expected-bucket-owner string`Account ID of the expected bucket owner
`--if-match-initiated-time string`Abort only if the upload was initiated at this time (RFC3339)
`--request-payer string`Confirms the requester will be charged (`requester`)
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale s3api abort-multipart-upload --bucket my-bucket --key large.bin --upload-id "$UPLOAD_ID" ``` *** ## Related > **[Object Storage (CLI)](/docs/cli/object-storage)** > > Manage object storage endpoints, identity policies, and access keys. > **[Object Storage (Console)](/docs/storage/object-storage)** > > Create and manage object storage via the Console UI. # Security groups Source: https://docs.nscale.com/docs/cli/securitygroups Manage security groups for controlling network access to instances. Security groups act as virtual firewalls, controlling inbound and outbound traffic for compute instances. **Aliases:** `securitygroups`, `sg` Commands that act on one security group take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List security groups * [get](#get) — Get security group details * [create](#create) — Create a new security group * [update](#update) — Update an existing security group * [delete](#delete) — Delete a security group *** ## list List security groups, optionally filtered by organization, project, network, or region. ```bash theme={null} nscale securitygroups list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--network string`Network ID
`--region string`Region ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale securitygroups list --org --region ``` *** ## get Get details for a specific security group. ```bash theme={null} nscale securitygroups get --org ``` ### Flags
FlagDescription
`--id string`Security group ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new security group. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the security group details and rules. ```bash theme={null} nscale securitygroups create [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale securitygroups create --file securitygroup.json nscale securitygroups create --stdin < securitygroup.json cat securitygroup.json | nscale securitygroups create --stdin ``` *** ## update Update an existing security group. Accepts input from a JSON file or stdin; with neither, the CLI prompts for each field, pre-filled from the security group as it stands. ```bash theme={null} nscale securitygroups update [flags] ``` ### Flags
FlagDescription
`--id string`Security group ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale securitygroups update --file securitygroup.json nscale securitygroups update --stdin < securitygroup.json cat securitygroup.json | nscale securitygroups update --stdin ``` *** ## delete Delete an existing security group. ```bash theme={null} nscale securitygroups delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Security group ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | ### Example ```bash theme={null} nscale securitygroups delete --yes ``` *** ## Related > **[Instances (Console)](/docs/compute/create-new-instances)** > > Security groups are configured during instance creation. > **[Load balancers (CLI)](/docs/cli/load-balancers)** > > Load balancers expose services on a network; restrict listener sources with allowed CIDRs. # Service accounts Source: https://docs.nscale.com/docs/cli/serviceaccounts Manage service accounts and their access tokens. Service accounts provide machine-to-machine authentication for CI/CD pipelines and automated workflows. Once created, their tokens can be passed via the `NSCALE_SERVICE_TOKEN` environment variable. **Aliases:** `serviceaccounts`, `sa` Commands that act on one service account take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List service accounts * [get](#get) — Get service account details * [create](#create) — Create a new service account * [update](#update) — Update an existing service account * [rotate](#rotate) — Rotate a service account token * [delete](#delete) — Delete a service account *** ## list List service accounts in an organization. ```bash theme={null} nscale serviceaccounts list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## get Get details for a specific service account. ```bash theme={null} nscale serviceaccounts get --org ``` ### Flags
FlagDescription
`--id string`Service account ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new service account. Supports interactive mode or JSON input. ```bash theme={null} nscale serviceaccounts create --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale serviceaccounts create --org --file serviceaccount.json nscale serviceaccounts create --org --stdin < serviceaccount.json cat serviceaccount.json | nscale serviceaccounts create --org --stdin # Interactive mode nscale serviceaccounts create ``` *** ## update Update an existing service account. ```bash theme={null} nscale serviceaccounts update --org [flags] ``` ### Flags
FlagDescription
`--id string`Service account ID
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm update
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale serviceaccounts update --org --file serviceaccount.json nscale serviceaccounts update --org --stdin < serviceaccount.json cat serviceaccount.json | nscale serviceaccounts update --org --stdin # Interactive mode nscale serviceaccounts update ``` *** ## rotate Rotate the access token for a service account. The old token is invalidated and a new one is returned. ```bash theme={null} nscale serviceaccounts rotate --org [flags] ``` ### Flags
FlagDescription
`--id string`Service account ID
`--org string`Organization ID
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm token rotation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale serviceaccounts rotate --org --yes ``` *** ## delete Delete an existing service account. ```bash theme={null} nscale serviceaccounts delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | Service account ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | *** ## Related > **[Service Tokens (Console)](/docs/manage/service-tokens)** > > Generate and manage service tokens via the Console UI. # SSH certificate authorities Source: https://docs.nscale.com/docs/cli/ssh-cas Manage SSH certificate authorities used to sign instance SSH host keys. SSH certificate authorities (CAs) let you sign the host keys used by your compute instances so clients can trust them without manually pinning fingerprints. Once a CA is created, you can bind it to an instance via [`nscale instances create --ssh-ca-id`](/docs/cli/instances#create). **Aliases:** `ssh-cas`, `sshca` Commands that act on one SSH certificate authority take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List SSH certificate authorities * [get](#get) — Get SSH certificate authority details * [create](#create) — Create a new SSH certificate authority * [delete](#delete) — Delete an SSH certificate authority *** ## list List SSH certificate authorities, optionally filtered by organization or project. ```bash theme={null} nscale ssh-cas list [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--project string`Project ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale ssh-cas list --org ``` *** ## get Get details for a specific SSH certificate authority. ```bash theme={null} nscale ssh-cas get --org ``` ### Flags
FlagDescription
`--id string`SSH certificate authority ID
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
*** ## create Create a new SSH certificate authority. Accepts input from a JSON file or stdin; with neither, the CLI prompts for the name, project, and public key. ```bash theme={null} nscale ssh-cas create [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`-f, --file string`Path to a JSON file
`--stdin`Read JSON from standard input
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm creation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale ssh-cas create --file sshca.json nscale ssh-cas create --stdin < sshca.json cat sshca.json | nscale ssh-cas create --stdin ``` *** ## delete Delete an existing SSH certificate authority. ```bash theme={null} nscale ssh-cas delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | SSH certificate authority ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | *** ## Related > **[Instances](/docs/cli/instances)** > > Bind a certificate authority when creating an instance with `--ssh-ca-id`. # Users Source: https://docs.nscale.com/docs/cli/users Manage the users of an organization. Users are the individual accounts with access to an organization. Membership starts with an invitation, and what a user can do is determined by the [groups](/docs/cli/groups) they belong to. Commands that act on one user take its ID either as a positional argument or with `--id`. If you omit it, the CLI opens an interactive picker, so always pass it in scripts. ## Subcommands * [list](#list) — List users * [invite](#invite) — Invite a user * [delete](#delete) — Delete a user *** ## list List users in an organization, along with their state and the number of groups each belongs to. **Aliases:** `list`, `ls` ```bash theme={null} nscale users list --org [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Example ```bash theme={null} nscale users list --org --json ``` *** ## invite Invite a user into an organization. A user is identified by their canonical name, which is usually an email address. Whether groups are accepted depends on how the organization authenticates its members: * **Private organizations** — members are added explicitly, so at least one group is required. Omit `--group` and the CLI presents a group picker. * **Public organizations** — members sign in with an email address on the organization's domain, and group membership is managed separately, so `--group` is rejected. To check which kind an organization is, read its type — `adhoc` for private, `domain` for public: ```bash theme={null} nscale organizations list -q ".[].metadata.name" -q ".[].spec.organizationType" ``` Use [`nscale groups list`](/docs/cli/groups#list) to discover the group IDs. For how groups and roles fit together, see [Groups and roles](/docs/manage/roles-and-groups). `--state` sets the state of the user's **membership of this organization**, which is what governs their access to it: * `pending` (the default) matches the Console flow — the member is listed as Pending and has no access until they join. * `active` skips that step, so the membership is usable as soon as the person can sign in. * `suspended` creates the membership with access already revoked. > [!NOTE] > > `--state active` does not bypass account sign-up. If the person has no Nscale account yet, they must still complete the verification email before they can authenticate; the flag only decides whether their membership of this organization is waiting on them to join. ```bash theme={null} nscale users invite --org --email [flags] ``` ### Flags
FlagDescription
`--org string`Organization ID
`--email string`The user's canonical name, usually an email address
`--group stringArray`Group ID to add the user to (repeatable)
`--state string`Membership state — `active`, `pending`, or `suspended` (default `pending`)
`--dry-run`Preview actions and payload without persisting
`-y, --yes`Automatically confirm the invitation
`--json` Emit the full JSON payload (mutually exclusive with `-q`)
`-q, --query stringArray` jq filter for value extraction (see [Query output with `-q`](/docs/cli/query-output))
### Examples ```bash theme={null} nscale users invite --org --email user@example.com nscale users invite --org --email user@example.com --group --group # Interactive mode nscale users invite ``` *** ## delete Delete an existing user from an organization. ```bash theme={null} nscale users delete --org [flags] ``` ### Flags | Flag | Description | | - | - | | `--id string` | User ID | | `--org string` | Organization ID | | `--dry-run` | Preview actions and payload without persisting | | `-y, --yes` | Automatically confirm deletion | # Version Source: https://docs.nscale.com/docs/cli/version Display the current version of the CLI. Display the currently installed version of the CLI. ```bash theme={null} nscale version ``` # Clusters Source: https://docs.nscale.com/docs/compute/clusters This guide provides step-by-step instructions to help users create, manage, and monitor virtual machines within the Clusters. It covers how to select VM configurations, choose system images, connect to project-level networks, and perform lifecycle actions. The guide is designed to support new users in getting started quickly and using the Nscale platform effectively. > [!WARNING] > > **Compute clusters have been removed.** The cluster API and console UI have been fully removed. Use [instances](/docs/compute/create-new-instances) to provision individual virtual machines or bare-metal nodes, or manage instances via the [CLI](/docs/cli/instances). > [!NOTE] > > This page is preserved for reference only. All cluster workflows have been replaced by the [instances](/docs/compute/create-new-instances) model. ## Introduction ### **Cluster Service – Introduction** The Cluster Service allows users to provision on-demand compute clusters composed of virtual machines or bare metal nodes. Designed for AI, ML, and general-purpose workloads, it provides a streamlined way to deploy and manage multiple instances through a unified UI and API. Networking, storage, and image management are abstracted and handled by the platform, so users can focus on running workloads without managing infrastructure complexity. ### **Benefits of the Cluster Service** * **No networking complexity:** Instances are auto-connected within a shared project network. * **Easy provisioning:** Minimal configuration via a single pane of glass covering compute, networking, and storage. * **Use only what you need:** Fractional flavours reduce cost for inference, testing, and right-sized workloads. * **Run GPU workloads out of the box:** Images suitable for GPU workloads are available and ready to use, or you can bring your own image. * **Full control over lifecycle:** Start, stop, and delete instances without requiring orchestration tools. * **OS-level access:** SSH into cluster nodes to configure and operate the system directly, using the credentials provided when the cluster is created. ## Architecture This diagram illustrates two high-level deployment models for compute infrastructure: ![image.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/image.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=5b877175c5be2582cff358f292a48c55) * **Left Side: Virtualised Architecture** Compute resources are virtualised using a hypervisor running on top of a host OS. Virtual machines (VMs) are provisioned for CPU or GPU workloads. GPU VMs include a guest OS with CUDA support to enable accelerated computing. * **Right Side: Bare-Metal Architecture** Applications run directly on the host OS without a virtualisation layer. CUDA is installed at the host level, providing direct access to GPU resources for maximum performance. ## Cluster Provisioning To create a new cluster, navigate to the **Clusters** section under **Compute** on the left menu. ![compute\_cluster\_selection.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/compute_cluster_selection.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=6e9f40a482c04cca254b9c140e848e92) Select **Create new resource**. ![cluster\_new.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_new.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=5d3eb642e22fc8a75cad7e8dac58fd34) Provide a name, select a project, and choose the deployment region. If you're unsure which project to use, see [Projects](/docs/manage/projects) for guidance on how projects group your resources. In the next step, define the **workload pool configuration**: * Set the pool name using alphanumeric characters and hyphens. ![cluster\_set\_up\_1.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_set_up_1.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=e6730efb13101aca01c48229fb11b788) * Select the desired **node type**. ![cluster\_set\_up\_2.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_set_up_2.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=2048967d8822aa92f7bc2ab0caa53e88) * Enable **persistent storage** and specify the desired volume size. * Choose the **operating system version** and define the **number of replicas**. * Enable or disable **public IP exposure** as needed. * Configure **firewall rules** to control inbound access (e.g., allow SSH on port 22). ![cluster\_set\_up\_3.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_set_up_3.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=096f83d5ad3722d7956f54aacfa4280e) * Optionally, you can provide a **cloud-init configuration** to run custom setup scripts during the first boot of each node. ![cluster\_set\_up\_4-cloud\_init.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_set_up_4-cloud_init.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=7f5a697c2a810a167e33b840c29b22d4) * Once the configuration is completed, review the cluster and provision it. When provisioning is complete, the cluster status will be set to ‘**Provisioned’**, and connection details, including the SSH private key and workload pool IP addresses, will be available in the cluster overview. ![cluster\_set\_up\_5.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/cluster_set_up_5.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=1524ac3b8720909ba80d23ebc4bee49f) ## Monitoring and observability Users can monitor resource utilisation directly from the operating system using the Interactive Process Viewer `htop`. ``` htop ``` More information can be found in [GitHub-htop](https://github.com/htop-dev/htop?utm_source=chatgpt.com) ![htop.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/htop.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=f1cd759551727aac7bcbd29d671d8f6a) ## Create a new pool on the existing cluster Once inside the cluster, open the **Workload Pools** tab. Use the **“+ Add Pool”** button to start a new pool configuration. ![Screenshot from 2025-10-06 11-18-40.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0611-18-40.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=26ef8cd21a628ea178ba287883237319) Once you are in the cluster, use the **“+ Add Workload Pool”** button to start the new pool configuration. ![Screenshot from 2025-10-06 11-19-59.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0611-19-59.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=86a90e2df204fb646e7481b310e46673) Define the name, base image, instance type, replica count, and any required firewall rules, following the steps outlined in the **Cluster Provisioning** section. Finalise by selecting **Create**. The new pool will appear in the list as provisioned. ![Screenshot from 2025-10-06 13-43-07.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-43-07.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=946ca9c7ae1b09a83e27e4c4a773acc0) ## Evicting a VM from an existing pool It is possible to evict a Virtual Machine from an existing pool. This process does not automatically migrate any existing workloads from the evicted VM to other Virtual Machines in the pool. The user has to manage the workload before eviction manually. Select the VM to evict from the pool by clicking the three dots on the right. ![Screenshot from 2025-10-06 13-50-39.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-50-39.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=1821fd71cdaae251d76ce3abf3d820a8) After a short while, the VM will be removed from the pool, its resources returned to the available resource pool, and any public IP associated with the VM will be released. This process will also delete any data stored on ephemeral storage. To retain data, persistent storage must be configured separately. ![Screenshot from 2025-10-06 13-51-56.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-51-56.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=1dc1f6d7f65239b155c1b17a6d50567a) The pool should now show that only 3 Virtual Machines remain active out of the 3 originally in the pool. ![Screenshot from 2025-10-06 13-52-31.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-52-31.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=e0ed09889fc1bc47fac6c14e548c6e2c) ## Deleting a pool from an existing cluster This process operates at a higher level than deleting a single VM. The user does not need to evict the VMs individually. Once the pool is deleted, all VMs within it will also be evicted automatically. All associated resources, including ephemeral data and public IPs, will be released from the cluster. Users must ensure that any data they wish to retain is saved to persistent volumes beforehand. Select the pool you want to delete. Click the three-dot menu on the right and choose **Delete Pool**. ![Screenshot from 2025-10-06 13-49-11.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-49-11.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=42804c1dad600b5e43a2dcf0ff162646) To confirm the delete operation, enter the name of the pool in the confirmation panel. ![Screenshot from 2025-10-06 13-53-35.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-53-35.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=0e535b63666aeaaa5d9944d9c9fdd9fe) The selected pool is not part of the cluster. ![Screenshot from 2025-10-06 13-54-33.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-54-33.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=8464b94c138ea79629615e5683c1ffe0) ## Delete a cluster The cluster `user-guide-test` contains one or more workload pools with running Virtual Machines. Before initiating the deletion process, ensure that any data that needs to persist is stored in a persistent volume. Ephemeral data will be permanently deleted. In the **Workload Pools** tab, click the green **Provisioned** button in the top-right corner of the cluster view.\ Select **Delete cluster** from the dropdown menu to begin the deletion process. ![Screenshot from 2025-10-06 13-55-08.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-55-08.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=72d89367c21589033430df2b97a13340) Deleting a cluster will **permanently remove all resources associated with it**, including: * All workload pools * All Virtual Machines * Any ephemeral storage * Any assigned public IPs\ All resources will be evicted and released back to the shared resource pool. A confirmation panel appears. To confirm the operation, enter the name of the cluster in the dialogue box. Once the deletion is initiated, the cluster status changes to **Deprovisioning**.\ When the process completes, the cluster is removed from the **Compute Clusters** list and all associated resources are fully deallocated. ![Screenshot from 2025-10-06 13-56-15.png](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshotfrom2025-10-0613-56-15.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=f3d9e7026461396a78fb8f76eb94f327) # Instances Source: https://docs.nscale.com/docs/compute/create-new-instances An instance is a virtual machine running on Nscale GPU or CPU infrastructure. It lives inside a VPC, is protected by a security group, and runs a base image (pre-provisioned, custom, or snapshot). Instances are the primary way to run workloads that need direct machine access. > [!NOTE] > > **Prerequisites:** Before creating an instance you need a [VPC network](/docs/network/vpc-networks) and at least one [security group](/docs/network/security-groups) in that VPC. Optionally prepare a [custom image](/docs/storage/custom-images) or [snapshot](/docs/storage/snapshots) if you don't want a pre-provisioned image. ## Summary This page walks you through creating a **compute instance** in the Nscale Console UI—selecting where it lives (project + region), attaching networking and security controls, and choosing what it runs (CPU/GPU + image). Use this guide if you: * Manage infrastructure for workloads that need **direct VM access** * Need to spin up **CPU or GPU** compute in an existing project * Want a repeatable, UI-driven process for provisioning instances ## Availability This service is currently only available in the **reserved cloud service environment.** > [!WARNING] > > If you **create or delete more than 30 instances** at the same time, the instance **provision/deletion time will increase**. Instance creation or deletion is **limited to 50 at a time**. ## Requirements Before you start, you need: * A project to place the instance into (instances are allocated to projects). If you’re not sure which project to choose, see [Projects](/docs/manage/projects) for more detail. * A deployment region selected (you choose this during creation, and it appears in the instance details and status) * A project network (VPC) created * At least one security group created and associated with that network > [!NOTE] > > **Naming rules:** Instance names must be **unique** and contain only **alphanumeric characters and hyphens**. Names are **immutable** — you cannot rename an instance after creation. Choose a descriptive name upfront. ## Instance lifecycle Instances move through the following states: | State | Description | | - | - | | **Queued** | The instance creation request has been accepted and is waiting for resources | | **Building** | Resources have been allocated and the instance is being built | | **Provisioning** | The instance is being configured and prepared for use | | **Running** | The instance is active and ready for use | | **Stopped** | The instance is shut down but can be restarted | | **Error** | Something went wrong during provisioning or operation | **Actions you can take:** * **Stop** a running instance to pause it. * **Start** a stopped instance to resume it * **Create a snapshot** to save a point-in-time copy of the instance's disk * **Delete** an instance to permanently remove it > [!WARNING] > > **Deleting an instance is permanent.** All data on the instance's local disk is lost. If you need to preserve the disk contents, [create a snapshot](/docs/storage/snapshots) before deleting. ## Step-by-step 1. In the Console, open your project, then go to **Compute → Instances** * You should now see the Instances list view 2. Click the **New Instance** button * You will now see the instance creation form / wizard where you will fill in basic details ![Instance](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/Instance.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=f9bfd324b3301ac1d88bcd1ddefab2d2) 3. Fill in the **basic details**: * **Name**: must be **unique** and contain only **alphanumeric characters and hyphens** * **Project**: select the project where the instance will be created 4. Configure networking: * Select or create a new **VPC (network)** to attach the instance to * Select or create a new **security group** to control inbound/outbound traffic * Confirm you've selected the intended VPC and security group before continuing ![New Instance Flow 1 1](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/new-instance-flow-1-1.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=d2851b22d46867c4dbe4172a3872f4dc) 5. Choose an SSH key (optional): * Under **Select existing SSH Keys from your org**, choose an SSH certificate authority to authorize login on the instance. Use the **Manage Keys** link to jump to the SSH Certificate CAs settings. * Alternatively, under **Add a new SSH key**, click **Add new public key** to register a new key without leaving the wizard. * If you don't need certificate-based SSH access, skip this step. You can still use other SSH methods (cloud-init, manual key injection) after provisioning. > [!NOTE] > > **New to SSH CAs?** See the [SSH certificate authorities guide](/docs/compute/ssh-certificate-authorities) for a full walkthrough of generating a CA key pair, registering it, signing user keys, and connecting. ![Choose SSH Key](https://mintcdn.com/nscale/c4ar32crZWhRjTLP/images/new-instance-flow-ssh.png?fit=max\&auto=format\&n=c4ar32crZWhRjTLP\&q=85\&s=ac7e22cae1315ba4129704543772aee0) 6. Configure compute + image: * Choose the **node type**: **CPU** nodes are suited for general workloads, while **GPU** nodes provide accelerated compute for AI/ML training and inference * Choose the **image** source: **pre-provisioned image**, **custom image**, or **snapshot** * You should see the selected node type and image reflected in the configuration summary > [!NOTE] > > **Image and node type compatibility:** Images declare a virtualization type — **bare-metal**, **virtualized**, or **any**. Bare-metal images require bare-metal node types and virtualized images require VM node types, while images marked **any** are generic and work with either. The image **architecture** (for example, x86-64 or ARM64) must also match the node type, and the image must fit within the chosen flavor's disk. The console automatically filters the image list to show only images compatible with the selected flavor's architecture. If you change the flavor to a different architecture, any previously selected incompatible image is cleared so you can pick a valid one. > **Optional: cloud-config YAML** > > You can optionally provide a **cloud-config YAML** block to run commands or configure packages at boot time. This uses the [cloud-init](https://cloud-init.io/) standard. For example: > > ```yaml theme={null} > #cloud-config > packages: > - docker.io > runcmd: > - systemctl start docker > ``` > > If you don't need boot-time configuration, leave this empty. ![New Instance Flow 2](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/new-instance-flow-2.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=a3efef246d2b43886d3f5d50bfaad8f7) 7. Review the configuration summary and click **Create instance** * The review screen shows your selected configuration including network, security group, SSH key (if set), node type, and image * You should be forwarded to the **instance details page** while provisioning is in progress * From the details page, you can monitor status and access the instance via terminal ![Instances Details View](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/Instances-details-view.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=5592105ad69aa59d6186ffe05a326a5a) ## Quotas Instance creation consumes quota for servers, GPUs, and floating IPs. If your instance uses a **public IP**, one floating IP is reserved from your project's quota. Check your current quota usage in the **Resource Usage** section on the **Dashboard**. ## Common issues / troubleshooting * **Symptom:** Instance creation is very slow. **Likely cause:** You are creating or deleting more than 30 instances at the same time. **Fix:** Wait for the current batch to complete before starting another. Instance creation/deletion is limited to 50 at a time. * **Symptom:** You can't connect to your instance via SSH. **Likely cause:** Your security group doesn't have an inbound rule allowing SSH (TCP port 22). **Fix:** Go to **Network → Security Groups**, select your security group, and add an inbound rule for TCP port 22 from your IP or `0.0.0.0/0`. * **Symptom:** Instance creation fails with an image/flavor compatibility error. **Likely cause:** The image's virtualization type or architecture doesn't match the node type, or the image is too large for the flavor's disk. **Fix:** Choose an image whose virtualization type matches your node type (or an **any** image) with a matching architecture, and a flavor with enough disk for the image. The console prevents incompatible selections, so this error typically appears only when creating instances via Terraform, the CLI, or the API. * **Symptom:** Instance creation fails with a quota error for floating IPs. **Likely cause:** Your project's floating IP quota is exhausted and the instance requests a public IP. **Fix:** Delete unused instances with public IPs or request a quota increase. *** ## Related > **[CLI: Instances](/docs/cli/instances)** > > Manage instances from the command line. > **[CLI: Security Groups](/docs/cli/securitygroups)** > > Manage security groups from the command line. # Placements Source: https://docs.nscale.com/docs/compute/placements Schedule bare-metal servers inside a reservation using a Pack or Spread topology policy. A placement schedules a block of pinned bare-metal servers inside a [reservation](/docs/compute/reservations). You choose how many hosts to use and how they should be distributed across the reserved NVLink domains—**Pack** for locality or **Spread** for resilience—and the platform launches one server per host and programs the InfiniBand fabric automatically. > [!NOTE] > > **Prerequisites:** Before creating a placement you need a **provisioned** [reservation](/docs/compute/reservations) with free capacity and a [VPC network](/docs/network/vpc-networks) in the reservation's region. Optionally, prepare [security groups](/docs/network/security-groups) in that VPC to attach to the placement's servers. ## Summary This page walks you through creating and managing **placements** in the Nscale Console—how to carve hosts out of a reservation, how the Pack and Spread policies behave, how to manage the servers a placement launches, and how to delete a placement. Use this guide if you: * Have reserved capacity and are ready to **launch workloads** onto it * Need to control **topology**—keeping hosts tightly packed for performance or spread for fault isolation * Want to run **more than one cluster** on the same reserved capacity ## How placements work A placement consumes capacity from its parent reservation and drives the creation of pinned servers: * **Hosts.** A placement allocates a number of hosts from the reservation. The number of hosts in each NVLink domain depends on the flavour: 18 for GB300 NVL72, one for B200. * **Servers.** The platform launches one server per allocated host. Servers are owned by the placement's lifecycle—they're created and removed with the placement. * **Networking.** Every placement attaches to a VPC. The VPC also sets the **InfiniBand partition boundary**: all hosts in a placement share a single partition key, and switch-port programming is fully automated between creation and boot. * **Flavour.** A placement inherits its flavour from the parent reservation—you don't choose it again. A single reservation can host **multiple placements**, but the total hosts across all placements can never exceed the reservation's capacity. > [!NOTE] > > **Placements are immutable.** You can't resize or re-policy a placement after creation. To change a placement, delete it and create a new one. ## Placement policy The placement policy decides how the platform selects hosts across the reservation's NVLink domains. | Policy | Optimized for | Behavior | | - | - | - | | **Pack** | Low-latency, local communication | Hosts are placed as close together as possible, filling one domain before moving to the next. Best for tightly coupled training. | | **Spread** | Fault isolation | Hosts are distributed evenly across the reserved domains for availability. | > [!NOTE] > > **Pack** gives the best-possible locality, not a physics-level guarantee. **Spread** keeps the host-count difference between any two domains to no more than one; if an even split isn't possible, the request fails cleanly rather than falling back to a skewed layout. To see how a placement actually landed, open the reservation's **Topology View** tab. Pack placements appear as contiguous runs of hosts, and Spread placements appear scattered across the reserved domains. See [Pack and spread in the grid](/docs/compute/topology-view#pack-and-spread-in-the-grid). ## Create a placement Creating a placement is a six-step wizard, launched from the **Create Placement** action on a reservation. You can't proceed to the next step until the current one is valid. **1. Set up your placement** Give the placement a name under **Placement name**. Names are 3–50 characters of lowercase letters, digits, and dashes, and must be unique within the reservation. The **Parent reservation** is fixed—the placement is scoped to the reservation you launched the flow from and can't be changed. **2. Configure your placement** Define how many hosts you need and how they should be distributed: * **Configure network connectivity** — choose the VPC the placement's servers attach to. * **Host Count** — the number of hosts to allocate. The maximum is the capacity still free in the reservation. * **Placement Policy** — choose **Pack** or **Spread** (see [Placement policy](#placement-policy)). > [!WARNING] > > If the reservation has no free capacity, host count is unavailable. Free up capacity by deleting an existing placement, or reserve more capacity, before creating a new placement. ![Configure your placement](https://mintcdn.com/nscale/nIcjBCbNvFHc262C/images/reservations/create-placement-step-2-configure.png?fit=max\&auto=format\&n=nIcjBCbNvFHc262C\&q=85\&s=f8b1eea6381fb4a8de46962411ad5b4c) **3. Configure each host** Choose what every host in the placement runs: * **Security groups** — optionally attach security groups from the selected VPC to control network traffic. * **OS Image** — select the operating system and default packages installed on every node. **4. Choose an SSH key (optional)** Optionally attach an [SSH certificate authority](/docs/compute/ssh-certificate-authorities) that authorizes login on every host in this placement. Select an existing SSH key from your organization, or add a new one. **5. Advanced configuration (optional)** Optionally paste a **cloud-config** YAML file to customize your cluster at first boot. This is applied only during creation and can't be changed later. **6. Review and create** Review the summary—name, host count, policy, VPC, and OS image—then click **Create Placement**. The platform allocates the hosts, programs the InfiniBand fabric, and launches one server per host. > [!NOTE] > > **Provisioning time scales with placement size.** The servers in a placement provision in parallel, so larger placements take longer to become fully ready—expect longer waits as host count grows. Provisioning throughput also decreases as you scale up, because the work is shared across the fabric. Track progress from each server's status in the **Servers** tab. ## View a placement Open a placement from the reservation's **Placements** tab. The detail view shows a header strip with the policy, VPC, host readiness, and OS image, plus two tabs: * **Servers** — every server the placement launched, with its private IP, GPU and CPU counts, and status. * **Security Groups** — the security groups attached to the placement. ![Placement detail](https://mintcdn.com/nscale/nIcjBCbNvFHc262C/images/reservations/placement-detail.png?fit=max\&auto=format\&n=nIcjBCbNvFHc262C\&q=85\&s=4bf6518a2dcf2b9256effa194b034ced) ## Manage servers The **Servers** tab lists every server the placement launched. Each server's **Status** column shows its lifecycle phase: | Status | Description | | - | - | | **Pending** | The server is accepted and waiting for work to start | | **Queued** | The server is waiting for bare-metal hardware | | **Building** | The provider is actively bringing the server up | | **Running** | The server is ready to use | | **Stopping** / **Stopped** | The server is shutting down, or shut down | | **Error** | The provider reported the server in a terminal error state | The placement itself reports a provisioning status in the reservation's **Placements** tab and in the placement's detail header. The values are **Pending**, **Provisioning**, **Provisioned**, **Deprovisioning**, **Error**, and **Unknown**. **Actions you can take:** * **Stop** a server to shut it down. * **Reboot** a server—choose a **soft reboot** (graceful) or a hard reboot (power cycle). > [!NOTE] > > Servers are managed as part of the placement. They can't be deleted individually—deleting the placement removes all of its servers. ## Delete a placement Deleting a placement stops and removes all of its servers and releases their hosts back to the reservation. **1. Open the placement** Go to the placement's detail view, open the actions menu, and choose **Delete Placement**. **2. Confirm the deletion** Confirm by entering the placement's name. If the placement still has active servers, they'll be **stopped and deleted**—this is the only way to release those hosts. Deletion is permanent and can't be undone. > [!NOTE] > > **De-provisioning can take a while.** Each server goes through a full clean-up cycle before its host is released, so deleting a large placement may take some time. You don't have to wait for it to finish—another placement can be created in the same reservation in parallel while a placement de-provisions. > [!TIP] > > Once a placement is deleted and its hosts are released, that capacity is free for a new placement in the same reservation. ## Next steps * Review [reservations](/docs/compute/reservations) and how capacity is reserved. * See how your placements are laid out in the [Topology View](/docs/compute/topology-view). * Manage placements and servers from the command line with the [CLI](/docs/cli/overview). * Explore the full [Placement API reference](/api-reference/placements/list-placements). # Reservations Source: https://docs.nscale.com/docs/compute/reservations Reserve exclusive, topology-aware bare-metal GPU capacity for a project, then launch workloads onto it with placements. A reservation ring-fences one or more contiguous **NVLink domains** of bare-metal GPU capacity for a single project in a region. The capacity is exclusively yours for the life of the reservation, with no noisy neighbors and no rescheduling. It is the foundation you build [placements](/docs/compute/placements) on top of to launch servers. > [!NOTE] > > **Reservations work for GB300 NVL72 and B200.** Reserved capacity is not available through the standard [instance creation](/docs/compute/create-new-instances) flow. To run on it, you reserve capacity first, then create a [placement](/docs/compute/placements) inside the reservation. ## Summary This page walks you through working with **reservations** in the Nscale Console, the capacity model for bare-metal GPU regions. You'll learn how reservations are structured, how to reserve contiguous capacity, how to read a reservation's capacity, and how to delete one. Use this guide if you: * Need **guaranteed, exclusive GPU capacity** for a project rather than best-effort placement * Are preparing to run **tightly coupled training or large-scale inference** on reserved GPU capacity * Want a repeatable, UI-driven process for reserving and managing bare-metal GPU capacity ## How reservations fit together Reservations sit at the top of a four-level hierarchy. Each level builds on the one above it: | Concept | What it is | | - | - | | **Reservation unit** | The capacity shape you reserve. One unit is **one NVLink domain**. Hosts per unit depend on the flavour: a GB300 NVL72 unit is a rack of 18 hosts; a B200 unit is a single host. | | **Reservation** | One or more contiguous units, ring-fenced for a project in a region. Exclusive, and fixed in size after creation. | | **Placement** | A scheduled block of hosts carved out of a reservation, governed by a Pack or Spread policy. See [Placements](/docs/compute/placements). | | **Server** | An individual bare-metal host launched by a placement. | A single reservation can host **multiple placements**, for example a production training cluster and a smaller development cluster on the same reserved capacity. The total number of servers across all placements can never exceed the reservation's capacity. > [!NOTE] > > **Capacity is shown in the console.** Each reservation unit reports its per-unit totals (hosts, GPUs, CPUs, and memory) in the creation wizard and via the [reservation-units API](/api-reference/reservation-units/list-reservation-units). Per-unit totals vary by flavour. ## Availability Reservations are the capacity model for **bare-metal GPU regions**, currently GB300 NVL72 and B200. Capacity is contracted and region-specific, so a reservation can only be created in a region that has enough **contiguous** capacity to satisfy the full request. ## Key properties Reservations behave differently from on-demand instances. Three properties matter most: * **Exclusive.** Reserved capacity belongs to your project alone for the life of the reservation. * **Contiguous and atomic.** A reservation is all-or-nothing. Either the exact contiguous capacity is delivered, or the request fails cleanly—fragmented capacity is never silently combined. * **Fixed size.** A reservation can't be grown after creation. You can add or remove placements, release unused units through the API, or delete the reservation entirely. > [!NOTE] > > **Naming rules:** Reservation names are **3–50 characters** of **lowercase letters, digits, and dashes**. ## Reservation lifecycle A reservation moves through the following provisioning states: | State | Description | | - | - | | **Pending** | The reservation has been accepted and is waiting for provisioning to start | | **Provisioning** | Capacity is being claimed and the NVLink domains are being ring-fenced | | **Provisioned** | The reservation is ready and you can create placements | | **Error** | Provisioning failed, or a provisioned reservation's capacity became invalid. For example, the requested contiguous capacity could not be claimed | | **Deprovisioning** | The reservation is being torn down following a delete | | **Unknown** | The reservation's state can't be determined right now | **Actions you can take:** * **Create a placement** to start launching servers from the reservation * **Delete a reservation** to release its capacity (this also deletes every placement in it) ## Reserve capacity Reserving capacity is a three-step wizard. You can't proceed to the next step until the current one is valid. **1. Open the create flow** In the Console, open your project, then go to **Compute → Reservations** and click **Reserve Capacity**. You can also start from **Reservations** in the organization sidebar, which lists reservations across every project in the organization. There, **Reserve Capacity** first asks you to choose the project to reserve in. See [Reserve capacity from the organization page](/docs/compute/topology-view#reserve-capacity-from-the-organization-page). ![Reservations list view](https://mintcdn.com/nscale/nIcjBCbNvFHc262C/images/reservations/reservations-list.png?fit=max\&auto=format\&n=nIcjBCbNvFHc262C\&q=85\&s=85c6ab96cbad26c0e7516246232090c7) **2. Set up your reservation** Give the reservation a name under **Reservation Name**. Names are 3–50 characters of lowercase letters, digits, and dashes. Click **Configuration** to continue. **3. Configure your reservation** Choose how much capacity to reserve and where: * **Flavour** selects the reserved capacity type. The per-unit breakdown updates with your choice. * **Number of units** sets how many NVLink domains to reserve. The wizard shows the per-unit breakdown (hosts, GPUs, and CPUs) as you adjust the count. * **Select available region** lists only the regions with enough **contiguous** capacity for your request, with the **Max contiguous** units available in each. > [!WARNING] > > **Domains must be contiguous.** If no single region can satisfy the full request from contiguous capacity, the wizard shows *"Insufficient contiguous capacity"*. Fragmented capacity across a region can't be combined—reduce the unit count or choose another region. Click **Review your reservation** to continue. ![Configure your reservation](https://mintcdn.com/nscale/nIcjBCbNvFHc262C/images/reservations/create-reservation-step-2-configure.png?fit=max\&auto=format\&n=nIcjBCbNvFHc262C\&q=85\&s=0a760e82192df3abc6c33633b7a7f99d) **4. Review and reserve** Review the summary: name, unit count, GPU and CPU totals, and region. Reserved capacity is exclusive to your project and **can't be grown after creation**. Click **Reserve Capacity** to submit. The reservation begins provisioning and appears in your reservations list. > [!TIP] > > Capacity is claimed asynchronously. A reservation starts in **Pending**, moves to **Provisioning** while capacity is claimed, and reaches **Provisioned** once all its NVLink domains are ring-fenced. That typically takes around a minute. You can create placements as soon as it is provisioned. ## View a reservation Open a reservation from the list to see its detail view. The **Overview** tab brings together everything about the reservation: * **Placements** — the placements running in this reservation, with a shortcut to create a new one. * **Capacity** — how many of the reservation's hosts are allocated to placements versus free, alongside units reserved, total placements, and per-host CPU and GPU counts. Click **See topology** to jump to the **Topology View** tab. * **Configuration** — the region, creation date, flavour, who created it, and the reservation ID. Switch to the **Placements** tab for the full list of placements in the reservation, with their host count, policy, network, status, and region. The **Topology View** tab shows where the reservation's hosts sit across pods and NVLink domains, colored by placement. See [Topology View](/docs/compute/topology-view). ![Reservation detail overview](https://mintcdn.com/nscale/nIcjBCbNvFHc262C/images/reservations/reservation-detail-overview.png?fit=max\&auto=format\&n=nIcjBCbNvFHc262C\&q=85\&s=454b24b72c843c25643275b0254ffa9d) > [!NOTE] > > **See all your reserved capacity on one map.** The **Reservations** pages for the organization and for each project also have a **Topology View** tab, which shows every reservation's hosts in one grid. It needs organization-level topology access. See [Topology View](/docs/compute/topology-view). ## Delete a reservation Deleting a reservation releases its capacity back to the region so it can be reserved again. > [!WARNING] > > **Deleting a reservation cascades.** It deletes every [placement](/docs/compute/placements) in the reservation, and each placement deletes all of its servers. This is permanent and can't be undone—any data on those servers is lost. **1. Open the reservation** Go to the reservation's detail view and review its placements—deleting the reservation will remove all of them. **2. Delete the reservation** Open the actions menu and choose **Delete Reservation**, then confirm. The reservation, its placements, and their servers are deleted, and the reserved capacity is released. ## Next steps * [Create a placement](/docs/compute/placements) to launch servers from your reservation. * See where your reserved hosts sit in the [Topology View](/docs/compute/topology-view). * Manage reservations from the command line with the [CLI](/docs/cli/overview). * Explore the full [Reservation API reference](/api-reference/reservations/list-reservations). # SSH certificate authorities Source: https://docs.nscale.com/docs/compute/ssh-certificate-authorities Register an SSH certificate authority to authenticate users to your instances with signed certificates instead of individual SSH keys. SSH certificate authorities (CAs) let you authenticate users to instances using signed SSH certificates instead of distributing individual public keys. You register your CA's public key with Nscale, and any instance created with that CA automatically trusts certificates signed by it. > [!NOTE] > > **Prerequisites:** You need an existing [project](/docs/manage/projects), a [VPC network](/docs/network/vpc-networks), and at least one [security group](/docs/network/security-groups) with SSH (TCP port 22) allowed. ## How it works 1. You generate an SSH CA key pair on your local machine 2. You register the CA's **public key** with Nscale at the project level 3. When you create an instance, you specify the SSH CA to trust 4. Nscale configures the instance to accept certificates signed by that CA 5. You sign user SSH keys with your CA private key and use them to connect This eliminates the need to upload individual SSH keys to each instance. Anyone with a certificate signed by the CA can connect. ## Availability SSH certificate authorities are available in the **reserved cloud service environment.** ## Step 1: Generate an SSH CA key pair If you don't already have a CA key pair, generate one: ```bash theme={null} ssh-keygen -t ed25519 -f ~/.ssh/nscale-ca -C "nscale SSH CA" ``` This creates two files: * `~/.ssh/nscale-ca` — the CA private key (keep this secure) * `~/.ssh/nscale-ca.pub` — the CA public key (you'll register this with Nscale) > [!WARNING] > > **Keep your CA private key secure.** Anyone with access to it can sign certificates that grant SSH access to your instances. Store it in a secrets manager or hardware security module for production use. ## Step 2: Register the CA with Nscale Register the CA public key using the API. The CA is scoped to an organization and project. ```bash curl theme={null} curl -X POST "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities" \ -H "Authorization: Bearer $NSCALE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "name": "my-ssh-ca", "description": "Team SSH certificate authority" }, "spec": { "organizationId": "", "projectId": "", "publicKey": "'"$(cat ~/.ssh/nscale-ca.pub)"'" } }' ``` ```python Python theme={null} import os import requests token = os.environ["NSCALE_TOKEN"] with open(os.path.expanduser("~/.ssh/nscale-ca.pub")) as f: ca_public_key = f.read().strip() response = requests.post( "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities", headers={"Authorization": f"Bearer {token}"}, json={ "metadata": { "name": "my-ssh-ca", "description": "Team SSH certificate authority", }, "spec": { "organizationId": "", "projectId": "", "publicKey": ca_public_key, }, }, ) print(response.json()) ``` ```go Go theme={null} package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" ) func main() { pubKey, _ := os.ReadFile(os.Getenv("HOME") + "/.ssh/nscale-ca.pub") body, _ := json.Marshal(map[string]any{ "metadata": map[string]string{ "name": "my-ssh-ca", "description": "Team SSH certificate authority", }, "spec": map[string]string{ "organizationId": "", "projectId": "", "publicKey": string(pubKey), }, }) req, _ := http.NewRequest("POST", "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer "+os.Getenv("NSCALE_TOKEN")) req.Header.Set("Content-Type", "application/json") resp, _ := http.DefaultClient.Do(req) fmt.Println(resp.Status) } ``` ```typescript TypeScript theme={null} import { readFileSync } from "node:fs"; import { homedir } from "node:os"; const pubKey = readFileSync(`${homedir()}/.ssh/nscale-ca.pub`, "utf8").trim(); const response = await fetch( "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities", { method: "POST", headers: { Authorization: `Bearer ${process.env.NSCALE_TOKEN}`, "Content-Type": "application/json", }, body: JSON.stringify({ metadata: { name: "my-ssh-ca", description: "Team SSH certificate authority", }, spec: { organizationId: "", projectId: "", publicKey: pubKey, }, }), } ); console.log(await response.json()); ``` The response includes the CA's ID, which you'll use when creating instances. ## Step 3: Create an instance with SSH CA trust When creating an instance, specify the `sshCertificateAuthorityId` to configure the instance to trust your CA: ```bash theme={null} curl -X POST "https://compute.nscale.com/api/v2/instances" \ -H "Authorization: Bearer $NSCALE_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "metadata": { "name": "my-instance" }, "spec": { "organizationId": "", "projectId": "", "regionId": "", "flavorId": "", "imageId": "", "networkId": "", "sshCertificateAuthorityId": "" } }' ``` The instance will be configured during provisioning to trust certificates signed by the specified CA. ## Step 4: Sign a user SSH key On your local machine, sign a user's public key with the CA: ```bash theme={null} ssh-keygen -s ~/.ssh/nscale-ca \ -I "user@example.com" \ -n ubuntu \ -V +52w \ ~/.ssh/id_ed25519.pub ``` | Flag | Description | | - | - | | `-s` | Path to the CA private key | | `-I` | Certificate identity (for audit logs) | | `-n` | Principals (usernames) the certificate is valid for | | `-V` | Validity period (e.g., `+52w` for one year) | This creates `~/.ssh/id_ed25519-cert.pub` alongside the user's existing key. ## Step 5: Connect to the instance SSH to the instance using the signed certificate. The SSH client automatically presents the certificate when the matching private key is used: ```bash theme={null} ssh -i ~/.ssh/id_ed25519 ubuntu@ ``` > [!NOTE] > > The SSH client uses the certificate file automatically if it's in the same directory and follows the naming convention (`id_ed25519-cert.pub` for an `id_ed25519` key). ## Managing SSH CAs ### List CAs ```bash theme={null} curl "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities" \ -H "Authorization: Bearer $NSCALE_TOKEN" ``` ### Get a specific CA ```bash theme={null} curl "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities/" \ -H "Authorization: Bearer $NSCALE_TOKEN" ``` ### Delete a CA ```bash theme={null} curl -X DELETE "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities/" \ -H "Authorization: Bearer $NSCALE_TOKEN" ``` > [!WARNING] > > You cannot delete an SSH CA that is referenced by active instances. Remove or update the instances first. ## Permissions SSH CA operations require the following RBAC permissions: | Role | Permissions | | - | - | | **Admin** | Create, read, delete | | **User** | Create, read, delete | | **Viewer** | Read only | ## Common issues / troubleshooting **Symptom:** SSH connection is refused or falls back to password auth. **Likely cause:** The certificate's principal doesn't match the server username. **Fix:** Re-sign the certificate with the correct `-n` value (e.g., `ubuntu` for Ubuntu images). *** **Symptom:** Certificate is rejected as expired. **Likely cause:** The certificate validity period has elapsed. **Fix:** Sign a new certificate with a fresh validity period using `ssh-keygen -s`. *** **Symptom:** Can't delete an SSH CA. **Likely cause:** The CA is still referenced by one or more instances. **Fix:** Delete or update the instances that reference the CA, then retry the deletion. *** ## Related resources > **[Instances](/docs/compute/create-new-instances)** > > Create instances that trust your SSH CA > **[Security groups](/docs/network/security-groups)** > > Allow SSH traffic to your instances > **[Service tokens](/docs/manage/service-tokens)** > > Create API tokens for programmatic access > **[API reference](/docs/api-reference/openapi-specs)** > > Full API documentation for SSH CAs # Topology View Source: https://docs.nscale.com/docs/compute/topology-view See your organization's allocated bare-metal capacity as a map of regions, pods, NVLink domains, and hosts, colored by reservation or placement. The **Topology View** is a visual map of the bare-metal GPU capacity allocated to your organization. It lays capacity out the way it is physically organized, region → pod → NVLink domain → host, and colors each host by the [reservation](/docs/compute/reservations) or [placement](/docs/compute/placements) that holds it. > [!NOTE] > > **Organization-level access required.** The Topology View needs organization-level read access to reservation topology. A project-level grant isn't enough. See [Permissions](#permissions). ## Summary This page explains where to find the Topology View in the Nscale Console, how to read the grid and its legends, how to filter it down to single reservations and the placements within them, and what the different states mean. Use this guide if you: * Want to see **which reservations and placements hold which hosts** across your organization or project * Need to check how a **Pack** or **Spread** placement actually landed across NVLink domains * Are planning a new reservation and want to see **allocated and unreserved capacity** at a glance ## Where to find it The **Topology View** tab appears in three locations. Each one shows the same grid at a different scope: | Page | How to get there | What it shows | | - | - | - | | **Organization** | Go to **Reservations** in the organization sidebar, then select the **Topology View** tab | Every project in the organization. | | **Project** | In a project, under **Compute**, select **Reservations**, then open the **Topology View** tab | Shows all reservations in the project. When a reservation is selected or filtered, its placements are shown. Hosts belonging to other projects appear in grey. | | **Reservation detail** | Open a reservation and select its **Topology View** tab (next to **Overview** and **Placements**), or select **See topology** on the reservation's **Capacity** card | Capacity for that one reservation only: its placements, how many hosts each holds, and how many hosts are unplaced or free. | ![Topology View at project scope](https://mintcdn.com/nscale/MNVPvfdtUHn9gs2Z/images/reservations/topology-project-view.png?fit=max\&auto=format\&n=MNVPvfdtUHn9gs2Z\&q=85\&s=4342d190e95dc2de1ca48f669146cf0b) ## Reading the grid The grid is split into one section per region and flavour. Each section is laid out from the top down: 1. **Section header.** The region and flavour, for example ` - GB300`, followed by the unit shape: `1 unit = 1 NVL72 domain`, then the hosts, GPUs, and CPUs in one unit. 2. **Pods.** Each pod is labeled with a badge showing how many units it holds. 3. **Domain cards.** One card per NVLink domain. A domain is one [reservation unit](/docs/compute/reservations#how-reservations-fit-together). 4. **Host bars.** One bar per host in the domain. How many bars a domain card holds depends on the flavour. Each card has one bar per host in the unit, and the section header shows how many hosts that is. ## Legend Hover **Legend** in the toolbar to see what each bar style means. When a reservation is selected, the legend changes to explain which placement each bar's color represents, instead of which reservation. ### Colored by reservation In the organization and project Topology Views, the grid shows each reservation in a different color when the page loads: | Key | Appearance | Meaning | | - | - | - | | **Reserved & placed** | Filled in a single color representing the reservation | The host is reserved, and a placement is using it. | | **Reserved & unplaced** | Outlined in the reservation's color | The host is reserved but no placement is using it. | | **Other projects** | Grey fill | The host is reserved by another project, or by a project you don't have permission to view. Only shown when the view contains such hosts. | | **Unreserved** | Dark grey outline, no fill | The host is part of your organization's allocated capacity, but no reservation currently claims it. | ### Colored by placement Select a reservation either by clicking it in the grid or by using the reservation filter. The grid then updates to show that reservation's placements, with each color representing a different placement. Use the placement filter to focus on a specific placement. Hover over a host bar to view details about the placement that holds it. | Key | Appearance | Meaning | | - | - | - | | **Placed** | Filled with the placement's color | The host is running a server for this placement. The key reads **Selected placement** once you pick a single placement. | | **Placed elsewhere** | Grey fill | The host is running a server for a different placement or reservation, or it's reserved by a project you can't read. | | **Not placed** | Dark grey outline, no fill | No placement is running on the host, whether it is reserved or unreserved. | ![A reservation's Topology View tab, colored by placement](https://mintcdn.com/nscale/MNVPvfdtUHn9gs2Z/images/reservations/topology-reservation-detail.png?fit=max\&auto=format\&n=MNVPvfdtUHn9gs2Z\&q=85\&s=b8c23a96f59d2ee3042a0841285c3e3d) ## Interacting with the grid ### Hover for details Hover over a host bar to highlight all hosts held by the same reservation or placement. The rest of the grid dims, and a tooltip shows details about the item you're hovering over: | Hovering over | Tooltip shows | | - | - | | A reservation | Its name, units and placements, then the number of hosts placed and the number free. | | A placement | Its name, host count, and policy, for example `4 hosts · pack policy`. | | **Other projects** | The units held by other projects, with the note *"Placement details aren't available because you don't have the required permissions."* | | **Unreserved** | The number of unreserved units and the free hosts they contain. | ![Hovering a reservation in the Topology View](https://mintcdn.com/nscale/MNVPvfdtUHn9gs2Z/images/reservations/topology-hover-tooltip.png?fit=max\&auto=format\&n=MNVPvfdtUHn9gs2Z\&q=85\&s=7b309f8340f9933cdb999963077e75eb) ### Click to open Click a bar to open what it belongs to: * When the grid is colored by reservation, select a reservation either using the reservation filter or by clicking it in the grid. The view then switches to show that reservation's placements. Clicking opens the reservation's own **Topology View** tab, while the filter keeps you on the current page. * When the grid is colored by placement, a click opens the placement's detail page. Bars you don't have access to, such as **Other projects**, don't open anything. ### Filter the view The Topology View is broken down by each region and flavour, with each section having its own filter header. You can use the overall **Region** and **Flavor** filters in the toolbar to filter the entire view across all sections. Both are multi-select. Within each region and flavour section, you can also use the section-level filters to filter its reservations and placements: * The reservation picker in each section header, labeled **All reservations** by default, lets you select a single reservation. Once selected, the grid shows placement coloring for that reservation. * The placement picker, labeled **All placements** by default, appears once a reservation is selected and placements are available. It lets you select a single placement, with the label showing its position in the list, for example `1/3 training`. * The arrow button next to a selected reservation or placement opens its detail page. * **Clear Filters** resets every filter at once. The reservation and placement you pick are kept in the page URL, so you can share a filtered view as a link. The Region and Flavor filters aren't saved in the URL. ![Topology View with the Region and Flavor filters applied](https://mintcdn.com/nscale/MNVPvfdtUHn9gs2Z/images/reservations/topology-reservation-filter.png?fit=max\&auto=format\&n=MNVPvfdtUHn9gs2Z\&q=85\&s=6a6809bf329c649b8753bf0489f998df) Filtering always keeps whole domain cards. If you pick a placement that uses three hosts in an 18-host domain, the whole domain stays on screen so you can see the rest of the unit around it. ## Pack and spread in the grid The Topology View is the easiest way to see how a [placement policy](/docs/compute/placements#placement-policy) was applied and how the resulting placements were distributed: * **Pack** placements show up as contiguous runs of bars, filling one domain before moving to the next. * **Spread** placements show up scattered evenly across the reservation's domains. Nscale Kubernetes Service (NKS) node pools backed by a reservation run on a placement, so they appear here as ordinary placements. ## How colors are assigned The grid uses a palette of **eight colors**: * Colors repeat once more than eight reservations or placements are in view. * Neighboring bars rarely share a color, so where two reservations or placements meet you can almost always see the boundary. * A color identifies a reservation or placement only within the current view. It can change after the data refreshes, when you apply a filter, or when you switch between reservation and placement coloring. Use the tooltip or the picker to confirm which one you're looking at. ## Reserve capacity from the organization page Because the organization **Reservations** page isn't tied to a specific project, selecting **Reserve Capacity** first opens a dialog asking you to choose which project the reservation should be created in: **1. Open the dialog** Click **Reserve Capacity** in the page header. If the organization has no allocated topology yet, the Topology View's empty state has a **Reserve Capacity** button that opens the same dialog. **2. Choose a project** The dialog lists only the projects you're allowed to reserve capacity in. Use **Search Project** to narrow the list, then select one. **3. Reserve capacity** The console opens the reservation wizard in that project. Continue from [Reserve capacity](/docs/compute/reservations#reserve-capacity). If there are no projects you can reserve in, the dialog shows **No projects available** instead. ## Permissions The Topology View requires **organization-level** read access to `reservation:topology`. A project-level grant alone is not sufficient, even when you open the tab from a project page. The **reservation-capacity-manager** and **reservation-capacity-reader** roles include this permission when assigned at organization level. See [Roles and groups](/docs/manage/roles-and-groups#reservations). * **Without this permission**, the **Topology View** tab is hidden on every page, and the **See topology** button is hidden from the **Capacity** card. * **If the request is refused**, the tab shows **Topology unavailable**: *"Viewing allocated topology needs organization-level access to reservations. Ask an organization administrator for access."* * **Hosts in projects you can't read** still appear, so the grid reflects everything allocated to the organization, but they're drawn as **Other projects** with no reservation or placement details. ## Empty states | Message | When you see it | What to do | | - | - | - | | **No allocated topology** | Nothing has been allocated to the organization yet. A project with no reservations of its own still shows the organization's capacity, with other projects' hosts in grey, so this state doesn't mean the project is empty. | Click **Reserve Capacity** to create a reservation. | | **No allocated hosts for this reservation** | On a reservation's **Topology View** tab, when the reservation doesn't hold any allocated hosts yet. | Wait for the reservation to finish provisioning. | | **No matching topology** | Your filters hide every host. | Clear a filter, or click **Clear Filters**, to see the rest of the allocated capacity. | | **Topology unavailable** | You don't have organization-level topology access. | Ask an organization administrator for access. | ## Limitations * **Mouse only.** Host bars can't be focused with the keyboard. To open a reservation or placement without a mouse, select it in the picker and use the arrow button next to it. * **No server details.** Bars show which reservation and placement hold a host, not the server running on it. Open the placement to see its servers. * **Region and Flavor filters reset on reload.** Only the reservation and placement selection is kept in the URL. * **Refreshes every 30 seconds.** The grid updates on its own, so a newly created placement can take up to 30 seconds to appear. ## Next steps * Learn how capacity is structured in [Reservations](/docs/compute/reservations). * Choose between Pack and Spread in [Placements](/docs/compute/placements). * Grant organization-level access in [Roles and groups](/docs/manage/roles-and-groups). # arXiv Multimodal RAG Source: https://docs.nscale.com/docs/cookbooks/arXiv-Multimodal-RAG ## Introduction This notebook gives a practical guide to inspire developers and researchers in building AI applications. Through a hands-on example of creating a multimodal RAG (Retrieval Augmented Generation) system for scientific papers, we'll explore: How to leverage Large Language Models (LLMs) hosted on [Nscale serverless](https://www.nscale.com/) platform The fundamentals of building effective RAG systems While we'll be building a specific implementation for processing arXiv papers, the concepts and patterns demonstrated here can be adapted to create various AI services and applications. Whether you're looking to understand RAG systems, explore multimodal AI, or learn how to utilize Nscale's hosted LLMs effectively, this notebook provides a foundation to build upon. You can access the Jupyter Notebook version [here](https://github.com/nscaledev/nscale-cookbooks/blob/main/RAG/arxiv_multimodal_rag.ipynb), where you can explore and execute the code yourself. ## Outlines of a simple RAG If you are not familiar with RAG, it is a technique that enhances AI language models by first retrieving relevant information from a knowledge base, then using that context to generate more accurate and informed responses. Think of it as giving an AI model access to a specialized library that it can reference before answering questions. Here's the outline of a simple RAG workflow: 1. Indexing phase: 1. The user first uploads a document 2. The document's content is then split into chunks 3. Those chunks are fed to an embedding model that will convert the text to a vector of number that captures the sementic meaning of the chunk 4. The chunk is then stored in a vector store or database 2. Retrieval phase: 1. The user will query the system 2. The query itself will be converted to an embedding 3. A vector similarity search between the query vector and the vectors stored in the database then happens. 3. Generation phase: 1. Once the vectors are retrieved, we use a large language model to generate a response based on the query and the retrieved context. ![Basic Rag Figure Pn](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/BasicRagFigure.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=031d544f357b695194418f8ab374a792) ## Multimodal RAG While simple RAGs can work well, they often fall short in tasks that requires parsing complex layouts. For example scientific paper, are complex to parse because of their sometimes difficult structure which can include text, image and tabular data. One solution has been to leverage projects such as LlamaParse or [unstructured.io](http://unstructured.io) to parse those documents using OCR, layout detection and captioning. Such approach can work well but will lead to overhead time in the indexing phase as seen in the following figure from [ColPali: EFFICIENT DOCUMENT RETRIEVAL WITH VISION LANGUAGE MODELS](https://arxiv.org/pdf/2407.01449) by Faysse et al. ![Offline Document Indexing Pn](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/OfflineDocumentIndexing.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=a891f6b3684fbcd5cce196b3f464e30d) Therefore in this notebook we will explore an efficient and simpler approach to building a multimodal RAG using the VLM ColPali. In high level, ColPali is based of PaliGemma-3B a vision language model that is further enhanced to generate ColBERT-style multi-vector representations of text and image data, among other optimisations. The model directly encode pages and can be used for multimodal retrieval tasks. To achieve the multimodal RAG system for scientific papers we are going to combine two powerful models: Llama 4 Scout for it’s vision capability, it is hosted on [Nscale serverless](https://www.nscale.com/) ColPali a VLM model capable of generating accurate embeddings of image data. If the concept is not clear by now, do not worry as we will be building a simple multimodal RAG system to answer any questions related to ColPali. Now let's get started! ## Implementation ### Install the required libraries ```python theme={null} !pip install arxiv # arXiv API !pip install byaldi # RAG model !pip install pdf2image # Convert pdf to images !pip install openai # LLM ``` ```python theme={null} Install poppler !sudo apt-get install -y poppler-utils ``` ### Export the necessary variables ```python theme={null} nscale_api_key = "xxxx" ``` ### Retrieve the arXiv data If you haven't heard of [arXiv](https://arxiv.org/), in brief it's an open-access repository where researchers share preprints of scientific papers before formal peer review, primarily in fields like physics, mathematics, and computer science. For our use case we will use the [paper](https://arxiv.org/pdf/2407.01449) "ColPali: EFFICIENT DOCUMENT RETRIEVAL WITH VISION LANGUAGE MODELS" by Faysse et al. And leverage [arxiv's API](https://info.arxiv.org/help/api/basics.html) to retrieve the paper. ```python theme={null} # Search for the most relevant paper on ColPali and download it to our data folder. import arxiv import os search = arxiv.Search( query="ColPali", max_results=1, sort_by=arxiv.SortCriterion.Relevance, ) results = list(search.results()) paper = results[0] download_dir = "data" pdf_path = os.path.join(download_dir, f"{paper.get_short_id()}.pdf") paper.download_pdf(filename=pdf_path) ``` ### Initialise the multimodal model We are going to initialise ColPali model using the byaldi library. [ColPali](https://huggingface.co/vidore/colpali-v1.2) will be used to generate the embeddings of the document. It does so by converting the document into images that will then be cut into patches, these patches are later embedded in a 128 dimension vector space. ![Col Pali Retrieval Pn](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/ColPaliRetrieval.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=1adeefb08b3eaf862d9f3d29c12bdff3) [ColPali: EFFICIENT DOCUMENT RETRIEVAL WITH VISION LANGUAGE MODELS](https://arxiv.org/pdf/2407.01449) by Faysse et al. ### Indexing phase ```python theme={null} from byaldi import RAGMultiModalModel # Initialise the multimodal model retrieval_model = RAGMultiModalModel.from_pretrained("vidore/colpali-v1.3") ``` ```python theme={null} # Index the data retrieval_model.index( input_path="data/", index_name="image_index", store_collection_with_index=True, overwrite=True ) ``` ### Initialise LLM We will use the new Llama 4 Scout as LLM, it is a 17 billion active parameter model with 16 experts that uses a mixture-of-experts (MoE) architecture. It's a very powerful multimodal model with native multimodality, strong performance and an extremely large context window. Running such model locally is not feasiable. For this reason we will be inferencing the model through [Nscale serverless](https://www.nscale.com/)! Nscale offers 5\$ of free credit upon signup, way more than enough to fully understand the ColPali paper! ### Retrieval and generation phase ```python theme={null} from openai import OpenAI # Initilise the client nscale_base_url = "https://inference.api.nscale.com/v1" client = OpenAI( api_key=nscale_api_key, base_url=nscale_base_url ) ``` ```python theme={null} # Query the retrieval model on the ColPali paper query = "Describe the results of table 2" returned_page = retrieval_model.search(query, k=2)[0].base64 ``` ```python theme={null} response = client.chat.completions.create( model="meta-llama/Llama-4-Scout-17B-16E-Instruct", messages=[ { "role": "user", "content": [ {"type": "text", "text": query}, { "type": "image_url", "image_url": { "url": f"data:image/jpeg;base64,{returned_page}", }, }, ], } ], max_tokens=300, ) print(response.choices[0].message.content) ``` > **LLM output** > > The table presents results that compare various models and their performance across multiple metrics. > > **Step 1: Identify the metrics and models presented**\ > The table provides a comprehensive evaluation of baseline models and proposed methods on ViDoRe, with only visual elements and text-only metrics not computed for benchmarks. > > **Step 2: Analyze the performance of different models**\ > The models are evaluated based on various metrics such as ArxivQ, DocQ, InfoQ, TabF, TATQ, Shift, AI, Energy, Gov, Health, and Avg. > > **3: Compare results across different models and methods**\ > Results are presented using Recall\@1 metrics. > > **4: Conclusion**\ > Based on the provided information, the description of table 2 results could not be found, however, table 6 and 7 results are provided. > > **5: Results from Table 6 and Table 7**\ > The best result in table 6 is from ColPali (+Lac Iter.) which scores 72.7 and has a recall of 85.0. \ > The best results in table 7 are from ColQwen2 (224) which scores 86.6 and 86.6 on Energy and Health. > > **6: Final Conclusion**\ > The description of table 2 results could not be found. However, based on the results from table 6 and 7, ColPali and ColQwen2 models tend to perform better across various metrics. ## Conclusion In this notebook, we've successfully built a multimodal RAG system for scientific papers that combines: * ColPali's powerful document retrieval and embedding generation * Llama 4 Scout's advanced vision-language understanding, accessed through Nscale's serverless platform We demonstrated how to: 1. Download and process arXiv papers 2. Index documents using ColPali's multimodal capabilities 3. Perform intelligent retrieval based on user queries 4. Generate contextual responses using Llama 4 Scout ### What We've Learned * How to implement a multimodal RAG system without complex OCR pipelines * Ways to leverage Nscale's LLMs effectively * Techniques for handling both text and visual content in academic papers ### Build Your Own This implementation serves as a starting point - here are some ways you could extend it: * Adapt the system for other document types (patents, technical documentation, etc.) * Add more sophisticated indexing, retrieval and generation strategies * Implement concurrent processing for large document collections * Create a web interface or API * Fine-tune the models for your specific use case Remember, the patterns shown here can be adapted for various use cases - from document analysis to building complete AI services. Happy building! 🚀 # Deploy a model Source: https://docs.nscale.com/docs/dedicated-models/deploy-a-model Run a model in your environment and call it with an OpenAI-compatible endpoint. > [!NOTE] > > **Beta:** Deploying models into [Environments](/docs/platform-services/environments) is in beta for **private cloud** organizations. To join the waitlist, contact [support](mailto:helpdesk@nscale.com). A **deployment** is something you run inside one environment. Deploying a model from the console sets up two things in the environment: * **The model**, which serves an **endpoint**: a URL you send requests to. It works with the OpenAI API format. * **A secret**, which stores the **access key** that lets you call the endpoint. The console lists them together as one deployment. ## What it does * **Dedicated hardware.** The model runs on your environment cluster. No other customer shares it. * **OpenAI-compatible endpoint.** OpenAI SDKs and tools work with it. * **Multiple deployments.** You can deploy the same model to several environments, for example `dev` and `prod`. ## Key words | Word | Meaning | | - | - | | **Model** | The AI model you want to run. The **Models** tab lists Nscale's models. The **Your Models** tab lists your project's own models. | | **Profile** | A ready-made setup for deploying a model. It decides the hardware and tuning. | | **Environment** | Where the model runs. It must be **Ready**. | **Profile types:** * **Balanced**: a good mix of speed and cost * **Latency-optimized**: faster replies for each request * **Throughput-optimized**: handles more requests at once * **Custom**: a special setup made for a specific need ## Before you start You need an [environment](/docs/platform-services/environments#environments) with the status **Ready**. ## Deploy a model **1. Start a deployment** Go to **AI Services → Models**. Click **+ Deploy Model**. You can also start from: * A model's page: click **Deploy** * An environment: click **⋯**, then **Deploy Model** ![The Models page with the Deploy Model button.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/deploy-entry.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=ece606c776babb698c6f8ad414f43a87) **2. Name the deployment and pick a model** Under **Deployment Details**: * **Deployment Name**: lowercase letters, numbers, and dashes. Up to 62 characters. Must be unique for this model. * **Model**: search for and select the model. ![The Deployment Details step with the Deployment Name and Model fields.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/deploy-details.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=e4887e51f4d0aea3538b94017a4c72f9) **3. Select an environment** Under **Select Environment**, pick where the model runs. Only **Ready** environments show in the list. No environment yet? Click **+ Create Environment**. It opens in a new tab. **4. Select a profile** Under **Select Profile**, pick a profile. Each profile card shows the hardware it needs. The console checks this against your environment's cluster. > [!WARNING] > > If a card says **No matching hardware in this environment**, the cluster doesn't have the right GPUs. Pick another profile, or use an environment on a different cluster. ![The Select Profile step with profile cards and hardware check.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/deploy-profile.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=b3f6c05b3c990c723a8dae3cf569258d) **5. Review and create** Check the **Review your Deployment** summary. Click **Create Deployment**. **6. Copy your access key** A **Copy your Access Key** window opens. It shows a new access key. > [!WARNING] > > **Copy the key now. You can't see it again.** Store it in a password manager or secrets store. Click **Copy Key & Create Deployment**. This copies the key and starts the deployment. Nothing is created until you click it. ![The Copy your Access Key window with the key and the Copy Key & Create Deployment button.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/deploy-access-key.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=2f6383d73017bf75def0dab99e2279a2) **What happens next:** The console opens the model's **Deployments** tab. Your deployment shows **Deploying**. When it shows **Running**, you can call it. > [!NOTE] > > Large models take longer to download and start. You can leave the page. ## Deployment status | Status | What it means | What to do | | - | - | - | | **Deploying** | The model is being set up | Wait | | **Running** | The model is ready | Call the endpoint | | **Undeploying** | The deployment is being removed | Wait | | **Failed** | The deployment didn't work | Hover the status to see why. Fix the cause, then [delete the deployment](#delete-a-deployment) and deploy it again | | **Cancelled** | The deployment was stopped | Deploy again if needed | > [!NOTE] > > The environment's **Deployments** tab uses different words for the same status: **Pending**, **In progress**, **Succeeded**, **Failed**, and **Cancelled**. ## Call your model 1. Open the model's page and go to **Overview**. 2. Find the **Access endpoint** card. If you have more than one deployment, pick one from the menu at the top of the card. 3. Copy the example in **cURL**, **Python**, or **TypeScript**. You can also copy the **Endpoint** from the **Deployments** tab. ![The Access endpoint card with code examples.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/deploy-access-endpoint.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=a3a2747f4e846a01ba262205d359431f) Example request: ```bash theme={null} export NSCALE_MODEL_ACCESS_KEY="" curl "/chat/completions" \ -H "Authorization: Bearer $NSCALE_MODEL_ACCESS_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "", "messages": [{"role": "user", "content": "Hello!"}] }' ``` Replace: * `` with the **Endpoint** from the console * `` with the key you copied * `` with the model name shown on the model page ## Lost your access key? Roll it You can't view an access key again. If you lose it, create a new one. 1. Open the model's **Deployments** tab. 2. Click **Roll Key** on the deployment. 3. Copy the new key. Click **Copy Key & Redeploy**. The deployment restarts with the new key. **The old key stops working.** Update any app that uses it. > [!NOTE] > > **Roll Key** is not available for profiles that support more than one hardware type. For these, delete the deployment and deploy again. ## Delete a deployment > [!WARNING] > > **The endpoint stops working straight away.** Any app that calls it will fail. 1. Open the model's **Deployments** tab. 2. Click **⋯** on the deployment. Click **Delete Deployment**. 3. Confirm. You can't delete a deployment while it is **Deploying** or **Undeploying**. # Deprecations Source: https://docs.nscale.com/docs/faqs/deprecations We’re excited to keep our platform at the cutting edge with robust open-source model upgrades. Below you’ll find our clear deprecation framework and step-by-step guidance to transition smoothly between model versions – we’ve designed this resource to make your migration effortless and interruption-free. **Key enhancements:** * **Proactive updates:** We continuously integrate state-of-the-art models while maintaining backward compatibility where possible * **Transparent timelines:** Deprecated models receive advance warnings and parallel support during phase-out periods * **Guided workflows:** Interactive documentation and automated version-check tools simplify transitions ## API keys removal > [!WARNING] > > **API keys are no longer supported** > > API keys are no longer an accepted method of authentication as of November 1, 2025. Service tokens now provide the authentication surface for all automation and integrations, offering finer-grained scoping and rotation controls. Migrate any remaining API key usage to service tokens to restore access. > > [Learn more about service tokens ](/docs/manage/service-tokens) ## Deprecation history | Removal date | Item | Type | Replacement | | :- | :- | :- | :- | | 2026-05-20 | Fine-tuning service | AI Services | [Contact support](mailto:support@nscale.com) | | 2026-05-07 | Compute clusters | Compute | [Instances](/docs/compute/create-new-instances) | | 2025-11-01 | API keys | Auth | [Service tokens](/docs/manage/service-tokens) | # Error codes Source: https://docs.nscale.com/docs/faqs/error-codes Refer to the error codes below for troubleshooting common issues with Nscale's serverless inference service. | Status Code | Description | Response Format | | - | - | - | | 401 | Invalid service token or unauthorized | Error object | | 403 | Forbidden — insufficient permissions for the requested endpoint and operation | Error object | | 404 | Model not found or unavailable | Error object | | 409 | Conflict — the resource was modified by another request (retry with a fresh copy) | Error object | | 429 | Insufficient credit | Error object | | 500 | Internal server error | Error object | | 503 | Service temporarily unavailable | Error object | ### Common solutions * **401 (Unauthorized)**: Verify your service token is valid and properly included in the Authorization header * **403 (Forbidden)**: The error message includes the endpoint and operation that was denied and which scope tier (global, organization, or project) rejected the request. Check that your role has the required permissions for this endpoint. * **404 (Not Found)**: Check that you're using a valid model ID * **409 (Conflict)**: Another request modified the resource between your read and your update. Fetch the latest version of the resource and retry your request. * **429 (Rate Limit)**: Review your available credit * **500 (Server Error)**: If persistent, contact support with details about your request * **503 (Service Unavailable)**: Retry your request after a short delay, using exponential backoff ### Error response format ```json theme={null} { "error": { "message": "Error message describing what went wrong", "type": "", "param": "", "code": "" } } ``` > **[Contact Support](mailto:helpdesk@nscale.com)** > > If you encounter any of these errors and need further assistance, please Contact Support. # Rate Limits Source: https://docs.nscale.com/docs/faqs/rate-limits Rate limits define the maximum number of requests a user can make to Nscale’s serverless inference service within a given time frame. Rate limits are applied to ensure efficient use of resources, maintain system stability, and provide fair access to all users. These limits may vary based on the type of model, your subscription plan, or specific API endpoints. ## Purpose of rate limits The implementation of rate limits serves several critical purposes: 1. **Protecting resources:** Rate limits prevent resource exhaustion by ensuring that no single user or process monopolises system resources. This is especially important in serverless environments where scaling is automatic but not free. 2. **Ensuring fair access:** By capping the number of requests per user or Service token, rate limits ensure equitable access to services for all users. 3. **Preventing abuse:** They act as a safeguard against malicious activities such as Distributed Denial of Service (DDoS) attacks or brute force attempts. 4. **Cost management:** Rate limits help control operational costs by preventing runaway resource consumption due to bugs or heavy traffic spikes. ## How we enforce rate limits Nscale doesn’t enforce rate limits for serverless inference, allowing you to scale dynamically without artificial constraints—your workload is only limited by your allocated resources, ensuring consistent performance even under high demand. # Overview Source: https://docs.nscale.com/docs/getting-started/overview Welcome to the Nscale docs. Discover how to get started and unlock the full potential of Nscale. ![](https://mintcdn.com/nscale/5cvpEeN1jrpcQB9B/images/overview.png?fit=max\&auto=format\&n=5cvpEeN1jrpcQB9B\&q=85\&s=d715ee73bd7ce18063cc4cfb2b69eb05) ## Building with Nscale We make it easy to integrate AI into your applications. Nscale is a high-performance compute platform designed to simplify AI development and deployment. It provides on-demand AI services that enable you to evaluate, deploy, and run AI models at scale—without the complexity of managing infrastructure. Built on Nscale’s powerful compute technology, these services are accessible in a self-serve, prepaid model. Whether you're optimising models for production or running large-scale inference, Nscale delivers the flexibility and performance needed to power AI-driven applications. ## Quick links > **[Quickstart](/docs/getting-started/quickstart)** > > Learn how to get started with Nscale > **[Serverless Inference](/docs/ai-services/models)** > > Get started with Serverless Inference > **[Contact Support](mailto:helpdesk@nscale.com)** > > Get help from our support team > **[Get GPU Clusters](https://www.nscale.com/contact/sales)** > > Slurm, Kubernetes and Bare metal clusters ## Nscale's capabilities * **Serverless inference** – Run popular LLMs effortlessly with our API, without worrying about infrastructure management. * **Evaluation (Coming soon)** – Evaluate model performance with tools designed to meet your specific requirements. * **GPU clusters** – Accelerate your workflow with cutting-edge infrastructure like NKS (Nscale Kubernetes Service), Slurm, or bare metal machines. [Contact sales to learn more](https://www.nscale.com/contact/sales). ## Quickstart **1. Create an account** Head to [console.nscale.com](https://console.nscale.com/login) and create an account **2. Add credit to your account** From the dashboard, add a minimum of \$5 of credit to start using our service **3. Call your first endpoint** Call the [inference endpoint](/api-reference/inference/create-chat-completion) with your Service token Head to the quickstart page for a more detailed view on how to get started with Nscale. ## Platform Infrastructure Provision and manage compute, networking, and storage resources directly in the Nscale Console. > **[Instances](/docs/compute/create-new-instances)** > > Create GPU and CPU virtual machines with SSH access > **[VPC Networks](/docs/network/vpc-networks)** > > Isolated private networks for your resources > **[Filesystem](/docs/storage/file-storage)** > > Shared persistent NFS storage for instances and clusters > **[Managed Kubernetes](/docs/platform-services/managed-kubernetes)** > > Provision isolated Kubernetes clusters for container workloads > **[Security Groups](/docs/network/security-groups)** > > Firewall rules controlling inbound and outbound traffic > **[Terraform Provider](/docs/manage/terraform)** > > Manage Nscale infrastructure as code ## Get help > **[Contact Support](mailto:helpdesk@nscale.com)** > > For technical issues or assistance with our platform. # Quick search Source: https://docs.nscale.com/docs/getting-started/quick-search Find any resource, page or command in the console from the keyboard. Search by name, ID, IP address, MAC address or hostname, narrow results with filters, and jump straight to what you need. Quick search is the fastest way to get around the Nscale console. Open it from any page, type what you are looking for, and press **Enter** to go there. ![Quick search open with no query, showing recent items, suggested pages and create actions](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/open.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=9bbbe3b860db57fa6b966607860afb72) ## Open quick search * On macOS, press **Cmd+K**. * On Windows and Linux, press **Ctrl+K**. * Or select **Search** at the top of the sidebar. Press **Esc** to close it. Before you type anything, quick search shows the items you opened recently, a few suggested pages and the most common create actions. Use the arrow keys to move through the list and **Enter** to open the highlighted row. Press **Cmd+Enter** (**Ctrl+Enter** on Windows and Linux) to open it in a new tab instead. ## Search for resources Start typing and results appear as you go. You don't need the full name: each word you type can match any part of a name, ID or other detail, so `train 01` finds `training-node-01`. Small typos are forgiven too, so `traning` still finds it. Matched text is highlighted in each row. ![Quick search results for vpc, with matching VPCs, the project each belongs to, and an option to search inside VPCs](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/results.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=75bf2212d5b532afc1e7a93388000c4b) You can search across: * **Resources** such as projects, instances, Kubernetes clusters, VPCs, security groups, filesystems, object storage, reservations, placements and models. * **Pages** in the console, including settings, billing and service tokens. * **Commands** such as changing the theme, copying the page URL, copying your organisation ID and signing out. Each resource row shows the project it belongs to. Results you open often, and recently, move up the list over time. When you are working inside a project, that project's resources are listed first. > [!NOTE] > > You only see resources and pages that you have permission to view, so the list may differ from a colleague's. ### Search by ID, address or hostname Paste an identifier and quick search recognises what it is. A badge in the search box shows what it found. | Paste | What you get | | :- | :- | | A resource ID, or just its first block (for example `3f2a9c1e`) | The resource with that ID | | An IPv4 address (for example `10.0.4.17`) | The instance or placement server that holds the address | | A CIDR range (for example `10.0.0.0/16`) | The VPCs whose range contains it | | A MAC address | The instance or server with that network interface | | A server hostname (for example `rack-0-3`) | The matching placement servers | | An email address | That person in **Settings > People**, if you manage people in your organisation | | A link to a console page | That page | ## Filter results Type a filter as `key:value` followed by a space, and it turns into a chip that narrows the results. Start typing a key, such as `sta`, and quick search suggests the keys and their values as you go. ![Quick search with a status filter chip applied, listing only resources in an error state](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/filters.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=478d56aa307518fd075ac2be7e7da9cc) | Filter | Values | Example | | :- | :- | :- | | `status` | `pending`, `provisioning`, `provisioned`, `deprovisioning`, `error`, `unknown` | `status:error` | | `health` | `healthy`, `degraded`, `error`, `unknown` | `health:degraded` | | `project` | Any project name in your organisation | `project:research` | | `type` | A resource type, such as `instance`, `vpc`, `sg` or `k8s` | `type:instance` | You can combine filters and text. For example, `status:error type:instance gpu` lists instances in an error state whose name or details match `gpu`. While a filter you typed is applied, only resources are listed; pages and commands come back when you remove it. To remove the last chip, press **Backspace** in an empty search box. > [!TIP] > > When you open quick search from inside a project, it starts with a `project` chip for that project. Press **Backspace** to remove it and search your whole organisation. ## Search inside one resource type A scope limits the search to a single resource type, such as instances or VPCs. This is useful when a name matches several kinds of resource, or when you want to browse everything of one type. ![Quick search scoped to VPCs, listing every VPC in the organisation](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/scope.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=094ff6e4c0ef24573aa84e934d4f7245) To enter a scope: 1. Type the name of the resource type, such as `instances` or `vpc`. Common alternatives work too, for example `vm`, `k8s`, `sg`, `bucket` or `nodes`. 2. Press **Tab**. The scope appears at the start of the search box. 3. Type to search within it, or leave the box empty to list everything of that type. You can also select a scope from the **Search in** list at the bottom of the results. To leave a scope, press **Backspace** in an empty search box, or select the **x** on the scope. ## Recent items Quick search remembers the pages and resources you open, whether you reached them through search or by browsing the console. They are listed under **Recent** each time you open it, so you can get back to what you were working on in a couple of keystrokes. Recent items are kept per organisation in your browser. To remove one, highlight it and press **Cmd+Backspace** (**Ctrl+Backspace** on Windows and Linux). ## Create resources Type `create` or `new`, followed by what you want to make, to see the create actions available to you. For example, `new instance` or `create vpc`. If you are already inside a project, the create action opens in that project. Otherwise, quick search asks you to choose a project first. ## Run commands Quick search also runs a few everyday commands: * **Change theme** switches between light, dark and system themes. * **Copy page URL** copies a link to the page you are on. * Type `org id` to copy your organisation's ID, for example when contacting support. * **Sign out** signs you out of the console. ## Calculator Type a sum or a conversion and the answer appears at the top of the results. Press **Enter** to copy it. ![Quick search showing the calculator answer for 64 gpus for 2 weeks](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/calculator.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=12f0e8d04e9970ef4eb5ef0bc5a6ad74) | Type | Answer | | :- | :- | | `8 * 72` | `576` | | `(1024 + 512) / 4` | `384` | | `64 gpus for 2 weeks` | `21,504 GPU-hours` | | `2 TiB in TB` | `2.199 TB` | | `3 days in hours` | `72 hours` | GPU-hours accept hours, days, weeks, months and years. Storage conversions accept both decimal units (KB, MB, GB, TB, PB) and binary units (KiB, MiB, GiB, TiB, PiB). ## Keyboard shortcuts Type `?` in quick search to list every shortcut. ![Quick search listing its keyboard shortcuts after typing a question mark](https://mintcdn.com/nscale/c09FwnQ-J_P-uNEK/images/quick-search/shortcuts.png?fit=max\&auto=format\&n=c09FwnQ-J_P-uNEK\&q=85\&s=607eb295f0a6c2eeea77f953696ae567) ### Inside quick search | Shortcut | Action | | :- | :- | | **Cmd+K** / **Ctrl+K** | Open or close quick search | | **Up** / **Down** | Move between results | | **Enter** | Open the highlighted result | | **Cmd+Enter** / **Ctrl+Enter** | Open the highlighted result in a new tab | | **Tab** | Search inside a scope | | **Backspace** (empty search) | Remove the last filter chip, or leave the scope | | **Cmd+Backspace** / **Ctrl+Backspace** | Remove the highlighted recent item | | **Esc** | Back out one step: clear filters, then leave the scope, then clear the search, then close | ### Go to shortcuts Anywhere in the console, outside a text field, press **G** followed by a second key to jump straight to a page. These shortcuts are also shown next to the matching pages in quick search. | Shortcut | Goes to | | :- | :- | | **G** then **H** | Dashboard | | **G** then **P** | Projects | | **G** then **I** | Instances | | **G** then **K** | Kubernetes | | **G** then **R** | Reservations | | **G** then **B** | Billing | | **G** then **S** | Settings | Outside a project, **G** then **I** and **G** then **K** open quick search scoped to instances or Kubernetes clusters so you can pick one. Shortcuts for pages you don't have access to are not available. # Quickstart Source: https://docs.nscale.com/docs/getting-started/quickstart Get up and running with Nscale’s serverless inference models in just a few steps. This guide will walk you through signing up, adding credit to your account, and making your first API call to start leveraging the power of our AI models. ![](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/login.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=d4b0acf782aa55399e913785d2f9470e) ## 1. Sign up * Visit the [Nscale website](https://www.nscale.com/) and click the **Login** button. * Currently, you can only sign up using **Google (SSO)**. Click the **Sign in with Google** button and select your Google account to complete registration. * Once signed in, you will be redirected to your Nscale dashboard. ![](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/balance.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=d5441aa2b6b2af67dc407ca7bc736226) ## 2. Add credit to your account * Go to the **Usage & Billing** section from the navigation bar. * Select the **Credit** tab. * Choose the amount you'd like to add and click **Add credit.** * Nscale accepts all major credit and debit cards. * Follow the Stripe payment flow to securely complete your transaction and add funds to your account. * Early users may be eligible for free credits—check for promotional offers. ![](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/service-tokens.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=91b4edaf04b7f058cdad1cc74aa4d097) ## 3. Create a service token * Go to **Settings** from the navigation bar. * Select the **Service Tokens** tab. * Click **Create Service Token** and assign it a name. * Copy the generated service token and store it securely. Note: The token will not be displayed again, for security. * Make use of environment variables or similar strategies to protect your service token from unauthorised access. # How to Contact Support Source: https://docs.nscale.com/docs/help/contact-support Learn how to get technical assistance from Nscale Support > [!WARNING] > > **Security First** > > Only sign in to the Support Portal at [https://nscale.atlassian.net/servicedesk/customer/portals](https://nscale.atlassian.net/servicedesk/customer/portals) > > Nscale will **never** ask for your password, one-time codes, or to install remote-access tools. ## Getting Assistance from Nscale Support > **Nscale Cloud Customers** > > For assistance with services on the [Cloud Console](https://console.nscale.com/), send an email to [helpdesk@nscale.com](mailto:helpdesk@nscale.com) > **Nscale Private Cloud Customers** > > Access the Nscale Support Portal as your primary channel for technical assistance. Submit tickets, track existing issues, view support history, and access self-help resources. ## Nscale Support Portal Access ### Navigating to the Support Portal If you are an Nscale Private Cloud Customer, you can access the Support Portal by visiting: > **[Nscale Ticketing Service](https://nscale.atlassian.net/servicedesk/customer/portals)** > > [https://nscale.atlassian.net/servicedesk/customer/portals](https://nscale.atlassian.net/servicedesk/customer/portals) ### Support Portal - First-time Login An account is created for you during onboarding. Follow these steps to sign in for the first time. **1. Navigate to the portal** Open the [Nscale Ticketing Service](https://nscale.atlassian.net/servicedesk/customer/portals), or use the link in your invitation email. **2. Request a password** Enter the email address registered to your Nscale account, then select **Create password**. If you arrived from an invitation link, simply set your new password and skip to the final step. **3. Check your email** You'll receive a password-reset email. Only act on it if **you** just requested the reset. **4. Verify the URL** Return to the portal tab you already have open to complete the reset. If you use the link in the email instead, confirm the address bar shows [https://nscale.atlassian.net/servicedesk/customer/user/login](https://nscale.atlassian.net/servicedesk/customer/user/login) before entering a password. **5. Sign in** Enter your email address and new password to sign in. > [!NOTE] > > If you need further assistance with this process, contact your Nscale Account Manager or email [helpdesk@nscale.com](mailto:helpdesk@nscale.com). ## Add a Customer to Your Service Space Both admins and agents can add customers to a service space. **1. Open Customers** From your service space, select **Customers**. **2. Start adding customers** On the **Customers** tab, select **Add customers**. **3. Enter customer details** Enter the customer's username or email address. To add several customers at once, separate the entries with commas. ## Response Times and SLAs We prioritize requests by impact and aim to respond according to our [Service Level Objectives (SLOs)](/docs/help/service-level-objectives). No matter the priority, the Nscale Support team aims to provide an outstanding service. We don't change how we interact with tickets based upon their review score. ## Additional Support Resources If you're unsure how to use the portal, contact your Nscale Account Manager or Sales Partner, or email [helpdesk@nscale.com](mailto:helpdesk@nscale.com) for assistance. ## Need to Escalate? > **[Contact Escalations Team](mailto:escalations@nscale.com)** > > For urgent escalations, please contact our escalations team at [escalations@nscale.com](mailto:escalations@nscale.com) # Logs for troubleshooting Source: https://docs.nscale.com/docs/help/logs-for-troubleshooting Manual log collection expectations for NVIDIA GPU infrastructure support cases. This page explains which logs and context to provide when opening a support ticket for NVIDIA GPU infrastructure hosted by Nscale, without using the Nscale Log Gatherer package. The standard manual collection is: * The NVDebug Redfish/BMC support bundle, including generated files and reports, plus host logs when available and the NVDebug console log. * NVIDIA `nvidia-bug-report.sh` output. Run commands with `sudo` or as root where possible so kernel, driver, hardware, and service logs are complete. ## Before you collect logs Collect logs as close to the failure time as possible. If the host is still running, collect logs before rebooting unless there is an operational reason to recover the system first. Include this context with every support request: | Field | What to include | | - | - | | Site or region | The affected Nscale site, region, or deployment identifier. | | Asset | Hostname, node name, switch name, rack ID, or serial number. | | Component | GPU, NVLink, NIC/HCA, NIC/DPU, BMC, CPU, FAN, PSU, HDD/SSD, System Board, Power Cycle, Chassis, CDU, or Other/Unknown. | | Failure time | Approximate start time, end time if known, and timezone. | | Symptoms | Error messages, alerts, Xid/SXid values, missing devices, link state, throttling, power event, or workload behavior. | | Impact | Whether the issue affects one GPU, one node, one rack, multiple racks, a cluster, or customer workloads. | | Current state | Whether the device is online, drained, rebooted, powered off, replaced, or ready to be worked on. | | Actions taken | Reseats, reboots, power cycles, counter clears, workload moves, cable cleanings, replacements, or other remediation already attempted. | ## Severity guide Use the severity that reflects actual business or service impact: | Severity | Use when | | - | - | | Critical | The customer environment is inaccessible or reserved capacity cannot reasonably be consumed. | | High | The environment is accessible, but important functionality is unavailable and there is no acceptable workaround. | | Medium | Functionality is impacted, but a workaround exists or the customer can continue using the environment. | | Low | There is a minor issue, question, or no material production impact. | ## Dependencies For the manual path: * Linux on the target NVIDIA GPU host or on a remote collection host that can reach the BMC and, when needed, the host OS. * `sudo` or root access is strongly recommended. * NVIDIA driver tooling, including `nvidia-smi` and ideally `nvidia-bug-report.sh`. * Python 3.12 and Python venv support for NVDebug. * `curl` or another approved method to download from GitHub. * `unzip`, `tar`, and `gzip`. * `ipmitool` for NVDebug IPMI-over-LAN collection. * BMC network access and credentials for the standard Nscale NVDebug bundle. On Ubuntu, the usual setup is: ```bash theme={null} bash <<'EOF' set -euo pipefail sudo apt-get update sudo apt-get install -y python3.12 python3.12-venv python3-pip curl unzip tar gzip ipmitool EOF ``` Do not install extra diagnostic tools unless Nscale Support specifically asks for them. ## Create a working directory Copy and paste this as one block. It creates the working directory and stores the path so later copy/paste blocks can find it. ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=/tmp/nscale_manual_logs_$(hostname -s)_$(date -u +%Y%m%dT%H%M%SZ) mkdir -p "$LOGDIR" printf '%s\n' "$LOGDIR" > /tmp/nscale_manual_logdir.path echo "Log directory: $LOGDIR" EOF ``` ## Collect the NVDebug support bundle NVDebug is NVIDIA's diagnostic collection tool for NVIDIA server platforms. The downloadable GitHub project is named [`open-nvdebug`](https://github.com/NVIDIA/open-nvdebug); this guide refers to the tool as NVDebug. For the full vendor reference, see the [NVIDIA NVDebug User Guide](https://docs.nvidia.com/multi-node-nvlink-systems/nvdebug-guide/index.html). For Nscale support cases, the important artifact is the generated NVDebug support bundle, not only the terminal output. The expected bundle contains both host-side logs and BMC/Redfish telemetry. Do not submit host-only or BMC-only collection unless absolutely necessary or Nscale Support explicitly asks for it. Why this guide asks for BMC details: NVDebug can run locally without BMC credentials, but that is a reduced host-local collection. NVIDIA documents that BMC-related collectors are skipped in that mode. For normal Nscale support, provide the BMC IP or hostname and credentials so the bundle includes Redfish/BMC and IPMI evidence. In most environments, the same BMC account is used for Redfish and IPMI access. Install `ipmitool` on the machine where NVDebug runs. In most cases, this is the affected host. Do not include this package or binary in the final support archive; it is only a runtime prerequisite for NVDebug's IPMI-over-LAN collectors. `sshpass` is not required for the normal affected-host workflow in this guide. Nscale Support may ask for it only for a specific SSH-based collection path, such as some jumphost, BMC SSH, HMC SSH, proxy, or tunnel workflows. In most cases, run the next two commands on the affected host. The first command downloads NVDebug from the `open-nvdebug` GitHub repository and prepares it in a local Python virtual environment. The `requirements.txt` file is included in the downloaded `open-nvdebug` package and installs NVDebug's Python dependencies. This guide uses `nvdebug-v2.1.0-release`; use a different release only if Nscale Support asks you to. ### Download NVDebug and set up the environment ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" NVDEBUG_TAG=nvdebug-v2.1.0-release curl -L -o open-nvdebug.zip "https://github.com/NVIDIA/open-nvdebug/archive/refs/tags/${NVDEBUG_TAG}.zip" unzip open-nvdebug.zip cd "open-nvdebug-${NVDEBUG_TAG}" python3.12 -m venv .venv . .venv/bin/activate python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt python -m src.tool.main --version > "$LOGDIR/nvdebug-version.txt" 2>&1 printf '%s\n' "$PWD" > /tmp/nscale_manual_nvdebug_dir.path echo "NVDebug prepared under: $PWD" EOF ``` ### Run NVDebug and generate the support bundle Run this block on the affected host. The affected host must be able to reach its BMC. This is the preferred collection path for most customers because NVDebug collects host logs locally and BMC/Redfish telemetry through the BMC details you enter. Do not paste passwords directly into the command line. The block below prompts for the required BMC/Redfish/IPMI details, creates the temporary NVDebug configuration automatically, runs NVDebug, and removes the temporary config file afterward. ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) NVDEBUG_DIR=$(cat /tmp/nscale_manual_nvdebug_dir.path) DUT_CONFIG="$LOGDIR/nvdebug-local-host-dut_config.json" : > "$DUT_CONFIG" chmod 600 "$DUT_CONFIG" "$NVDEBUG_DIR/.venv/bin/python" - "$DUT_CONFIG" <<'PYCONFIG' import getpass import json import sys from pathlib import Path bmc_ip = input("BMC IP or hostname: ").strip() bmc_user = input("BMC username: ").strip() bmc_pass = getpass.getpass("BMC password: ") baseboard = input("Baseboard override (optional, press Enter for auto-detect): ").strip() config = { "dut-1": { "local": True, "baseboard": baseboard, "BMC_IP": bmc_ip, "BMC_USERNAME": bmc_user, "BMC_PASSWORD": bmc_pass, } } Path(sys.argv[1]).write_text(json.dumps(config, indent=2)) PYCONFIG cd "$NVDEBUG_DIR" trap 'rm -f "$DUT_CONFIG"' EXIT sudo "$PWD/.venv/bin/python" -m src.tool.main collect --dut-config "$DUT_CONFIG" -o "$LOGDIR/nvdebug-host-bmc" > "$LOGDIR/nvdebug-host-bmc.stdout.txt" 2>&1 echo "NVDebug generated files: $LOGDIR/nvdebug-host-bmc" echo "NVDebug console log: $LOGDIR/nvdebug-host-bmc.stdout.txt" EOF ```
Alternative: run NVDebug from a jumphost Use this when you cannot run NVDebug directly on the affected host. The jumphost must be able to reach both the BMC and the affected host OS over SSH so the bundle still contains both BMC/Redfish telemetry and host-side logs. ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) NVDEBUG_DIR=$(cat /tmp/nscale_manual_nvdebug_dir.path) DUT_CONFIG="$LOGDIR/nvdebug-jumphost-dut_config.json" : > "$DUT_CONFIG" chmod 600 "$DUT_CONFIG" "$NVDEBUG_DIR/.venv/bin/python" - "$DUT_CONFIG" <<'PYCONFIG' import getpass import json import sys from pathlib import Path bmc_ip = input("BMC IP or hostname: ").strip() bmc_user = input("BMC username: ").strip() bmc_pass = getpass.getpass("BMC password: ") host_ip = input("Affected host IP or hostname: ").strip() host_user = input("Host username with sudo access: ").strip() host_pass = getpass.getpass("Host password: ") baseboard = input("Baseboard override (optional, press Enter for auto-detect): ").strip() config = { "dut-1": { "baseboard": baseboard, "BMC_IP": bmc_ip, "BMC_USERNAME": bmc_user, "BMC_PASSWORD": bmc_pass, "HOST_IP": host_ip, "HOST_USERNAME": host_user, "HOST_PASSWORD": host_pass, } } Path(sys.argv[1]).write_text(json.dumps(config, indent=2)) PYCONFIG cd "$NVDEBUG_DIR" trap 'rm -f "$DUT_CONFIG"' EXIT sudo "$PWD/.venv/bin/python" -m src.tool.main collect --dut-config "$DUT_CONFIG" -o "$LOGDIR/nvdebug-jumphost" > "$LOGDIR/nvdebug-jumphost.stdout.txt" 2>&1 echo "NVDebug generated files: $LOGDIR/nvdebug-jumphost" echo "NVDebug console log: $LOGDIR/nvdebug-jumphost.stdout.txt" EOF ```
Include the full generated NVDebug output directory and its matching console log: `nvdebug-host-bmc/` plus `nvdebug-host-bmc.stdout.txt`, or `nvdebug-jumphost/` plus `nvdebug-jumphost.stdout.txt` if you used the jumphost block. If NVDebug cannot collect both host logs and BMC/Redfish telemetry, include any `nvdebug*.stdout.txt` or Python error output and tell Nscale Support which access path failed. ## Collect NVIDIA bug report ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" (cd "$LOGDIR" && sudo nvidia-bug-report.sh) > "$LOGDIR/nvidia-bug-report.stdout.txt" 2>&1 echo "NVIDIA bug report output saved under: $LOGDIR" EOF ``` If `nvidia-bug-report.sh` creates `nvidia-bug-report.log.gz`, leave it in `$LOGDIR` so it is included in the final archive. ## Add failure-specific logs | Failure type | Expected logs | | - | - | | GPU missing from `nvidia-smi`, GPU fallen off bus, driver error, Xid/SXid/NVRM, PCIe or enumeration issue | Standard manual collection. Include affected GPU index/UUID/serial, Xid/SXid if known, and the failure timestamp. | | GPU ECC, SRAM/DRAM, row remapper, page retirement, memory error, or suspected GPU memory fault | Standard manual collection. Include affected GPU index/UUID/serial, observed ECC or row-remapper alert, and workload impact. | | NVLink, NVSwitch, Fabric Manager, IMEX, NVLSM, OpenSM, Fabric state, training, Xid 145, or Xid 149 issue | Standard manual collection from each affected compute host. For NVL systems, include switch-side NVOS tech-support or NVSwitch logs when available or requested. | | Thermal, fan, power, throttling, PSU, or voltage issue | Standard manual collection. Include the NVDebug Redfish/BMC bundle when BMC access is available, plus facility alarms, sensor exports, or photos/screenshots when useful. | | Unexpected reboot, node power loss, power cycle, or suspected BMC event | Standard manual collection after the host is back online. Include the NVDebug Redfish/BMC bundle when BMC access is available. Include exact reboot or outage time if known. | | Host unresponsive, CPU soft or hard lockup, hung task, watchdog warning, or RCU stall | Standard manual collection plus the complete BMC serial-over-LAN (SOL) console capture. Include the exact failure and recovery times, workload or job details, previous-boot journals, pstore files, and any kernel crash-dump inventory. | | NVMe, disk I/O, filesystem, Linux MD RAID, or hardware RAID issue | Standard manual collection. Include the affected device path, mount point, or volume if known. Nscale Support may request storage-specific command output after initial triage. | | System memory, CPU, MCE, EDAC, RAS, OOM, or host-level thermal issue | Standard manual collection. Include any visible machine-check, EDAC, OOM, DIMM slot, CPU socket, or sensor alert details. | | Ethernet switch device issue | Device logs, CLI command output, interface state and error counters, environmental or hardware alerts, and screenshots when available. Include switch asset, site, component, current state, and impact. | | Ethernet link issue | Endpoint A and Port A, Endpoint B and Port B if known, plus command output for both sides where available: `net show interface detail`, `net show interface pluggables`, and `sudo l1-show `. Include link state, counters, cleaning or optics replacement attempts, and impact. | | InfiniBand switch device issue | Device logs, UFM or fabric health evidence, port state and error counters, environmental or hardware alerts, and screenshots when available. Include switch asset, site, component, current state, and impact. | | InfiniBand link issue | Endpoint A and Port A, Endpoint B and Port B if known, UFM evidence, and `mlxlink -d lid -p -c` output. Note whether the port was isolated in UFM and whether `perfquery -x ` was run as part of your normal process. | | Rack issue | Rack ID, affected rack unit/side/bay/PDU, photos or screenshots, related device logs, power or environmental evidence, and any impacted host logs. | | Facility, cooling, rPDU, or widespread power issue | Site, affected racks/rows/clusters/devices, start time, current state, alarm screenshots, rPDU or facility exports, photos when useful, and sample host logs from impacted nodes. | ## Targeted add-on commands Run these only when the issue type matches or Nscale Support asks for them. Skip commands that are not available on the host and note that they were unavailable in the support request. ### GPU missing, Xid/SXid, PCIe, NVLink, or fabric ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" nvidia-smi -q > nvidia-smi-q.txt 2>&1 nvidia-smi topo -m > nvidia-smi-topo-m.txt 2>&1 nvidia-smi nvlink -s > nvidia-smi-nvlink-s.txt 2>&1 nvidia-smi nvlink --errorcounters > nvidia-smi-nvlink-errorcounters.txt 2>&1 nvidia-smi --query-gpu=index,name,uuid,serial,pci.bus_id,temperature.gpu,memory.total,memory.used,memory.free,power.draw --format=csv > nvidia-smi-query-gpu-health.csv 2>&1 nvidia-smi --query-gpu=index,serial,uuid,pci.bus_id,fabric.state,fabric.status --format=csv > nvidia-smi-query-fabric-status.csv 2>&1 sudo dmesg -T | grep -Ei 'Xid|SXid|NVRM|fallen off|PCIe|AER|nvidia|nvswitch|nvlink|fabric' > dmesg-gpu-fabric-filtered.txt 2>&1 EOF ``` **Active diagnostics:** Run `dcgmi diag -r 4` only when Nscale Support asks for it or when the host is available for a long-running active diagnostic. ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" sudo dcgmi diag -r 4 > dcgmi-diag-r4.txt 2>&1 EOF ``` ### GPU ECC, memory, row remapper, or page retirement ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" nvidia-smi -q -d ECC > nvidia-smi-q-d-ecc.txt 2>&1 nvidia-smi -q -d MEMORY > nvidia-smi-q-d-memory.txt 2>&1 nvidia-smi -q -d ROW_REMAPPER > nvidia-smi-q-d-row-remapper.txt 2>&1 nvidia-smi -q -d PAGE_RETIREMENT > nvidia-smi-q-d-page-retirement.txt 2>&1 sudo dmesg -T | grep -Ei 'ECC|row|remap|retire|SRAM|DRAM|memory error|Xid|NVRM|MCE|EDAC|RAS' > dmesg-memory-ecc-filtered.txt 2>&1 EOF ``` ### Unexpected reboot, power cycle, or host reset ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" sudo journalctl --list-boots --no-pager > journalctl-list-boots.txt 2>&1 last -x reboot shutdown -F > last-reboot-shutdown.txt 2>&1 who -b > who-b.txt 2>&1 uptime -s > uptime-s.txt 2>&1 EOF ``` ### Host unresponsive, CPU lockup, hung task, watchdog, or RCU stall Keep the BMC SOL console recording from before the first warning until the host recovers or is restarted. Include the complete console output, including kernel call traces; a screenshot containing only repeated watchdog summary lines is not sufficient. If the host is partially responsive, run this before restarting it: ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" sudo ps -eLo pid,tid,ppid,psr,cls,rtprio,pri,ni,stat,wchan:32,comm,args > ps-threads-during-lockup.txt 2>&1 EOF ``` If Magic SysRq works through SOL, capture these diagnostic dumps one at a time and wait for each dump to finish: * `Alt+SysRq+l`: backtrace all active CPUs. * `Alt+SysRq+t`: dump all tasks. * `Alt+SysRq+w`: dump tasks blocked in uninterruptible state. Do not use SysRq `b` (immediate reboot) or `c` (forced crash) unless Nscale Support explicitly coordinates it. A forced crash is useful only when kernel crash dumping has already been configured and tested. After the host recovers or restarts, run this promptly, before previous-boot records rotate: ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" mkdir -p pstore-after-lockup sudo journalctl --list-boots --no-pager > journalctl-list-boots.txt 2>&1 sudo journalctl -k -b -1 --utc -o short-precise --no-pager > journal-kernel-previous-boot.txt 2>&1 sudo journalctl -b -1 --utc -o short-precise --no-pager > journal-all-previous-boot.txt 2>&1 sudo cp -a /sys/fs/pstore/. pstore-after-lockup/ 2>/dev/null || true sudo find /var/crash -maxdepth 3 -type f -printf '%TY-%Tm-%TdT%TH:%TM:%TSZ %s %p\n' > var-crash-inventory.txt 2>&1 uname -a > uname-a.txt 2>&1 cat /etc/os-release > os-release.txt 2>&1 cat /proc/cmdline > proc-cmdline.txt 2>&1 sudo sysctl \ kernel.watchdog kernel.watchdog_thresh kernel.nmi_watchdog \ kernel.softlockup_panic kernel.hardlockup_panic \ kernel.softlockup_all_cpu_backtrace kernel.hardlockup_all_cpu_backtrace \ kernel.panic > kernel-watchdog-sysctls.txt 2>&1 systemctl status kdump-tools --no-pager > kdump-tools-status.txt 2>&1 || true sudo kdump-config show > kdump-config-show.txt 2>&1 || true EOF ``` Include the workload scheduler job ID, container image and command, framework and communication-library versions, and whether the same workload was running on every affected node. Also note whether SSH, ping, monitoring, BMC sensors, and SOL remained responsive. The process name printed in a lockup warning identifies the task that was current when the watchdog fired. It does not, by itself, identify the faulty application, kernel component, or device driver. Preserve any `vmcore` listed under `/var/crash`, but do not attach it to the ticket archive unless Nscale Support provides an approved transfer method; crash dumps can be large and may contain sensitive data. ### NVMe, disk, filesystem, or RAID ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" df -hT > df-hT.txt 2>&1 lsblk -a -o NAME,KNAME,PATH,SIZE,TYPE,FSTYPE,MOUNTPOINTS,MODEL,SERIAL,WWN,VENDOR,STATE,TRAN > lsblk.txt 2>&1 cat /proc/mdstat > proc-mdstat.txt 2>&1 nvme list > nvme-list.txt 2>&1 for dev in /dev/nvme*n1; do [ -e "$dev" ] || continue; sudo nvme smart-log "$dev"; done > nvme-smart-log.txt 2>&1 for dev in /dev/nvme*n1; do [ -e "$dev" ] || continue; sudo nvme error-log "$dev"; done > nvme-error-log.txt 2>&1 sudo dmesg -T | grep -Ei 'I/O error|blk_update_request|buffer I/O|medium error|critical warning|nvme|md/|raid|scsi|sas|sata|smart|xfs|ext4|btrfs|reset|timeout' > dmesg-storage-filtered.txt 2>&1 EOF ``` ### System memory, CPU, MCE, EDAC, RAS, OOM, or host thermal ```bash theme={null} bash <<'EOF' set -u LOGDIR=$(cat /tmp/nscale_manual_logdir.path) cd "$LOGDIR" free -h > free-h.txt 2>&1 cat /proc/meminfo > proc-meminfo.txt 2>&1 lscpu > lscpu.txt 2>&1 sudo dmidecode -t memory > dmidecode-memory.txt 2>&1 sensors > sensors.txt 2>&1 sudo dmesg -T | grep -Ei 'MCE|EDAC|RAS|ECC|memory error|hardware error|machine check|out of memory|oom|thermal|overheat|temperature|throttl' > dmesg-memory-ras-thermal-filtered.txt 2>&1 EOF ``` ## Create the archive ```bash theme={null} bash <<'EOF' set -euo pipefail LOGDIR=$(cat /tmp/nscale_manual_logdir.path) ARCHIVE=/tmp/$(basename "$LOGDIR").tar.gz sudo tar -czf "$ARCHIVE" -C /tmp "$(basename "$LOGDIR")" sudo chown "$(id -u):$(id -g)" "$ARCHIVE" 2>/dev/null || true echo "$ARCHIVE" EOF ``` Attach the `.tar.gz` archive to tickets created in Jira with the context listed at the top of this page. ## Alternative Customers who approve the use of the packaged automated collector can use the Nscale Log Gatherer to collect the same diagnostic information in a single support bundle. Because the Nscale Log Gatherer is provided as a Python script, you can easily review its contents to verify exactly what data is collected before executing it. ## Data notice Support bundles may include hostnames, IP addresses, serial numbers, kernel logs, package versions, NVIDIA diagnostic output, BMC details, storage health data, and other operational metadata. Review the archive before sharing it if your environment requires data screening. # Service Level Objectives Source: https://docs.nscale.com/docs/help/service-level-objectives Nscale Technical Support Service Level Objectives ### Support Hours and Communications Support is provided according to the Nscale service model in use: * **Nscale Cloud Customers** - support available via email only at [helpdesk@nscale.com](mailto:helpdesk@nscale.com). This channel is used for questions, troubleshooting, and issue reporting. * **Nscale Private Cloud Customers –** are provided access to the Nscale Support Portal, which offers ticket submission and tracking, case history, and knowledge resources. Nscale will provide full support for service incidents and requests in accordance with the following table: | **Priority** | **Platinum Support Hours** | **Gold Support Hours** | **Silver Support Hours** | **Initial Response Time** | **Resolution Target** | | - | - | - | - | - | - | | P1 (Critical) | 24x7, 365 days | 24x7, 365 days | 0900 – 1700 Local DC Time | 15 Minutes | 4 hrs | | P2 (High) | 24x7, 365 days | 0900 – 1700 Local DC Time | 0900 – 1700 Local DC Time | 1 Hour | 24 hrs | | P3 (Medium) | 24x7, 365 days | 0900 – 1700 Local DC Time | 0900 – 1700 Local DC Time | 1 Hour | 1 week | | P4 (Low) | 24x7, 365 days | 0900 – 1700 Local DC Time | 0900 – 1700 Local DC Time | 1 Hour | 1 month | | Request | 24x7, 365 days | 0900 – 1700 Local DC Time | 0900 – 1700 Local DC Time | 1 Hour | 1 month | ### Priority Levels Priority Levels are dependent on the impact and urgency responses provided by the reporter. The definition for the Incident Priority levels can be found below. This list is non-exhaustive, and the grading of the final priority falls with Nscale Support Engineers after taking incident details and customer impact into account. > **P1 (Critical)** > > A critical incident causing a **complete system outage** or **severe degradation of production infrastructure**, resulting in an inability to consume Nscale services. Core operations are entirely halted, requiring immediate intervention to restore service. > **P2 (High)** > > Operations can continue in a limited capacity, though long-term productivity may be affected. Heavily degraded compute performance incidents, where services are still available and rendered usable, fall under this priority. Additionally, it can cover management plane outages where core operations continue, but management tasks, like configuration or monitoring, are impaired. > **P3 (Medium)** > > A partial, non-critical loss of functionality that affects some aspects of the system but does not prevent overall operations. Users may experience intermittent issues or limited access to certain features, but the primary Nscale services and systems remain operational. This priority level includes problems where a workaround exists, allowing users to continue their work with some inconvenience. > **P4 (Low)** > > Minor issues or anomalies that have little to no impact on operations. These include cosmetic issues, performance issues that do not significantly affect user experience, and problems that have a simple workaround. Users can continue working with minimal inconvenience. > **Requests** > > General usage enquiries, documentation errors, product feature requests, and requests for assistance. ### Scheduled Maintenance Nscale performs regular scheduled maintenance, including service upgrades, enhancements, and general maintenance. During these periods, Nscale services may experience limited availability. We will provide a minimum of one (1) week's notice before any potentially disruptive maintenance. For potentially disruptive maintenance, they will be performed outside of core office hours to minimize impact to customer operations. Maintenance notifications will be provided via the Announcements page on the Support Portal, where the impacted components and timescale for the maintenance period will be detailed. ### Emergency Maintenance In cases of service degradation or urgent security vulnerabilities, Nscale may perform emergency maintenance, which could result in temporary unavailability of the Nscale infrastructure. We aim to avoid core office hours however, to quickly restore or safeguard the services, this is not always possible. We will communicate updates regarding the status of the maintenance via Announcements in the Support Portal. ### Service Outages Where a service incurs (or is at risk of) an outage, we will provide notifications and regular updates via Announcements in the Support Portal. ### Service Credits Service Credits for breached Service Level Agreements (SLAs) are outlined in the contract and represent the remedy available. ## Need to Escalate? Please contact our escalations team at [escalations@nscale.com](mailto:escalations@nscale.com) # Shared Responsibility Model Source: https://docs.nscale.com/docs/help/shared-responsibility How responsibility for security, privacy, and operations is divided between you and Nscale across our AI Services. Nscale operates and secures the AI Services platform. You own the content, configuration, and access decisions inside your account. The matrix below sets out where each responsibility sits for Serverless inference. > [!NOTE] > > This page covers AI Services. Compute, networking, and storage products have separate boundaries — contact [helpdesk@nscale.com](mailto:helpdesk@nscale.com) for product-specific guidance. ## Legend | Marker | Meaning | | - | - | | Yours | You configure, supply, or operate this control. | | Shared | Both parties contribute; obligations are split. | | Nscale | Nscale implements, operates, and assures this control. | | n/a | Not applicable to this service. | ## Your layer Controls you configure, supply, or operate. Nscale has no visibility into the substance of these decisions and cannot assume responsibility for them. | Control | Serverless inference | | - | :-: | | Prompt & query content | Yours | | Service tokens & access control | Yours | | Application & integration code | Yours | | Input / output data retention & privacy | Yours | | Regulatory & legal compliance | Yours | | Model & inference parameters | Yours | ## Boundary Controls where obligations are split. Nscale provides the underlying capability; you are responsible for using it correctly within your application and operational processes. | Control | Serverless inference | | - | :-: | | Encryption in transit (TLS) | Shared | | Billing & usage monitoring | Shared | | Incident response & notification | Shared | ## Nscale layer Controls Nscale implements, operates, and assures on your behalf as part of the managed service. | Control | Serverless inference | | - | :-: | | Base model weights & updates | Nscale | | Inference serving runtime | Nscale | | Autoscaling & availability SLA | Nscale | | GPU compute & virtualisation | Nscale | | Network security & DDoS protection | Nscale | | Physical infrastructure & data center | Nscale | ## Related * [Service Level Objectives](/docs/help/service-level-objectives) — support hours, response targets, and incident priority definitions. * [Terms](/docs/help/terms) — contractual terms governing your use of Nscale services. # Terms Source: https://docs.nscale.com/docs/help/terms # Auto-recharge Source: https://docs.nscale.com/docs/manage/auto-recharge Auto-recharge tops up your credit balance automatically when it runs low, so your AI services keep running. You set a threshold and a target balance. When your balance reaches the threshold, we charge your default payment card and restore your balance to the target. ## **Setting up auto-recharge** Auto-recharge requires a default payment card on your account. See [Credit](/docs/manage/credit) for how to add and manage cards. To turn on auto-recharge: * Navigate to **Usage & Billing** section and click the **Credit** tab. * On the **Auto-recharge** card, click **Set up auto-recharge**. * Set **When balance falls below**: the balance that triggers a recharge. * Set **Restore balance to**: the balance each recharge restores you to. * Review your settings and click **Save and enable**. ![The set up auto-recharge dialog with threshold and target balance fields](https://mintcdn.com/nscale/06Gp17d5Fs92h0IG/images/auto-recharge-setup.png?fit=max\&auto=format\&n=06Gp17d5Fs92h0IG\&q=85\&s=7c2a773c07e3ad746f562db187c3f4f0) **Amount limits**: > [!NOTE] > > The minimum threshold is \$5. The target balance must be at least \$10 above your threshold, up to a maximum of \$1,000. ## **How recharges work** When your credit balance reaches your threshold, we charge your default payment card the difference between your current balance and your target balance. If your threshold is \$20, your target is \$50 and your balance falls to \$18, your card is charged \$32. > [!NOTE] > > Enabling auto-recharge, or editing its amounts, can charge your card immediately if your balance is already below the threshold. The console shows this warning before you confirm. For every recharge: * Your balance is restored to the target shortly after payment succeeds. * You receive an invoice from Stripe and a confirmation email from Nscale. The recharge also appears in your in-app notifications. ## **If a payment fails** If a recharge payment is declined, auto-recharge is turned off automatically and no credit is added. You receive an email and an in-app notification, and the **Auto-recharge** card shows the failure with the reason from your card provider. To resume: * Check your card in the **Billing Details** tab, and update it if needed. * Return to the **Auto-recharge** card and turn auto-recharge back on. Your threshold and target balance are kept, and a recharge is attempted right away if your balance is below your threshold. Low balance warning emails resume while auto-recharge is off, so your account is never without a safety net. ## **Editing and turning off** * To change your amounts, click **Edit auto-recharge** on the **Auto-recharge** card. * To turn auto-recharge off, use the toggle on the card. Your settings are remembered and apply again when you turn it back on. ![The auto-recharge card on the Credit tab showing the configured threshold and target balance](https://mintcdn.com/nscale/06Gp17d5Fs92h0IG/images/auto-recharge-card.png?fit=max\&auto=format\&n=06Gp17d5Fs92h0IG\&q=85\&s=fe7804883bc8dae25bb6a68f7671354b) > [!NOTE] > > You can enable or edit auto-recharge up to five times in 24 hours. If you reach the limit, wait and try again later, or contact support. > **[Get support](mailto:helpdesk@nscale.com)** > > Need help with billing? Reach out to our support team to get help. # Credit Source: https://docs.nscale.com/docs/manage/credit Nscale AI services use a credit-based billing system. To access AI services, you’ll need to purchase credits, which are deducted as you consume resources. You can monitor your balance, usage, and transaction history in the Usage & Billing section. ## **Purchasing credits** To use the Nscale services, you'll need to purchase credits. Here's how: **Adding credits via the console**: * Navigate to **Usage & Billing** section and click the **Credit** tab. * Select or type in the amount you'd like to purchase. * Follow the Stripe payment flow to securely complete your transaction and add funds to your account. If applicable taxes apply in your jurisdiction, they are calculated and displayed during checkout. Business customers can enter a VAT or tax ID to apply reverse-charge or zero-rate treatment automatically. * Upon successful transaction, the credits will be added to your account balance. The credited amount is the pre-tax subtotal you selected. **Minimum and maximum purchase limits**: > [!NOTE] > > The platform supports credit purchases from \$5 up to a maximum of \$10,000 per transaction. **Auto-recharge**: You can also recharge your balance automatically when it runs low. See [Auto-recharge](/docs/manage/auto-recharge). ## **Transaction history and receipts** **Viewing Transactions in the Credit Section**: * Navigate to **Usage & Billing** section and click the **Credit** tab.. * Displayed below your balance is all of your credit purchase transactions **Receiving Receipts via Email**: * For every credit purchase, a receipt is automatically sent to your registered email address. * This email will include the billing details added to your account. If no billing details are added to your account, we will take the billing details added to Stripe during the purchase flow. ## **Adding billing details** To ensure your receipts contain the right information, keep your billing details up-to-date: * Navigate to **Usage & Billing** section and click the **Billing Details** tab. * **Entering Billing Information**: Provide necessary details such as your name, address, and contact information. * **Saving Changes**: Ensure all information is accurate and save the changes to update your billing profile. ## **Managing credit cards** Efficient management of your payment methods ensures seamless transactions. Here's how to handle credit cards within the platform: **Adding a credit card**: * Navigate to **Usage & Billing** section and click the **Billing Details** tab. * In the **Payment Cards** section, select **Add New Card**. * Enter your credit card details, including card number, expiration date, and CVV. * Save the information to add the card to your account. > [!NOTE] > > Nscale accepts all major credit cards **Setting a default credit card**: * Navigate to **Usage & Billing** section and click the **Billing Details** tab. * Identify the card you wish to set as default. * Click on **Make default** next to the chosen card. * This card will now be used for all future purchases unless changed. **Deleting a credit card**: * Navigate to **Usage & Billing** section and click the **Billing Details** tab. * Click on 'Delete' adjacent to the respective card. * Confirm the deletion when prompted. Note: Ensure you have at least one active payment method to avoid service interruptions. ## **Payment methods accepted** Nscale accepts all major credit cards, providing a wide range of options for users to manage their payments conveniently. > **[Get support](mailto:helpdesk@nscale.com)** > > Need help with billing? Reach out to our support team to get help. # Monitoring usage Source: https://docs.nscale.com/docs/manage/monitoring-usage You can monitor your usage and spend in the Usage & Billing section to manage costs, optimise workloads, and prevent unexpected credit depletion. ## Inference usage The **Usage & Billing** section provides real-time insights into your inference usage and credit spend, helping you manage costs effectively. The **Inference Usage** section offers a visual breakdown of your spending over a selected time period, updated daily. Here's how it can help: * **Track Trends** – Identify usage patterns over time to understand peak and low-demand periods. * **Optimise Costs** – Spot excessive spending and adjust workloads to improve efficiency. * **Plan Ahead** – Forecast future credit needs based on past usage trends. * **Compare Usage** – Toggle between different timeframes (daily, weekly) to analyse changes in consumption. ![](https://mintcdn.com/nscale/5cvpEeN1jrpcQB9B/images/usage-and-billing.png?fit=max\&auto=format\&n=5cvpEeN1jrpcQB9B\&q=85\&s=b715e3c3f330e71dd95e0f37a90c212c) # Projects Source: https://docs.nscale.com/docs/manage/projects Understand how projects group and isolate your resources across Nscale services. ## What is a project? A **project** is a logical container for your Nscale resources. It provides an isolation boundary for: * Compute resources (instances, reservations) * Networking (VPCs, security groups) * Storage and other shared services Projects help you organise workloads by team, environment (e.g., staging vs. production), or application, and make it easier to reason about where resources live. ## What lives inside a project? When you create resources in Nscale, you place them into a project. For example: * **Instances** – virtual machines you create from the **Compute → Instances** page * **Kubernetes clusters** – managed clusters you create from the **Services → Kubernetes** page * **Networks and security controls** – VPC networks and security groups associated with the project * **Storage** – file storage and object storage endpoints scoped to the project These resources are associated with a single project at creation time so that usage, access, and configuration are grouped together. ## Creating and managing projects You can create and manage projects directly from the Nscale Console. At a high level: 1. From the Console, select **All Projects** in the left navigation. The projects page displays your projects as cards showing the name, description, and creation date. 2. Use the **search field** to filter projects by name or description. 3. Create a new project and give it a clear, descriptive name (for example, `team-ml-prod` or `payments-staging`). 4. Use this project when creating instances, clusters, and related resources so they are grouped together. You can return to **All Projects** at any time to review existing projects. Click the menu on any project card to navigate directly to that project's settings. ## How projects show up across services Many flows in the console ask you to choose a **project**, including: * Creating a new **instance** from **Compute → Instances** * Creating a new **Kubernetes cluster** from **Services → Kubernetes** * Creating a new **VPC** from **Network → VPCs** * Creating **object storage** from **Storage → Object Storage** In these flows, the selected project determines **where** the new resource is created and which other project-scoped resources (like networks and security groups) it can see. If you are unsure which project to use, align with your team’s conventions (for example, one project per environment or per team) before creating long‑lived resources. ## Notes and limitations Projects are designed to be stable containers for your workloads. In general, resources are created into a project and managed there for their lifetime. If you need to reorganise how your workloads are grouped, plan ahead and coordinate any resource moves or recreations with your team. # Reporting Nvidia GPU Instance Errors to Nscale Support Source: https://docs.nscale.com/docs/manage/reporting-an-incident ## Before You Begin * You have ran and obtained the output from `nvidia-bug-report.sh` * You have recorded the affected `Instance name` and `Instance ID`. * You have your `Organisation Name` and `Organisation ID`. ## Deprovisioning the Instance ***Once*** you have recorded the necessary prerequisite information, including logs and IDs, you should deprovision your instance using the Nscale Console. This allows the Nscale Support team to act promptly to perform breakfix investigations on the affected GPU node. ## Raising a ticket with Nscale Support **1. Log in** Log in to the [Nscale Ticketing Service](https://nscale.atlassian.net/servicedesk/customer/portals) **2. Create an Incident** Inside the ticket: 1. Provide a brief Summary of the issue. 2. In the description provide… 1. Your Organisation details. 2. The affected Instance name and ID. 3. What issue you are seeing? 4. A snippet from output showing the errors 5. How the issue can be reproduced. 3. Attach the output from `nvidia-bug-report.sh` **3. Submit your ticket** Submit the ticket to Nscale Support. We will use the information and get back to you as soon as possible. # Groups and roles Source: https://docs.nscale.com/docs/manage/roles-and-groups Control who can access your organization and what they can do, using groups, roles, and project scoping. Groups and roles control access to your organization. Members belong to **groups**, each group is granted one or more **roles** that define its permissions, and groups can be given access to specific **projects**. This lets you grant the right level of access to the right people, scoped to the right projects. > [!NOTE] > > **Availability:** Managing groups and roles is available to **private organizations**. The controls appear under **Settings → People** for members whose role allows managing access (for example, an administrator). ## How access works Access is layered, from the organization down to individual projects: | Concept | What it is | | - | - | | **Organization** | The top-level tenant that contains your members, groups, projects, and resources. | | **Member** | A person (or [service account](/docs/manage/service-tokens)) in the organization. | | **Group** | A collection of members, granted one or more roles. Members get their permissions through the groups they belong to. | | **Role** | A predefined set of permissions. Roles are assigned to groups, not to individuals. | | **Project** | A group can be scoped to specific projects, limiting where its access applies. See [Projects](/docs/manage/projects). | A member's effective access is the **combination of the roles on every group they belong to**—permissions are additive. A member can be in multiple groups, and a group can hold multiple roles. Members never get permissions directly. Access always flows down this hierarchy—a member belongs to groups, groups are granted roles, and roles are bundles of permissions: ```mermaid theme={null} flowchart TD Org([Organization]) Org --> Members[Members] Org --> Groups[Groups] Org --> Projects[Projects] Members -->|belong to| Groups Groups -->|are granted| Roles[Roles] Roles -->|are a bundle of| Permissions[Permissions] Groups -. can be scoped to .-> Projects ``` > [!NOTE] > > **Roles are predefined.** You assign existing roles to groups; you don't create custom roles in the Console. ## Roles All roles are listed in the Console. Roles you don't have permission to grant are shown as disabled. **Scope** tells you where a role applies: * **Organization**: applies across the whole organization, including every project. * **Project**: applies only within the projects the group is assigned to. * **Organization and project**: read access to shared organization items (such as flavors, images, regions, and quotas), plus the role's permissions in the projects the group is assigned to. ### General | Role | Scope | What it allows | | - | - | - | | **administrator** | Organization | Full control of the organization: manage members, groups, projects, service accounts, roles, identity providers, and all resources. | | **auditor** | Organization | Read-only access to everything in the organization. | | **public-administrator** | Organization | Manage service accounts, plus read-only access to the organization, groups, projects, quotas, and roles. | | **user** | Organization and project | Create and manage resources (instances, clusters, networks, security groups, load balancers, volumes, file and object storage) in the projects the group is assigned to. | | **reader** | Organization and project | Read-only access to resources in the projects the group is assigned to. | ### Reservations | Role | Scope | What it allows | | - | - | - | | **reservation-capacity-manager** | Organization | Create and delete reservations. View reservation units and topology. | | **reservation-capacity-reader** | Organization and project | View reservation units and topology across the organization, and reservations in assigned projects. | | **reservation-placement-user** | Project | Create and manage placements. View placement servers and reservations. | | **reservation-placement-operator** | Project | View and update placement servers. View placements. | | **reservation-placement-reader** | Project | Read-only access to placement servers and placements. | ### Radar | Role | Scope | What it allows | | - | - | - | | **fleet-operator** | Organization | Raise and view break-fix requests. View repair stats, resource stats, announcements, and topology. | > [!TIP] > > Assign the **least-privileged** role that lets a group do its job. Use **auditor** or **reader** for people who only need visibility, and reserve **administrator** for those who manage the organization. ## Who can manage groups and roles Two rules decide whether you can create or edit a group. Both must be satisfied. **1. Being in a group doesn't let you manage it.** Membership gives you the group's permissions; it does not give you control over the group. To create, edit, or change the members of a group you need a role that allows managing groups—typically **administrator**. A **user** or **reader** who belongs to a group still can't add people to it. **2. You can only assign roles you already hold.** To prevent anyone from granting access they don't have themselves, you can only give a group a role whose permissions you fully hold. This is why the role picker only lists roles you're allowed to assign—any role you couldn't grant is hidden. ### Why a group might not be editable Rule 2 also applies to a group's **existing** roles. Saving any change to a group re-checks every role already on it, so: > [!WARNING] > > If a group includes a role you don't have permission to grant, you can't edit that group **at all**—not its name, not its roles, and **not even its members**—until someone who holds those roles makes the change. This can be surprising: you might belong to a group and have an administrator role, yet still be unable to add a member, because the group also carries a more specialized role (for example, one of the reservation roles above) that your roles don't include. In the Console the group's edit and **Update Members** actions are disabled in this case, with a note explaining why. **Deleting still works.** You can delete such a group (if your role allows deleting groups), because deleting only *removes* access—it never grants a role—so it isn't subject to this rule. **What to do:** ask an organization administrator who holds the missing role to make the change, or have someone with the broader role added so the group's full set of roles can be granted. If you manage roles centrally, make sure your **administrator** role includes every permission used by the more specialized roles you expect administrators to assign. ## Manage members Members are managed from **Settings → People**, in the **Organization Members** card. The table shows each member's email, last active time, groups, and status: | Status | Meaning | | - | - | | **Pending** | The member has been invited but hasn't joined yet | | **Active** | The member has joined and can access the organization | | **Suspended** | The member's access is currently revoked | ### Invite a member **1. Open the People tab** Go to **Settings → People** and find the **Organization Members** card. **2. Invite members** Click **Invite Members**, then enter one or more email addresses (separated by commas), and select the **groups** the new members should belong to. **3. Send the invite** Click **Invite**. Each invited member appears with a **Pending** status until they join, after which they become **Active**. ### Remove a member In the **Organization Members** table, use the member's actions menu to remove them, then confirm. Removing a member permanently revokes their access to the organization. ## Manage groups Groups are managed from **Settings → People**, in the **Organization Groups** card. The table shows each group's name, the projects it can access, its members, and its roles. ### Create a group **1. Open the People tab** Go to **Settings → People** and find the **Organization Groups** card. **2. Create the group** Click **Create Group**, then set: * **Group Name** — can only contain lowercase alphanumeric characters and dashes. * **Role** — select one or more roles the group's members will have. * **Add members** — add the members who should belong to the group. **3. Save the group** Click **Create group**. The group appears in the Organization Groups list. ### Edit or delete a group Select a group to open its detail page: * **Group Details** — rename the group or change its roles. * **Group Members** — use **Add Members** to add people to the group. * **Delete Group** — permanently delete the group. You'll be asked to type the group's name to confirm. If the edit and **Update Members** actions are disabled, the group includes a role you're not allowed to grant—see [Why a group might not be editable](#why-a-group-might-not-be-editable). > [!WARNING] > > **Deleting a group is permanent.** It removes the group's access from every project it was assigned to. ## Give a group access to projects A group's access is scoped to the projects it's assigned to. You assign a group to a project from the **project's settings**, not from the group itself. Once assigned, the group's members gain that group's project-scoped permissions within that project. See [Projects](/docs/manage/projects) for how to manage project membership. ## Next steps * Manage groups from the command line with the [CLI](/docs/cli/groups). * Explore the [Groups API](/api-reference/groups/list-groups) and [Roles API](/api-reference/roles/list-roles). * Learn how [projects](/docs/manage/projects) organize resources and access. # Service tokens Source: https://docs.nscale.com/docs/manage/service-tokens Service Tokens (JWTs) provide scoped, time‑limited access for non‑human clients (e.g. backend services, cron jobs). Each token is a signed JSON Web Token that your services can present to authenticate against the Nscale API. ![](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/service-tokens.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=91b4edaf04b7f058cdad1cc74aa4d097) ## Steps to generate a Service Token The creation flow looks like this: 1. Navigate to **Settings → Service Tokens**. 2. Click **Create Service Token**. 3. Name your token. 4. Copy the token now—you won’t be able to view it again. > [!NOTE] > > Tokens can be rotated (regenerated) at any time without changing the Token ID or its access. Make sure you update your secret store with the new value. ## Refreshing a Service Token If you need a new JWT (e.g. a token was compromised or lost): 1. Find the token in the list and select **Rotate** from the table row actions. 2. Confirm the action. 3. Copy the new token immediately—you won’t see it again. ## Best Practices & Security * **Secure Storage** Keep Service Tokens in an encrypted vault (e.g. AWS Secrets Manager, HashiCorp Vault). * **Rotate Regularly** Refresh tokens before expiry to limit the impact of a leak. * **Immediate Blacklisting** Revoke any token immediately upon suspicion of compromise. *** ## Related > **[CLI: Service Accounts](/docs/cli/serviceaccounts)** > > Manage service accounts from the command line. # Terraform Provider Source: https://docs.nscale.com/docs/manage/terraform The Nscale Terraform provider lets you define and provision Nscale infrastructure as code. Declare your resources in `.tf` files, run `terraform plan` to preview changes, and `terraform apply` to create them. Use it for repeatable, version-controlled provisioning of VPCs, instances, clusters, security groups, and filesystems. > [!NOTE] > > **Prerequisite:** You need a [service token](/docs/manage/service-tokens) to authenticate the Terraform provider. ## Quick Start The provider is distributed via the Terraform Registry as `nscaledev/nscale`. Declare it in your `required_providers` block: ```hcl theme={null} terraform { required_providers { nscale = { source = "nscaledev/nscale" # Check the Terraform Registry or GitHub Releases for the latest version. # version = "~> 0.0.8" } } } ``` > [!NOTE] > > **Pin your provider version** in production to avoid unexpected changes when new versions are released. Use `version = "~> 0.0.8"` (or your current version) in the `required_providers` block. ## Authentication The provider authenticates with Nscale using a service token, which you can generate and rotate in the [Nscale Console](/docs/manage/service-tokens). ### Environment Variables The recommended way to configure the provider is via environment variables. This avoids hard-coding credentials in your `.tf` files: ```bash theme={null} export NSCALE_REGION_ID="" export NSCALE_ORGANIZATION_ID="" export NSCALE_PROJECT_ID="" export NSCALE_SERVICE_TOKEN="" ``` Alternatively, you can configure the provider block directly (not recommended for production): ```hcl theme={null} provider "nscale" { # Recommended: supply these values via environment variables, not hard-coded here. # region_id = "" # organization_id = "" # project_id = "" # service_token = "" } ``` ## Supported Resources The following table maps Terraform resource types to their corresponding console pages: | Terraform Resource | Description | Console Page | | - | - | - | | `nscale_network` | VPC networks | [VPC Networks](/docs/network/vpc-networks) | | `nscale_security_group` | Firewall rules | [Security Groups](/docs/network/security-groups) | | `nscale_file_storage` | Shared NFS filesystem | [Filesystem](/docs/storage/file-storage) | | `nscale_compute_instance` | Virtual machines | [Instances](/docs/compute/create-new-instances) | | `nscale_compute_cluster` | GPU clusters | [Clusters](/docs/compute/clusters) | More resources are planned for future releases. > [!WARNING] > > **`terraform destroy` deletes real infrastructure.** Always review the plan output before confirming a destroy operation. Resources deleted via Terraform are permanently removed just as if you deleted them in the console. ## Documentation Full documentation for the provider is available on the [Terraform Registry](https://registry.terraform.io/providers/nscaledev/nscale/latest/docs), and you can find [examples](https://github.com/nscaledev/terraform-provider-nscale/tree/main/examples) in the GitHub repository. *** ## Related Resources > **[Service Tokens](/docs/manage/service-tokens)** > > Generate the token used to authenticate the Terraform provider > **[API Reference](/api-reference/instances/list-instances)** > > The underlying API that the Terraform provider calls > **[Terraform Registry](https://registry.terraform.io/providers/nscaledev/nscale/latest/docs)** > > Full provider documentation and resource reference > **[GitHub Examples](https://github.com/nscaledev/terraform-provider-nscale/tree/main/examples)** > > Example Terraform configurations # Security groups Source: https://docs.nscale.com/docs/network/security-groups A security group is a set of stateful firewall rules that control inbound and outbound traffic to your resources. Security groups are tied to a VPC and can be reused across all resources in that VPC. You need at least one security group before creating an instance. By default, all traffic is denied — you must explicitly add rules to allow it. > [!NOTE] > > **Prerequisite:** You need an existing [VPC network](/docs/network/vpc-networks) before creating a security group. ## Summary This page explains how to create and manage **security groups** in the Nscale Console UI. Use this workflow if you: * Need to control which traffic can reach your instances and clusters * Want to define reusable firewall rules within a VPC * Are setting up networking before creating instances (a security group is required) ## Availability This feature is available for **On-demand** and **Reserved** cloud services. ## Requirements * A **VPC network** to associate the security group with * Permission and sufficient **quota** to create security groups > [!NOTE] > > **Default behaviour:** With no rules defined, all inbound and outbound traffic is **denied**. You must add rules to allow the traffic your workloads need. ## Key concepts * **Inbound rules** control traffic coming **into** your resources (e.g., SSH connections from your IP) * **Outbound rules** control traffic going **out** from your resources (e.g., internet access for package downloads) * **Stateful:** If you allow an inbound connection, the return traffic is automatically allowed (and vice versa) ### CIDR notation Security group rules use CIDR notation to specify IP ranges: > [!TIP] > > `0.0.0.0/0` = all IP addresses (open to the internet). `10.0.1.0/24` = a specific subnet (256 addresses). `203.0.113.50/32` = a single IP address. ### Protocol reference | Protocol | When to use | | - | - | | **TCP** | Most common — used for SSH (port 22), HTTP (80), HTTPS (443), and application traffic | | **UDP** | Used for DNS (port 53), some streaming/gaming protocols | | **Any** | Allows all protocols — use with caution | | **VRRP** | Virtual Router Redundancy Protocol — used for high-availability failover. Most users don't need this; use TCP/UDP/Any instead | ## Common rule examples | Use Case | Direction | Protocol | Port Range | Source/Destination CIDR | | - | - | - | - | - | | Allow SSH access | Inbound | TCP | 22 | `0.0.0.0/0` or your IP (`x.x.x.x/32`) | | Allow HTTP traffic | Inbound | TCP | 80 | `0.0.0.0/0` | | Allow HTTPS traffic | Inbound | TCP | 443 | `0.0.0.0/0` | | Allow all outbound | Outbound | Any | All | `0.0.0.0/0` | ## Security group lifecycle | Action | Details | | - | - | | **Create** | Provide a name, select a VPC, add an optional description, and define rules | | **Edit rules** | Add, modify, or remove individual rules at any time | | **Delete** | Remove the security group when it is no longer needed | > [!WARNING] > > You **cannot delete a security group** that is currently attached to active resources (instances, clusters). Detach or delete the associated resources first. ## Step-by-step ### Create a security group 1. In the Console, open your project, then go to **Network → Security Groups** 2. Click the **+ New** button in the top-right corner 3. A side panel opens with the creation form: * **Name**: Enter a name for the security group * **VPC**: Select the VPC this security group will belong to * **Description** (optional): Add a description (up to 200 characters) 4. Click **Add Rules** to define your firewall rules: * Choose **Inbound** or **Outbound** * Select the **Protocol** (TCP, UDP, Any, or VRRP) * Enter the **Port Range** (e.g., `22` for SSH, `80` for HTTP, or `1-65535` for all ports) * Enter the **CIDR** block (e.g., `0.0.0.0/0` for all IPs) * Add as many rules as needed 5. Click **Create** to save the security group ### View security group details Click any security group in the list to view its detail page. The detail page has three tabs: * **Overview** — summary of rules, linked instances, and configuration details (VPC, region, project) * **Rules** — full table of inbound and outbound rules with add/edit side panels * **Instances** — all instances using this security group, with search filtering ### Managing security groups To **edit** a security group: 1. Go to **Network → Security Groups** and select the security group 2. Click **Edit Group** from the header actions menu. A side panel opens with the editable fields. 3. Make your changes and save To **edit rules** on an existing security group: 1. Go to **Network → Security Groups** and select the security group 2. Open the **Rules** tab 3. Add, modify, or remove rules as needed 4. Save your changes To **delete** a security group: 1. Ensure no resources are attached to it (check the **Instances** tab) 2. Use the actions menu from the list page or detail page header ## Common issues / troubleshooting * **Symptom:** Can't delete a security group. **Likely cause:** The security group is attached to one or more active resources (instances, clusters). **Fix:** Remove or delete the associated resources, then try deleting the security group again. * **Symptom:** Instance is unreachable via SSH. **Likely cause:** No inbound rule for SSH (TCP port 22) in the instance's security group. **Fix:** Go to **Network → Security Groups**, select the security group attached to the instance, and add an inbound rule for TCP port 22 from your IP or `0.0.0.0/0`. * **Symptom:** Instance can't download packages or reach the internet. **Likely cause:** No outbound rules defined. By default, all outbound traffic is denied. **Fix:** Add an outbound rule allowing the required protocols and ports (or allow all outbound with protocol **Any** to `0.0.0.0/0`). *** ## Related resources > **[VPC Networks](/docs/network/vpc-networks)** > > Create the VPC your security group belongs to > **[Instances](/docs/compute/create-new-instances)** > > Attach security groups when creating instances > **[Terraform Provider](/docs/manage/terraform)** > > Manage security groups as infrastructure as code > **[API Reference](/api-reference/security-groups/list-security-groups)** > > Manage security groups programmatically via the Networking and Storage API # VPC Networks Source: https://docs.nscale.com/docs/network/vpc-networks A Virtual Private Cloud (VPC) is an isolated network boundary for your resources. Instances, clusters, and filesystems inside a VPC can communicate with each other but are isolated from resources in other VPCs. You need at least one VPC before you can create instances. VPCs are project-scoped and region-bound. > [!NOTE] > > **Prerequisite:** You need an existing project before creating a VPC. ## Summary This page explains how to create and manage **Virtual Private Cloud (VPC) networks** in the **nscale Console UI**. Use this workflow if you: * Need a private network boundary for workloads in a **specific project** * Want to prepare networking before creating instances (you need at least one VPC to create instances) The Console guides you through VPC creation in a short, three-step flow — **Details**, **Network Configuration**, and **Add Routes** — so you can size the network and (optionally) tune its IP allocation before any machines are provisioned. ## Availability This feature is available for **On-demand** and **Reserved** cloud services. ## Requirements * A **project** where the VPC will be created (VPCs are project-scoped; you can create multiple VPCs per project) * Permission and sufficient **quota** to create a VPC > [!NOTE] > > VPCs are project-scoped — you can create and use multiple VPCs within the same project. > [!WARNING] > > Your VPC's workload subnet must have at least a **/24 CIDR block** (256 IP addresses). This is the minimum for any network. ## VPC Lifecycle | Action | Details | | - | - | | **Create** | Walk through the three-step flow: enter the **details** (name, project, region, nameservers), define the **network configuration** (address, mask, and optional advanced IP reservations), and optionally **add routes**. | | **Edit** | Update the **name**, **nameservers**, and **routes** at any time after creation. Note: nameserver changes propagate via DHCP and may take up to 24 hours to apply on machines. Reboot the instance or run `dhclient` to force an immediate refresh. | | **Delete** | Remove a VPC that is no longer needed. | > [!WARNING] > > You **cannot change** the region or the IP address range of a VPC after creation. The IP allocation is permanent — to change it you would need to delete the VPC and reprovision every machine in it. Plan these values carefully. ## Step-by-step ### Create a new VPC 1. In the Console, open your project, then open **Network** in the project sidebar. 2. Select **VPCs**. 3. Click **Create VPC**. ![VPC list with the Create VPC button](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-list.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=cd210d8372f9f416c5ced0bcf58bca4e) #### Step 1 — Details 4. Fill in the VPC details: * **Name**: Enter a name for your network. It can only contain lowercase alphanumeric characters and dashes (e.g. `ml-platform-vpc`). * **Project**: Choose the project where the VPC should exist. * **Region**: Select the region for the VPC. * **Nameservers**: Optionally add one or more DNS server IPs. > [!TIP] > > If you leave **Nameservers** blank, Nscale-provided DNS defaults are used. > [!WARNING] > > Adding an explicit DNS server **bypasses internal hostname resolution** — instances in the VPC will not be able to resolve each other by hostname. Use with caution. ![VPC creation — Details step](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-create-details.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=b23cfce1a34e27bb982851141d2d37ea) 5. Click **Next: Network Configuration**. #### Step 2 — Network Configuration 6. Define the VPC's address range: * **Network Address**: The base network address (e.g. `10.0.0.0`). This must be the network base address — the host bits below the mask must be zero. * **Network Mask**: The prefix length, from `/8` to `/24`. This sets the total number of IP addresses available in the network. > [!TIP] > > **Sizing examples:** `/16` gives you 65,536 addresses (a large VPC), while `/24` gives you 256. Choose a `/16` or `/20` if you expect to scale. > [!NOTE] > > This IP allocation is permanent. To change it, you'd need to delete this VPC and reprovision all your machines. ![VPC creation — Network Configuration step](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-create-network-config.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=7198bf45bc6ef9774ae2ddca0c2f0b50) 7. (Optional) Turn on **Advanced Configuration** to control how the network's IP space is divided. See [Advanced Configuration (IP reservations)](#advanced-configuration-ip-reservations) below. 8. Click **Next: Add Routes**. #### Step 3 — Add Routes 9. (Optional) Add static routes for the VPC: * **Prefix**: The destination CIDR block (e.g. `192.168.0.0/24`). * **Next hop**: The IP address traffic for that prefix should be forwarded to. * Click **Add Route** to add it to the list. Repeat for additional routes. > [!TIP] > > Routes are optional — you can add or change them later by editing the VPC. ![VPC creation — Add Routes step](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-create-routes.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=756cb16a558c3072385057e07dcddfcd) 10. Click **Create VPC**. 11. Verify the result — the new VPC appears in the **VPC list** for the selected project and begins provisioning. ![VPC list showing the new VPC](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-dashboard.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=cb2ca98b8e27fb3eb9c65f6e2f6ab345) ## Advanced Configuration (IP reservations) By default, nscale automatically divides your VPC's IP space between the addresses handed to your machines (the **DHCP pool**) and a block reserved for **Nscale services** and **network services** (gateway, DNS, and metadata). Most VPCs never need to change this. **Advanced Configuration** lets you tune that split. On the **Network Configuration** step, toggle **Advanced Configuration** on to reveal two controls and a live allocation preview: * **Define your reservation block**: The block of IPs set aside for Nscale services and network services — these are unavailable for DHCP. * **Define network services**: Your portion within the reservation block for gateway, DNS, and metadata. The remainder of the reservation block goes to Nscale services. The selections always nest as **network ⊇ reservation block ⊇ network services**, and the **Network Allocation** summary updates live to show how many IPs go to **Network Services**, **Nscale Services**, and the **DHCP** pool. ![VPC creation — Advanced Configuration with IP reservations](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/vpc-create-advanced-config.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=5f1da5decb2761c007f98a5b6dfe8379) > [!NOTE] > > Advanced Configuration is optional. If you leave it off, nscale applies a sensible default reservation and the rest of your network is available to the DHCP pool. ## Quotas To check your current network quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows your provisioned and total limits for networks alongside GPU, servers, clusters, and filesystem quotas. ## Common Issues / Troubleshooting * **Symptom:** You can't find a VPC you expect to see in the Console. **Likely cause:** The Console is currently scoped to a different **project**. VPC networks are **project-scoped**, so you'll only see VPCs created in the selected project. **Fix:** In the Console, switch to the correct **project**, then return to **Network → VPCs** and check the list again. * **Symptom:** Your DNS server IPs changed after the VPC was created. **Likely cause:** DNS servers can change over time (for example, if your upstream DNS changes), and the VPC still has the older nameservers configured. **Fix:** Go to **Network → VPCs**, select the VPC, and update the **Nameservers**. You can return later at any time to edit them. * **Symptom:** The **Region** list is missing the region you expect. **Likely cause:** VPCs can only be created in regions that support them, so other region types are filtered out of the picker. **Fix:** Choose one of the regions shown. If the region you need is missing entirely, contact support to confirm availability. *** ## Related Resources > **[Instances](/docs/compute/create-new-instances)** > > Create compute instances inside your VPC > **[Security Groups](/docs/network/security-groups)** > > Control traffic rules for resources in your VPC > **[Filesystem](/docs/storage/file-storage)** > > Attach shared persistent storage within your VPC > **[API Reference](/api-reference/networks/list-networks)** > > Manage VPCs programmatically via the Networking and Storage API # Environments Source: https://docs.nscale.com/docs/platform-services/environments Reuse your GPUs across multiple environments, such as dev, staging, and prod, and deploy AI models into each one. **Reuse your GPUs across multiple environments.** You reserve GPU capacity once, as an environment cluster. Several environments, such as `dev` and `staging`, can then share that capacity. You deploy AI models into each environment, and each deployment has an OpenAI-compatible endpoint. > [!NOTE] > > **Beta:** Environments is in beta for **private cloud** organizations. To join the waitlist, contact [support](mailto:helpdesk@nscale.com). ## What you get * **Shared GPUs.** Several environments can use the same cluster. * **Network isolation.** Each environment has its own network rules. By default, environments can't reach each other over the network. Environments on the same cluster share its GPUs, so their compute isn't isolated. To give an environment its own GPUs, put it on its own cluster. * **Model deployment from the console.** Select a model, an environment, and a profile. The console creates an OpenAI-compatible endpoint. * **Managed setup.** Nscale installs the GPU drivers, the model runtime, and the public gateway. ## The three parts There are three things to know. You create them in this order. | Part | What it is | | - | - | | **Environment cluster** | GPU capacity you reserve in one region. Nscale manages it. | | **Environment** | A named, network-isolated space that runs on a cluster. For example, `dev` or `prod`. | | **Deployment** | Something you run inside an environment, such as a model with its own endpoint. | **How they connect:** * One cluster can hold **many** environments. * One environment can hold **many** deployments. * A deployment always lives in **one** environment. * Deploying a model from the console sets up two things in the environment: the model, which serves the endpoint, and a secret that stores its access key. The console lists them together as one deployment. ## Before you start Check that you have: * A [project](/docs/manage/projects) * A [VPC](/docs/network/vpc-networks) in the region you want * Enough **GPU quota** for the cluster you want, or a [reservation](/docs/compute/reservations) with available hosts if you plan to use bare-metal node types * The right **permissions**. Creating clusters needs an organization-level role. Ask your organization owner if a button is missing. The console hides buttons you can't use. ## Get started In the console, open your project and go to **Platform Services → Environments**. The page has two tabs: * **Overview**: your environments * **Environment Clusters**: the clusters your environments run on When you open it for the first time, a **Get started with Environments** checklist walks you through three steps: 1. [Create an environment cluster](#create-an-environment-cluster). Provisioning takes up to 90 minutes. 2. [Create an environment](#create-an-environment) on the cluster. 3. [Deploy a model](/docs/dedicated-models/deploy-a-model) into the environment, from **AI Services → Models**. ![The Get started with Environments checklist, with three steps: Create Environment Cluster, Create Environment, and Deploy a Model.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/get-started-checklist.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=155d390ae06849c5165c95becc00dcd1) The Get started checklist ## Environment clusters An **environment cluster** is a set of GPU nodes in one region, dedicated to your workloads. Nscale places the nodes to optimize the network topology between them. Your environments and models run on it. Nscale runs the cluster as a managed inference service. Nscale provisions, operates, and updates the nodes, the network, the GPU drivers, and the gateway that serves your model endpoints. ### What a cluster does * **Runs your environments.** Every environment runs on a cluster. One cluster can run many environments. * **Dedicated.** No other customer runs on it. * **Your choice of hardware.** You pick the VPC, which sets the region, and the node types. ### Cluster terms | Word | Meaning | | - | - | | **Regional VPC** | The [VPC](/docs/network/vpc-networks) the cluster runs in. The VPC sets the cluster's region, and the region decides which node types you can pick. **You can't change it later.** | | **Node type** | The kind of node. For example, how many GPUs, how much VRAM, CPU, and RAM. | | **Node pool** | A group of identical nodes with one node type. A cluster has one or more pools. | | **Reservation** | Bare-metal (**BM**) capacity reserved for your organization. A pool with a BM node type takes its hosts from a [reservation](/docs/compute/reservations). | ### Create an environment cluster > [!NOTE] > > You need an **organization-level** role to create clusters. If you can't see the button, ask your organization owner. **1. Open the Environment Clusters tab** Go to **Platform Services → Environments** and open the **Environment Clusters** tab. Click **Create Environment Cluster**. If you already have clusters, click **+ Add Cluster** above the table. ![Environment Clusters tab with the Create Environment Cluster button.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-create-entry.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=4ac42857b0b769db99fcb2f816ac9189) **2. Name the cluster** Under **Environment Cluster Details**, enter a **Name**. Name rules: * 3 to 49 characters * Lowercase letters, numbers, and dashes only * Start and end with a letter or number * Can't contain `nscale` * Must be unique in the project ![The Environment Cluster Details step with the Name field.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-create-name.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=5774035539ea23eb2323a4243586e766) **3. Select a Regional VPC** Under **Select Regional VPC**, pick a VPC from **Choose your Regional VPC**. Each VPC shows its region. To create a VPC, click **+ Add new VPC**. > [!WARNING] > > **You can't change the VPC later.** The VPC sets the cluster's region, and the region decides which node types you can use. ![The Select Regional VPC step with the VPC dropdown and the Add new VPC button.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-create-vpc.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=849f5994b4065b8831220dd35e6e4cc2) **4. Add node pools** Under **Add Node Pools**, set up at least one pool: * **Pool Name**: same rules as the cluster name. Must be unique in the cluster. * **Node Type**: pick a node type from the table. Check the **GPUs** and **VRAM** columns. The **Type** column shows **VM** or **BM** (bare metal). The remaining fields depend on the node type: * **VM node type**: under **Configure your Pool**, set the **Number of Replicas**. * **BM node type**: the field label changes to **Placement Pool Name**. Under **Set up your reservation**, select the reservation to take hosts from. Under **Configure your placement**, set the **Host Count**. The maximum is the number of hosts available in the reservation. The pool uses the cluster's VPC. To add more pools, click **+ Add Another Pool**. > [!TIP] > > Pick the node type with care. **You can't change it after the cluster is created.** Choose hardware that fits the models you plan to run. ![The Add Node Pools step with a B200 NVLink node type selected, a reservation selected, and the Host Count counter.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-create-node-pools.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=efb1df6622d3fd6da0f40c772b0ed153) **5. Review and create** Under **Review Environment Cluster**, check the cluster, VPC, and node pool summary. If the pools go over your GPU quota, the review shows a message and you can't create the cluster. Remove a pool or lower its node or host count. Click **Create Environment Cluster**. ![The Review Environment Cluster step with the cluster, VPC, and node pool summary.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-create-review.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=588ef0db6a7f636cc844483277f0d8e5) **What happens next:** The console takes you back to the **Environment Clusters** tab. Your cluster shows **Provisioning**. > [!NOTE] > > **Provisioning can take up to 90 minutes.** You can leave the page. When the status shows **Ready**, you can [create an environment](#create-an-environment) on it. ### Cluster status | Status | What it means | What to do | | - | - | - | | **Provisioning** | Nscale is building the cluster | Wait. This can take up to 90 minutes | | **Ready** | The cluster is ready to use | Create an environment | | **Updating** | A change is being applied | Wait | | **Deleting** | The cluster is being removed | Wait | | **Error** | The cluster couldn't be built | Delete it and create a new one. There is no retry | The **Health** column shows if a ready cluster is working well: **Healthy**, **Degraded**, **Unhealthy**, or **Unknown**. ### View a cluster Click a cluster in the list to open it. You'll see three tabs: * **Overview**: node pools, assigned environments, status, health, cluster ID, and region * **Node Pools**: each pool, its node type, and node count * **Assigned Environments**: environments that run on this cluster ![The environment cluster detail page showing the Overview tab.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/cluster-detail.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=4408e12646a769c125ebac2ce9e8f044) > [!NOTE] > > You can't edit a cluster or add pools after it is created. To change the hardware, create a new cluster. ### Cancel a cluster that is still provisioning If you made a mistake, you can stop it. 1. In the cluster list, click **⋯** on the cluster. 2. Click **Cancel Current Request**. 3. Click **Cancel request** to confirm. Any work done so far is lost. If you try again, it starts from the beginning. ### Delete an environment cluster > [!WARNING] > > **Deleting a cluster is permanent.** Environments that use it lose their capacity. Any model running on it stops. **1. Delete the environments first** Delete every environment listed under **Assigned Environments**. See [Delete an environment](#delete-an-environment). **2. Delete the cluster** In the cluster list, click **⋯** on the cluster, then click **Delete Environment Cluster**. **3. Confirm** Type the cluster name and confirm. The status changes to **Deleting**. The cluster disappears from the list when it is done. You can't delete a cluster while a request is still running. Wait for it to finish, or cancel it first. ## Environments An **environment** is a named, network-isolated space on an environment cluster. You deploy models into it. For example, you can have `dev`, `staging`, and `prod` environments on the same cluster. ### What an environment does * **Network isolation.** By default, a model in `dev` can't reach a model in `prod` over the network. * **Grouped deletion.** Deleting an environment also deletes every deployment in it. ### Create an environment You need an [environment cluster](#environment-clusters) with the status **Ready**. **1. Open Environments** Go to **Platform Services → Environments**. Click **+ Create Environment**. ![The Environments page with the Create Environment button.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/environment-create-entry.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=157186e304f56b8b046075b379edd53a) **2. Name the environment** Under **Environment Details**, enter a **Name**. For example, `dev` or `prod`. Name rules: * Up to 62 characters * Lowercase letters, numbers, and dashes only * Start and end with a letter or number * Must be unique in the project > [!TIP] > > Use a name that shows the purpose, like `dev`, `test`, or `prod`. **You can't rename it later.** **3. Select a cluster** Under **Select cluster**, pick the environment cluster to run on. The table shows each cluster's **GPU Type**, **GPUs**, **Region**, **Status**, and **Health**. Pick one that is **Ready** and has the GPUs your models need. ![The Create Environment form with the Name field and the cluster table.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/environment-create-form.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=84c8f966e4484b1289322a1cb6a85a5b) **4. Review and create** Check the **Review your Environment** card. Click **Create Environment**. **What happens next:** The console takes you back to the Environments list. Your environment shows **Creating**. When it shows **Ready**, you can [deploy a model](/docs/dedicated-models/deploy-a-model) into it. ### Environment status | Status | What it means | What to do | | - | - | - | | **Creating** | Nscale is setting it up | Wait | | **Ready** | Ready for models | Deploy a model | | **Updating** | A change is being applied | Wait | | **Deleting** | It is being removed | Wait | | **Error** | Something went wrong | Delete it and try again. Contact [support](mailto:helpdesk@nscale.com) if it keeps failing | > [!NOTE] > > You can only deploy models into a **Ready** environment. ### View an environment Click an environment in the list to open it. You'll see three tabs: * **Overview**: its status, cluster, and latest deployments * **Clusters**: the environment clusters it runs on * **Deployments**: every deployment in it, with its service, model, profile, and status ![The environment detail page showing the Overview tab.](https://mintcdn.com/nscale/0Xteqf06Y_m8g2R8/images/environments/environment-detail.png?fit=max\&auto=format\&n=0Xteqf06Y_m8g2R8\&q=85\&s=ad0973e13123629b62164d76d93b21d3) To deploy a model from here, click **⋯** and choose **Deploy Model**. ### Delete an environment > [!WARNING] > > **Deleting an environment is permanent.** Every model deployed into it is removed. Their endpoints stop working. **1. Open the menu** In the Environments list, click **⋯** on the environment. Click **Delete Environment**. You can only delete an environment when it is **Ready** or **Error**. **2. Confirm** Type the environment name and click **Delete**. The status changes to **Deleting**. The environment disappears from the list when it is done. ## Next steps > **[Deploy a model](/docs/dedicated-models/deploy-a-model)** > > Run a model in your environment and call its OpenAI-compatible endpoint. # Managed Kubernetes Source: https://docs.nscale.com/docs/platform-services/managed-kubernetes Create and run single-tenant Kubernetes clusters on on-demand or reserved GPU capacity with Nscale Kubernetes Service (NKS). Nscale Kubernetes Service (NKS) runs Kubernetes clusters for you. Nscale operates the parts that keep a cluster running, and you get a private cluster to deploy your workloads on with standard tools like `kubectl` and `helm`. Your workloads run on on-demand machines or on bare-metal GPU capacity you've [reserved](/docs/compute/reservations). > [!NOTE] > > **Before you start, you need:** > > * A [project](/docs/manage/projects) and a [VPC network](/docs/network/vpc-networks) in the region you want the cluster in. > * A **provisioned** [reservation](/docs/compute/reservations) with free hosts, if you want NVIDIA bare-metal machines. > * The right [permissions](#permissions) for NKS. > * The [Nscale CLI](/docs/cli/overview) **v5.0.0 or later**, logged in with `nscale login`, and [kubectl](https://kubernetes.io/docs/tasks/tools/) installed on your computer. ## Summary Getting a cluster running takes four steps: 1. [Create the cluster](#create-a-cluster) in the console. You pick a network, a Kubernetes version, and the machines to run on. 2. Wait for its status to change from **Provisioning** to **Provisioned**. 3. Run the command on the cluster's **Access your cluster** card to [connect `kubectl`](#access-your-cluster). 4. Run `kubectl get nodes` to check the connection, then deploy your workloads. The rest of this page covers each step in detail, how to manage the cluster afterwards, and [advanced configuration](#advanced-configuration) such as your own sign-in provider. ## Availability Managed Kubernetes is available to **reserved cloud** organizations and is enabled per organization. If you don't see **Kubernetes** under **Services** in the console sidebar, contact your Nscale account team. ## Key concepts | Term | What it means | | - | - | | **Cluster** | Your Kubernetes environment. It belongs to one project. | | **Control plane** | The Kubernetes components that run the cluster itself, such as the API server that `kubectl` talks to. Nscale runs these for you. See [How NKS runs your cluster](#how-nks-runs-your-cluster). | | **Node** | One machine that runs your workloads. | | **Node pool** | A group of identical nodes. A cluster needs at least one. A pool is either a compute pool or a [reservation pool](/docs/compute/reservations) (see below). | | **Node type** | The kind of machine every node in a pool uses. You pick it when you create the pool and can't change it later. | | **Regional VPC** | The [network](/docs/network/vpc-networks) the cluster joins. It decides the cluster's region, and you can't change it after the cluster is created. | | **NKS version** | The Kubernetes version plus the add-ons NKS installs, released together. The console also calls it the **platform release** or **release**. | | **kubeconfig** | The file `kubectl` reads to find a cluster and sign in to it. | ### Compute pools and reservation pools The node type you pick decides which kind of pool you get: | | Compute pool | Reservation pool | | - | - | - | | **Node types** | Virtual machines, and bare-metal machines that aren't NVIDIA | NVIDIA bare-metal machines, which are only sold as reserved capacity | | **Where the machines come from** | Created on demand | Taken from one of your [reservations](/docs/compute/reservations). NKS creates a [placement](/docs/compute/placements) in it for the pool. | | **How you size it** | **Number of Replicas** | **Host Count**, plus a **Pack** or **Spread** placement policy | | **Resize later?** | Yes | No. Add a new pool instead. | | **Uses GPU quota?** | Yes, for GPU node types | No, the capacity is already reserved | | **Icon in the console** | Stacked layers | Bookmark | In a [reservation pool](/docs/compute/reservations), each host becomes one node. For GB300 NVL72, one host is one compute tray. The console labels a reservation pool's name field **Placement Pool Name**. ## Create a cluster In your [project](/docs/manage/projects), go to **Services → Kubernetes** and click **Create Cluster**. The create flow has four steps. Steps 2 to 4 unlock once you've named the cluster and picked a [VPC](/docs/network/vpc-networks). ![Kubernetes clusters list](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/clusters-list.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=294bed49d97c35e20f95c44e7436603b) **1. Set up your cluster** * **Name**: 3–50 lowercase letters, digits, and dashes. It must start with a letter or digit, can't end with a dash, and can't contain `nscale`. You can't rename a cluster later. * **Choose your Regional VPC**: the network the cluster joins, which also sets its region. You can't change it later. To create a [VPC](/docs/network/vpc-networks) without leaving the create flow, click **Add new VPC**. If you come back and change the VPC, any node types you've picked are cleared, because each region offers different machines. > [!NOTE] > > Node labels and initial taints can't be set in the console. Use the API or the [Nscale CLI](/docs/cli/kubernetes#nodepool-create) instead. **2. Configure Kubernetes** | Setting | Default | What it does | Change later? | | - | - | - | - | | **NKS Version** | Newest available | The Kubernetes version and add-ons the cluster runs. Only current versions offered in the VPC's region are listed. | [Upgrade only](#upgrade-a-cluster) | | **Hardware Profile** | On | Installs the drivers and plugins GPUs and the HPC network need. If you turn it off, you install and manage them yourself. | Yes, in **Settings** | | **Node Health Monitoring** | On | Detects and reports problems with your nodes. | Yes, in **Settings** | | **Public API Endpoint** | Off | Makes the cluster's API reachable from the internet. Sign-in is still required. When it's off, you can only reach the API from inside the cluster's VPC. | Yes, with [Manage Access](#manage-api-access) | | **Allowed Address Ranges** | Empty | Only shown when the public endpoint is on. Limits which IPv4 ranges can reach the API, for example `10.0.0.0/8`. Leave it empty to allow any address. | Yes, with [Manage Access](#manage-api-access) | Nscale manages the control plane over its own network, so it never needs the public endpoint. ![Configure Kubernetes step](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/create-cluster-step-2-configure.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=40dbd864054917a623571c72f58e4f7a) **3. Add node pools** Name the pool and pick a node type from the table. The pool name must be unique in the cluster and follow the same rules as the cluster name. A node type is grayed out if the selected NKS version doesn't support it. The rest of the step depends on the node type you picked: **Compute pool** Under **Configure your Pool**, set **Number of Replicas**: how many nodes the pool runs. ![Add a compute node pool](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/create-cluster-step-3-compute-pool.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=ffb7314c2f38681fb8463b0e9934ac72) **Reservation pool** 1. Under **Set up your reservation**, pick a reservation in **Select reservation for this node pool**. Only provisioned reservations for the chosen node type are listed. 2. Under **Configure your placement**, set **Host Count**: how many of the [reservation](/docs/compute/reservations)'s hosts the pool uses. The limit is the reservation's free hosts, minus any that other pools in this cluster already use. 3. Pick a **Placement Policy**. **Pack** keeps hosts close together for fast communication. **Spread** spreads them out so one failure affects fewer of them. See [Placement policy](/docs/compute/placements#placement-policy). The **Network** row shows the cluster's [VPC](/docs/network/vpc-networks), which the pool uses too. **Change VPC** takes you back to step 1, and changing the VPC clears the node types you've picked. ![Add a reservation node pool](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/create-cluster-step-3-reservation-pool.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=da2b6267e59942ca27cfddf64cf24f06) To add more pools, click **Add Another Pool** once the current one is complete. Only one pool is open at a time: **Collapse** folds it into a summary row, and **Remove** deletes it. A pool you haven't changed from its defaults is ignored. **4. Review your cluster** Check the [VPC](/docs/network/vpc-networks) and each node pool, then click **Create Cluster**. If your compute pools use GPUs, the review shows how much of your [GPU quota](#quotas) they need. The console creates the cluster, then each node pool, and opens the cluster's page. Its status changes from **Provisioning** to **Provisioned** when it's ready. > [!WARNING] > > **If a node pool fails, the cluster is still created.** A notification names the missing pools, for example "my-cluster was created with 1 of 2 node pools". Add them from the cluster's **Node Pools** tab. Don't run the create flow again, or you'll create a second cluster. ## Access your cluster When the cluster is ready, the **Access your cluster** card on its **Overview** tab shows a command that sets up `kubectl`. Until then, the card says the endpoint isn't published yet. **1. Add the cluster to your kubeconfig** Copy the command from the card. On its own, it prints the kubeconfig to your terminal. Add `--merge` to save it into the kubeconfig `kubectl` already uses (`$KUBECONFIG` or `~/.kube/config`) and switch to it: ```bash theme={null} nscale k8s kubeconfig get \ --org \ --cluster \ --merge ``` To save it as a separate file instead, use `--output` (`-o`): ```bash theme={null} nscale k8s kubeconfig get --org --cluster -o my-cluster.yaml export KUBECONFIG=$PWD/my-cluster.yaml ``` **2. Check the connection** ```bash theme={null} kubectl get nodes ``` You'll see the cluster's nodes and their Kubernetes version. Nodes appear as their pools finish provisioning. The kubeconfig contains no password or token. Each time `kubectl` needs one, it asks the Nscale CLI for a fresh token. So the file never goes stale, and sharing it doesn't give anyone access. > [!NOTE] > > **What you can do in the cluster depends on your `nks:kubernetes-api` permission.** **Read** gives you read-only access (the Kubernetes `view` role). **Update** gives you full admin access (`cluster-admin`). Without either, the command still runs but `kubectl` fails, and the card tells you so. > [!NOTE] > > The kubeconfig uses the public endpoint if the cluster has one, and the private one otherwise. To force the private endpoint, add `--endpoint private`. It only works from inside the cluster's VPC. ## View a cluster The **Kubernetes** page lists your project's clusters. Click one to open it. The cluster page has three tabs, **Overview**, **Node Pools**, and **Settings**, and an actions menu with **Copy ID**, **Copy as JSON**, and **Delete Cluster**. The list's **Version** column shows the Kubernetes version each cluster runs. ### Overview ![Cluster overview](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/cluster-overview.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=99e8247020bb04928fe2af7362fedfca) | Card | What it shows | | - | - | | **Access your cluster** | The command to connect `kubectl`. See [Access your cluster](#access-your-cluster). | | **Node Pools** | The first few pools and their status. **All Pools** opens the **Node Pools** tab. | | **Details** | Status, health, creation date, VPC, NKS version, and cluster ID. A **Withdrawn**, **Deprecated**, or **Upgrade Available** badge appears next to the version when it applies. | | **Configuration** | Region, number of pools and nodes, and total vCPUs. | | **Network** | The [VPC](/docs/network/vpc-networks)'s route count and the API's private IP address. **Manage Routes** opens the VPC's routes. | | **API Access** | Whether the API is private or public, its public IP address, and its allowed address ranges. | ### Manage API access To change who can reach the API, click **Manage Access** on the **API Access** card. Turn **Public API Endpoint** on or off, edit **Allowed Address Ranges**, and click **Save Changes**. Turning off the public endpoint also clears the ranges. ### Node Pools tab This tab lists every pool with its node type, how many nodes are ready out of the number requested (**Ready / Requested**), and its **Status** and **Health**. The icon shows whether it's a compute pool (stacked layers) or a reservation pool (bookmark). See [Manage node pools](#manage-node-pools). ![Node Pools tab](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/cluster-node-pools-tab.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=06295bf23a25444fd540f7d7710ab834) ### Settings tab * **Cluster info**: the cluster's name and project. Names can't be changed. * **Cluster configuration**: click **Edit** to [upgrade the NKS version](#upgrade-a-cluster) or turn **Hardware Profile** and **Node Health Monitoring** on or off, then click **Save Changes**. The VPC is shown but can't be changed. * **Delete**: see [Delete a cluster](#delete-a-cluster). ## Upgrade a cluster When a newer NKS version is available, the **Details** card shows **Upgrade Available**. **1. Open the cluster configuration** On the cluster's **Settings** tab, click **Edit** on the **Cluster configuration** card. **2. Choose a version** Pick a version from **Platform release**. Only the current version and the ones you can upgrade to are listed. **3. Save** Click **Save Changes** to start the upgrade. > [!WARNING] > > **Upgrades can't be undone.** You can't move a cluster back to an earlier version. ## Manage node pools ### Add a node pool On the **Node Pools** tab, click **Add Pool**. The page works like step 3 of the create flow: set up one or more pools under **Configure your node pools**, check them under **Review your node pools**, and click **Add Pools**. Each new pool needs a name the cluster doesn't already use, and runs the cluster's current NKS version. ### Edit a node pool You can only change the size of a compute pool. From its row menu, choose **Edit Pool**, change **Number of Replicas**, and click **Update Pool**. Its name and node type stay the same. A [reservation pool](/docs/compute/reservations) can't be changed after it's created: its host count, placement policy, taints, and labels are fixed. To change any of them, [add a new pool](#add-a-node-pool) and delete the old one. ![Edit Pool modal](https://mintcdn.com/nscale/tczTGAenQ13Z8C9Q/images/kubernetes/edit-node-pool-modal.png?fit=max\&auto=format\&n=tczTGAenQ13Z8C9Q\&q=85\&s=cf22e85d189538f901643c9ceef5add6) ### Delete a node pool From the pool's row menu, choose **Delete Pool** and type its name to confirm. Its nodes are drained and removed, and your workloads move to the cluster's other pools. > [!WARNING] > > If it's the cluster's **only** pool, your workloads have nowhere to move and stop running until you add another pool. ### View a node pool Click a pool to open it. The header shows its status and health, links to its cluster (and reservation, for a [reservation pool](/docs/compute/reservations)), and what each node provides. For a reservation pool, it also shows the placement policy and host count. * **Compute pool**: the **Nodes** table lists each node with its private IP and **Power Status**. Use **Stop** or **Start** in the row, or **Reboot Node** from the row menu. * **[Reservation pool](/docs/compute/reservations)**: the table lists the servers of the pool's [placement](/docs/compute/placements), once NKS has taken its hosts from the reservation. Use **Stop** in the row, or **Reboot Server** (hard reboot) or **Soft Reboot Server** from the row menu. A stopped server shows **Reboot** to turn it back on. > [!NOTE] > > You can't delete a single node or server. NKS manages them and would replace it. To make a compute pool smaller, [edit its size](#edit-a-node-pool). ## Delete a cluster **1. Open the delete action** Choose **Delete Cluster** from the cluster's row menu on the **Kubernetes** page, or from the actions menu or **Settings** tab on the cluster's page. **2. Confirm** Type the cluster's name to confirm. > [!WARNING] > > **Deleting a cluster is permanent.** Its node pools and everything running on them are destroyed. Save any data you need outside the cluster first. ## Cluster and node pool status The **Status** column shows where a cluster or node pool is in its lifecycle: | Status | Meaning | | - | - | | **Pending** | Accepted, waiting to start | | **Provisioning** | Being created | | **Provisioned** | Ready to use | | **Deprovisioning** | Being deleted | | **Error** | Something went wrong | Once it's **Provisioned**, the **Health** column shows how it's doing. Before that, the column is empty. | Health | Meaning | | - | - | | **Healthy** | Everything is working | | **Degraded** | Running, but some parts aren't ready | | **Error** | In an error state | | **Unknown** | Health can't be determined | ## Permissions The console hides anything your role can't do. These are the permissions (scopes) each task needs. To grant them, see [Roles and groups](/docs/manage/roles-and-groups). | To do this | You need | | - | - | | See clusters | `nks:clusters` read | | Create a cluster | `nks:clusters` create, `nks:nodepools` create, and `nks:platformreleases` read | | Change API access, upgrade, or turn add-ons on or off | `nks:clusters` update | | Delete a cluster | `nks:clusters` delete | | See node pools | `nks:nodepools` read | | Add a node pool | `nks:nodepools` create and read (read is needed to check the name isn't taken) | | Resize a compute pool | `nks:nodepools` update | | Delete a node pool | `nks:nodepools` delete | | Use the cluster with `kubectl`, read-only | `nks:kubernetes-api` read | | Use the cluster with `kubectl`, full admin | `nks:kubernetes-api` update | | Pick node types | `compute:flavors` read, granted organization-wide | | Set up a [reservation pool](/docs/compute/reservations) | `reservation:reservations`, `reservation:placements`, and `reservation:reservation-units` read. `reservation:reservation-units` must be granted organization-wide. | | Use the **Add Reservation** shortcut | `reservation:reservations` create | | See or power-cycle a compute pool's nodes | `compute:instances` read, and update to stop, start, or reboot | | See or power-cycle a [reservation pool](/docs/compute/reservations)'s servers | `reservation:placement-servers` read, and update to stop or reboot | ## Quotas Compute pools with GPU node types use your organization's GPU quota. [Reservation pools](/docs/compute/reservations) don't, because that capacity is already reserved. To check your quota, go to **Resource Usage** on the **Dashboard**. ## How NKS runs your cluster NKS runs each cluster's control plane on its own machines, separate from your node pools: the API server, the scheduler, the controllers, and etcd, the database that stores the cluster's state. Nscale sets them up, keeps them running, and replaces them when needed. * **Always available.** The control plane runs as three copies on separate machines, so the cluster keeps working if one fails. * **Careful maintenance.** When NKS replaces a machine, it starts the new one and waits for it to be healthy before removing the old one. * **Your workloads keep running.** If the control plane is briefly unavailable, you can't deploy or change things, but workloads already running on healthy nodes keep going. Applications that call the Kubernetes API all the time can still notice. * **Certificates.** Nscale renews the control plane's certificates without changing the cluster's certificate authority (CA), so your clients keep trusting the cluster. Replacing the cluster CA isn't supported. * **Secrets.** NKS doesn't encrypt Kubernetes Secrets at rest. ### Who manages what | Area | Nscale | You | | - | - | - | | Control plane | Setup, configuration, upgrades, replacing machines, and certificates | Choosing the NKS version, and keeping your applications compatible with it | | Access | The API endpoint and the sign-in methods you configure | Who can do what inside the cluster (Kubernetes RBAC), and any identity provider you add | | Monitoring | Watching the control plane, and giving you access to its metrics | Your own Prometheus, workload monitoring, and alerts | | Data | The control plane's own database | Backing up your application data, such as persistent volumes, datasets, and checkpoints | The three control plane copies keep the cluster available. They don't back up your data. ## Advanced configuration ### Use your own identity provider By default, you sign in to the cluster with your Nscale account. You can also let people sign in with your own OpenID Connect (OIDC) provider, and give them one of the built-in roles: `cluster-admin`, `admin`, `edit`, or `view`. Nscale never sees or stores their tokens. You can only set this up when you create the cluster, and only through the API or CLI, not the console. Add it to the cluster's `spec.apiServer` in the [create cluster](/api-reference/clusters/create-cluster) request (`POST https://nks.nks.europe-west4.nscale.com/api/v1/clusters`), or in the file you pass to `nscale k8s cluster create --file cluster.json`: ```json theme={null} "apiServer": { "authentication": { "externalIssuers": [ { "issuerURL": "https://idp.example.com", "audiences": ["acme-tenant-api"], "usernameClaim": "sub", "usernamePrefix": "acme:", "groupsClaim": "groups", "groupsPrefix": "acme:" } ] }, "authorization": { "clusterRoleBindings": [ { "clusterRole": "cluster-admin", "subjects": [{ "kind": "Group", "name": "acme:platform-admins" }] } ] } } ``` | Field | Rule | | - | - | | `issuerURL` | Your provider's `https://` URL, with no query string or fragment. It must match the `iss` claim in your tokens exactly. Up to 8 issuers. | | `audiences` | At least one. The token's `aud` claim must match one of them. | | `usernameClaim` | The token claim used as the username. Defaults to `sub`. | | `usernamePrefix` | Required. Added to every username so it can't clash with built-in Kubernetes names. It can't start with, or be a prefix of, `system:`, `kubeadm:`, `nks-management:`, `nks:`, or `nscale.com/`. | | `groupsClaim`, `groupsPrefix` | Optional, but set both or neither. The prefix follows the same rules. | | `caCertificate` | The PEM certificate that signed your provider's HTTPS certificate. Only needed if it isn't from a public CA. | | `clusterRoleBindings` | One entry per role. Each subject is a `User` or `Group`, written with your prefix, for example `acme:alice`. | Keep in mind: * **It can't be changed later.** To change the provider or role bindings, create a new cluster. Pick an issuer CA that will outlast the cluster. * **Add at least one role binding.** People only get the access you bind. Someone with a valid token but no binding is refused everything. * **Your provider affects the cluster.** The cluster fetches your provider's signing keys over HTTPS. Short outages are fine, because the keys are cached. A long outage, or a new key the cluster can't fetch, stops people signing in and can make the API report as not ready. To connect, users need a kubeconfig with the cluster's API endpoint and CA, and pass their token to `kubectl`, for example with `--token` or a credential plugin. ### Monitor the control plane You can scrape Prometheus metrics from each API server, controller manager, and scheduler through the `nks-control-plane-metrics` Service in `kube-system`. Metrics per copy help you tell a problem with one of them apart from load on the whole cluster. To set it up, run Prometheus as a Pod in the cluster, and let its ServiceAccount read the metrics by binding the built-in `nks-metrics-component-scraper` ClusterRole to it: ```yaml theme={null} apiVersion: rbac.authorization.k8s.io/v1 kind: ClusterRoleBinding metadata: name: prometheus-control-plane-metrics roleRef: apiGroup: rbac.authorization.k8s.io kind: ClusterRole name: nks-metrics-component-scraper subjects: - kind: ServiceAccount name: prometheus namespace: monitoring ``` * **Scrape from inside the cluster.** Only addresses in the cluster's subnet can reach the metrics, even over peered networks. * **Create your own binding.** Don't edit the existing `nks-metrics-component-scraper` binding. Nscale owns it and undoes changes. * **Ports.** `kube-apiserver` on 6443, `kube-controller-manager` on 10257, and `kube-scheduler` on 10259. Each copy has its own name: `.nks-control-plane-metrics.kube-system.svc.cluster.local`. * **Scrape by name, not by IP address.** A replacement machine can reuse an old IP address. Scraping by name shows a replacement as a gap, instead of silently mixing two machines' data. Keep only endpoints marked ready, and give new copies time to start before alerting. * **Adding up metrics.** Sum `kube-apiserver` counters across copies. Only one controller manager and one scheduler are active at a time, so take the maximum of their gauges, such as `scheduler_pending_pods`, instead of summing them. * **Not available.** etcd, node, and host metrics. ### Forward DNS zones to your resolvers Inside the cluster, CoreDNS answers DNS lookups for your Pods. To send lookups for your own zones, such as `corp.example.com`, to your own DNS servers, create a ConfigMap named `coredns-custom` in `kube-system`. Nscale never touches it. ```yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: coredns-custom namespace: kube-system data: corp.example.com.server: | corp.example.com:53 { errors cache 30 forward . 10.0.0.53 } ``` * **Key names must end in `.server`.** Other keys, such as the `.override` keys some providers use, are silently ignored. * **No restart needed.** Changes apply within about two minutes. * **Your nodes must reach your DNS servers** on port 53, over both UDP and TCP. * **Pods only.** This doesn't change DNS on the nodes themselves, or for Pods with `dnsPolicy: Default`. * **Leave the cluster's own zones alone.** Don't add blocks for `cluster.local`, `in-addr.arpa`, `ip6.arpa`, or the root zone (`.`). The first three break Service and reverse lookups. A root block stops CoreDNS from starting the next time a CoreDNS Pod restarts. * **Check the logs after each change.** If CoreDNS can't read your file, it keeps using the last working one. Look for `Corefile parse failed` in `kubectl logs -n kube-system -l k8s-app=kube-dns`, and fix it before a CoreDNS Pod restarts. ### Workload credentials Applications running in the cluster should use projected ServiceAccount tokens. Kubernetes renews them automatically, so your application needs to re-read the token file to pick up new ones. * **Tokens last up to 24 hours.** A request for longer is shortened to 24 hours without an error, so check the expiry you get back. Tokens from `kubectl create token` aren't renewed, so automation outside the cluster must request a new one before it expires. * **Legacy token Secrets are empty.** A `kubernetes.io/service-account-token` Secret is never filled in. Use the TokenRequest API or projected tokens instead. ## Troubleshooting > **The command on the Access your cluster card isn't there yet** > > The cluster is still being set up. The card says the endpoint will be published when the control plane finishes provisioning. Wait a few minutes; the command appears as soon as it's ready. > **The NKS Version picker says NKS isn't available in the VPC's region** > > No NKS version is offered in that VPC's region yet. Choose a [VPC](/docs/network/vpc-networks) in another region, or [contact support](/docs/help/contact-support). > **The create flow says NKS versions or node types aren't visible to your role** > > Your role is missing `nks:platformreleases` read, or organization-wide `compute:flavors` read. Ask an organization owner to add the missing [permission](#permissions). > **A node type is grayed out** > > The selected NKS version doesn't support that machine's CPU architecture. Choose another node type, or go back to **Configure Kubernetes** and pick a different NKS version. > **There's no reservation or free capacity for a reservation pool** > > You see **Reservation required**, **No host capacity available**, or a message that your pools ask for more hosts than the reservation has. Either there's no provisioned reservation for that node type, its hosts are already in use, or several pools in the cluster together ask for too many. > > Add or expand a [reservation](/docs/compute/reservations), delete a [placement](/docs/compute/placements) to free up hosts, or lower a pool's **Host Count**. > **The create flow says reservations aren't visible to your role** > > Your role can't read reservations, placements, or reservation units. Ask an organization owner to add the [reservation permissions](#permissions), or pick an on-demand node type. > **kubectl fails even though the kubeconfig command worked** > > Your role is missing `nks:kubernetes-api` access. Ask an organization owner to grant it: **read** for read-only access, or **update** for full admin. > **kubectl times out connecting to the cluster** > > Either the cluster has no public endpoint and you're outside its [VPC](/docs/network/vpc-networks), or your IP address isn't in **Allowed Address Ranges**. Run `kubectl` from inside the VPC, or change the settings with [Manage Access](#manage-api-access). > **People can't sign in with your identity provider** > > * **`401 Unauthorized`**: the token was rejected. Check that `issuerURL` and `audiences` match the token's `iss` and `aud` claims, that the token hasn't expired, and that the cluster can reach your provider. > * **`Forbidden` for everything**: the token is fine, but no role binding covers the user or their groups. Check that the binding includes your prefix, for example `acme:alice`. *** ## Related resources > **[Reservations](/docs/compute/reservations)** > > Reserve bare-metal GPU capacity for reservation pools > **[Placements](/docs/compute/placements)** > > Learn how Pack and Spread place hosts > **[VPC networks](/docs/network/vpc-networks)** > > Create the regional VPC a cluster attaches to > **[File storage on NKS](/docs/platform-services/nks-file-storage)** > > Give pods shared, persistent storage with PersistentVolumeClaims > **[Nscale CLI](/docs/cli/kubernetes)** > > Manage clusters, node pools, and kubeconfigs from the command line > **[Kubernetes API reference](/api-reference/clusters/create-cluster)** > > Manage clusters, node pools, and NKS versions through the API # File storage on NKS Source: https://docs.nscale.com/docs/platform-services/nks-file-storage Give pods on an Nscale Kubernetes Service (NKS) cluster shared, persistent, POSIX filesystem storage with Nscale file storage and PersistentVolumeClaims. This guide is for teams running workloads on an [Nscale Kubernetes Service (NKS)](/docs/platform-services/managed-kubernetes) cluster who want shared, persistent, POSIX filesystem storage for their pods. The storage is Nscale [file storage](/docs/storage/file-storage), shown as **Filesystem** in the console. The Nscale File Storage CSI Driver and a high-performance NFS client on the nodes are already installed and maintained for you, so there is nothing to deploy. You create one Kubernetes `StorageClass`, and from then on your teams request storage with ordinary `PersistentVolumeClaim` objects. > [!NOTE] > > **Before you start, you need:** > > * `kubectl` access to the cluster. See [Access your cluster](/docs/platform-services/managed-kubernetes#access-your-cluster), or run `nscale kubernetes kubeconfig get --merge`. > * File storage available to you. It's currently offered only in the reserved cloud environment, and the cluster's VPC needs at least a **/24** CIDR block. See [Filesystem availability](/docs/storage/file-storage#availability). > * The [Nscale CLI](/docs/cli/overview), logged in with `nscale login`, to look up the file storage class ID. The console doesn't show class IDs. ## What is already in your cluster | Component | Who provides it | What it does | | - | - | - | | Nscale File Storage CSI Driver (`filestorage.csi.nscale.com`) | NKS | Creates, expands, and deletes file storage for your PVCs, and mounts it in your pods | | NFS client on every node | NKS | Provides the high-performance NFS client used by the optional [attachment mount options](#attachment-mount-options-and-performance) | | `StorageClass` | **You** | Chooses which kind of file storage to create, and what happens when a PVC is deleted | ## Step 1: Find your file storage class ID A **file storage class** is an Nscale-side definition of the kind of storage to create: its performance characteristics and the storage features available in a region. Your Kubernetes `StorageClass` selects one by ID. A file storage class belongs to a region, and you must use one from the **region your NKS cluster was provisioned in**. Find that region first. The cluster listing shows it in the `Region` column, or you can read it from the cluster directly: ```bash theme={null} nscale kubernetes cluster list nscale kubernetes cluster get -q '.status.regionId' ``` Then list the file storage classes available in that region with [`nscale filestorage classes`](/docs/cli/filestorage#classes): ```bash theme={null} nscale filestorage classes --region ``` Copy the ID of the class you want. To extract just the IDs, or to inspect the full payload: ```bash theme={null} nscale filestorage classes --region -q '.[].metadata.id' nscale filestorage classes --region --json ``` > [!WARNING] > > A class from a different region can't be attached to your cluster's network, and PVCs using it never bind. ## Step 2: Create a StorageClass ```yaml storageclass.yaml theme={null} apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: nscale-filestorage provisioner: filestorage.csi.nscale.com parameters: filestorage.csi.nscale.com/storage-class-id: "" # Optional, recommended: use the NFS mount options Nscale publishes for the # network attachment. Requires the NFS client that NKS installs on its nodes. filestorage.csi.nscale.com/use-attachment-mount-options: "true" reclaimPolicy: Retain allowVolumeExpansion: true volumeBindingMode: Immediate ``` Apply and verify it: ```bash theme={null} kubectl apply -f storageclass.yaml kubectl get storageclass nscale-filestorage ``` ### Fields | Field | Value | Why | | - | - | - | | `provisioner` | `filestorage.csi.nscale.com` | The driver name. Must match exactly. | | `reclaimPolicy` | `Retain` | Keeps your data when a PVC is deleted. See [Delete a PVC](#delete-a-pvc-and-the-retain-reclaim-policy). | | `allowVolumeExpansion` | `true` | Lets users grow a PVC later. Growing is the only supported resize. | | `volumeBindingMode` | `Immediate` | File storage is reachable from every node on the cluster network, so there is no reason to delay binding until a pod is scheduled. | ### Parameters | Parameter | Default | Meaning | | - | - | - | | `filestorage.csi.nscale.com/storage-class-id` | *required* | The file storage class ID from [step 1](#step-1-find-your-file-storage-class-id). | | `filestorage.csi.nscale.com/use-attachment-mount-options` | `"false"` | When `"true"`, the NFS mount options Nscale publishes for the network attachment are applied at mount time. **Recommended.** | | `filestorage.csi.nscale.com/root-squash` | `"true"` | When `"true"`, the export maps remote root to an unprivileged user. Set to `"false"` only if your workloads must write as root. | Any other `filestorage.csi.nscale.com/*` parameter is rejected, and the PVC stays `Pending` with an `unsupported StorageClass parameter` error. ### Attachment mount options and performance `use-attachment-mount-options: "true"` is optional, but recommended. When it is enabled, the driver passes through the mount options that Nscale publishes for the specific network attachment backing your volume, including the multipath options that let a single mount use several storage endpoints in parallel. Without it, the volume still mounts and works correctly, but it mounts with plain kernel NFS defaults and loses that extra throughput. These options need the NFS client that NKS installs on its nodes, **so on NKS you can enable this safely.** On a self-managed cluster without it, the mount fails with `mount.nfs: an incorrect mount option was specified`. ### StorageClass mount options You can add `mountOptions` to the `StorageClass`, and they are passed to every NFS mount for volumes created from it: ```yaml theme={null} mountOptions: - nfsvers=4.1 ``` A `StorageClass` mount option **overrides** an attachment mount option with the same key. If you have enabled `use-attachment-mount-options`, leave `mountOptions` empty unless you have a specific reason to override it. That way the options Nscale publishes for your attachment apply exactly as intended. ## Step 3: Create a PersistentVolumeClaim ```yaml pvc.yaml theme={null} apiVersion: v1 kind: PersistentVolumeClaim metadata: name: shared-data namespace: my-app spec: accessModes: - ReadWriteMany storageClassName: nscale-filestorage resources: requests: storage: 100Gi ``` ```bash theme={null} kubectl -n my-app apply -f pvc.yaml kubectl -n my-app get pvc shared-data -w ``` The PVC becomes `Bound` once the driver has created the file storage and Nscale has attached it to your cluster's network. This normally takes well under a minute. File storage is sized in whole GiB, so a request is rounded **up** to the next GiB. Requesting `100Gi` gives you 100 GiB; requesting `500Mi` gives you 1 GiB. Supported access modes: | Access mode | Use it for | | - | - | | `ReadWriteMany` | The normal case. Many pods across many nodes read and write the same volume. | | `ReadWriteOnce` | A single-writer filesystem volume. | `ReadOnlyMany` and block volumes are not supported. Each PVC maps to exactly one file storage resource. To share data between pods, have them mount the same PVC with `ReadWriteMany`. ## Step 4: Mount the PVC in a pod ```yaml pod.yaml theme={null} apiVersion: v1 kind: Pod metadata: name: shared-data-writer namespace: my-app spec: containers: - name: writer image: busybox:1.36 command: - sh - -c - | echo "hello from ${HOSTNAME}" >> /data/hello.txt sleep 3600 volumeMounts: - name: shared mountPath: /data volumes: - name: shared persistentVolumeClaim: claimName: shared-data ``` ```bash theme={null} kubectl -n my-app apply -f pod.yaml kubectl -n my-app exec shared-data-writer -- sh -c 'df -h /data; cat /data/hello.txt' ``` Any number of pods, on any number of nodes, can mount the same `ReadWriteMany` PVC the same way. A `Deployment` or `StatefulSet` uses the identical `volumes` block. ## Grow a volume If the `StorageClass` sets `allowVolumeExpansion: true`, edit the PVC request: ```bash theme={null} kubectl -n my-app patch pvc shared-data \ --type merge \ -p '{"spec":{"resources":{"requests":{"storage":"200Gi"}}}}' kubectl -n my-app get pvc shared-data -w ``` Expansion is **grow-only** and happens online: the mounted pods keep running and see the new size without a restart. Shrink requests are rejected. ## Delete a PVC and the `Retain` reclaim policy The reclaim policy decides what happens to your data when someone deletes a PVC. | | `Retain` (recommended) | `Delete` | | - | - | - | | PVC deleted | PV moves to `Released` | PV is removed | | File storage | **Kept, with your data** | **Deleted, permanently** | | Who removes the storage | You, deliberately | Kubernetes, immediately | With `reclaimPolicy: Retain`, deleting the PVC never deletes your data. Kubernetes does not call the driver at all. The `PersistentVolume` is left behind in `Released` state and the file storage still exists in your project. From there you have three options: 1. **Delete it** with the Nscale CLI or in [console.nscale.com](https://console.nscale.com/), once you are sure. 2. **Re-use it.** Bind it to a new PVC in this cluster or in another cluster in the same project, or attach it to a compute instance. See [Use existing file storage](#use-existing-file-storage). 3. **Leave it.** It stays in the project and keeps using quota, so you still have to decide what to do with it later. Find the file storage ID behind a released volume. The CSI `volumeHandle` **is** the file storage ID: ```bash theme={null} kubectl get pv -o custom-columns='PV:.metadata.name,STATUS:.status.phase,CLAIM:.spec.claimRef.name,FILESTORAGE-ID:.spec.csi.volumeHandle' ``` Then remove the leftover Kubernetes object, and the storage itself if you no longer want it: ```bash theme={null} kubectl delete pv nscale filestorage get nscale filestorage delete ``` Under `Retain`, deleting the `PersistentVolume` only removes the Kubernetes object. It does not touch the file storage; only the CLI, the console, or the Nscale API does that. > [!WARNING] > > **The reclaim policy is set on each PV when it is created.** Changing `reclaimPolicy` on the `StorageClass` affects only volumes provisioned after the change. To change an existing one: > > ```bash theme={null} > kubectl patch pv \ > -p '{"spec":{"persistentVolumeReclaimPolicy":"Retain"}}' > ``` > > Check this on any PVC you care about before deleting it. If the PV says `Delete`, the data goes with it. ## Use existing file storage Sometimes the storage exists before the PVC does: a volume retained from a deleted PVC, a dataset shared with another cluster or a compute instance, a filesystem seeded outside Kubernetes, or storage whose lifecycle a different team owns. In those cases you don't ask the driver to provision anything. You point Kubernetes at storage that already exists by writing the `PersistentVolume` yourself. Such a volume is an **admin-managed volume**. The CSI driver only mounts it. It never creates, deletes, or resizes it, whatever happens to the Kubernetes objects. > [!WARNING] > > **The file storage must be attached to the network your NKS cluster uses.** The same file storage can be attached to more than one network, so a volume shared with another cluster or instance is normal. But nothing in this flow checks the attachment for you. If it is missing, the PVC still binds, but the pod hangs in `ContainerCreating` until the NFS mount times out. ### Collect the values ```bash theme={null} nscale filestorage list --region --project nscale filestorage get --json ``` From the output you need the file storage ID, and two values from the attachment for your cluster's network in `status.attachments[]`: | Value | Where | Used as | | - | - | - | | `metadata.id` | The file storage itself | The `volumeHandle`, prefixed with `static:` | | `mountSource` | The attachment, as `server:/export/path` | Split into the `server` and `export-path` volume attributes | | `mountOptions` | The attachment, as a map such as `{"remoteports": "10.0.0.16-10.0.0.19"}` | One `key=value` entry per key in `spec.mountOptions`, for example `remoteports=10.0.0.16-10.0.0.19` | Split `mountSource` on the **last** colon: for `10.0.0.16:/mnt/nfs` the server is `10.0.0.16` and the export path is `/mnt/nfs`. The same values are visible under **Storage → Filesystem** in the console. ### Write the PersistentVolume ```yaml pv.yaml theme={null} apiVersion: v1 kind: PersistentVolume metadata: name: shared-datasets spec: capacity: storage: 200Gi # informational; at least the PVC request accessModes: - ReadWriteMany persistentVolumeReclaimPolicy: Retain storageClassName: "" # prevents a default StorageClass applying mountOptions: - remoteports=10.0.0.16-10.0.0.19 # from the attachment's mountOptions claimRef: # pre-bind, so only this PVC can claim it namespace: my-app name: shared-datasets csi: driver: filestorage.csi.nscale.com volumeHandle: static: volumeAttributes: filestorage.csi.nscale.com/server: "10.0.0.16" filestorage.csi.nscale.com/export-path: "/mnt/nfs" ``` Three details matter: * **`volumeHandle: static:`.** The `static:` prefix is what protects your data. The driver recognizes it and refuses to delete or resize the file storage, so removing this `PersistentVolume` can never remove storage the driver did not create. Keeping the real ID after the prefix means `kubectl get pv` still shows which file storage backs the volume. * **`persistentVolumeReclaimPolicy: Retain`.** With `Retain`, Kubernetes never asks the driver to delete anything in the first place. The `static:` handle is the backstop, not the primary control, so set both. * **`claimRef`.** Without it, any PVC in any namespace that matches on capacity and access mode can bind this volume. Put mount options in `spec.mountOptions`, not in a `filestorage.csi.nscale.com/mount-options` volume attribute. That attribute is split on commas and breaks a comma-separated value such as a `remoteports` list. ### Write the PersistentVolumeClaim ```yaml pvc.yaml theme={null} apiVersion: v1 kind: PersistentVolumeClaim metadata: name: shared-datasets namespace: my-app spec: accessModes: - ReadWriteMany storageClassName: "" volumeName: shared-datasets resources: requests: storage: 200Gi ``` ```bash theme={null} kubectl apply -f pv.yaml kubectl -n my-app apply -f pvc.yaml kubectl -n my-app get pvc shared-datasets ``` `storageClassName: ""` on **both** objects keeps a default `StorageClass` from being applied, and the PVC can't request more than the PV's declared capacity. Pods then mount the PVC exactly as in [step 4](#step-4-mount-the-pvc-in-a-pod). ### What the driver does and does not do | | PVC-provisioned volume | Existing file storage | | - | - | - | | Creates the file storage | Yes, from the PVC | No, you do | | Attaches it to the cluster network | Yes | No, you do | | Checks the network attachment | Yes, before binding | **No** | | Mounts it on the node | Yes | Yes | | Deletes it when the PV goes away | Only with `reclaimPolicy: Delete` | **Never** | | Grows it when the PVC grows | Yes | **Never** (the resize is rejected) | To resize storage used this way, grow the file storage through the CLI or console, then raise `spec.capacity` on the PV to match. Leave the PVC as it is: with `storageClassName: ""` there's no `StorageClass` that allows expansion, so the API server rejects a PVC resize. ## Troubleshooting > **The PVC stays Pending with an unsupported StorageClass parameter error** > > The `StorageClass` has a `filestorage.csi.nscale.com/*` parameter the driver doesn't accept. Use only the [supported parameters](#parameters), then recreate the `StorageClass` and the PVC. > **The PVC never binds** > > Check that `storage-class-id` is a class from the [cluster's region](#step-1-find-your-file-storage-class-id). A class from another region can't be attached to the cluster's network. Run `kubectl describe pvc ` to see the driver's events. > **The pod hangs in ContainerCreating with existing file storage** > > The file storage isn't attached to the cluster's network, so the NFS mount times out. Attach it to that network in the console, or run [`nscale filestorage update `](/docs/cli/filestorage#update) without a file and add the network in the pre-filled prompts, then recreate the pod. A `--file` payload that only lists the network resets `posixAcl` and `atimeUpdateIntervalSeconds`. See [Use existing file storage](#use-existing-file-storage). > **mount.nfs: an incorrect mount option was specified** > > The node doesn't have the NFS client that NKS installs, so it can't use the [attachment mount options](#attachment-mount-options-and-performance). On a self-managed cluster, set `use-attachment-mount-options` to `"false"`. > **A PVC resize is rejected** > > Volumes can only grow. Check that the new request is larger than the current size, and that the `StorageClass` sets `allowVolumeExpansion: true`. For existing file storage, see [what the driver does and does not do](#what-the-driver-does-and-does-not-do). *** ## Related resources > **[Managed Kubernetes (NKS)](/docs/platform-services/managed-kubernetes)** > > Create and connect to an NKS cluster > **[Filesystem](/docs/storage/file-storage)** > > Create, attach, and configure file storage in the console > **[File storage CLI](/docs/cli/filestorage)** > > Manage file storage, storage classes, and snapshot policies from the command line > **[Kubernetes CLI](/docs/cli/kubernetes)** > > Manage clusters and kubeconfigs from the command line # Custom Images Source: https://docs.nscale.com/docs/storage/custom-images Custom images let you upload your own OS image (QCOW2 or RAW format) to use as the base when creating instances. Use them for hardened baselines, pre-configured environments, or any OS build that isn't available as a pre-provisioned image. Unlike snapshots (which copy an existing instance's disk), custom images are uploaded from an external source. > [!NOTE] > > **Prerequisites:** You need an existing project and a custom image file in **QCOW2** or **RAW** format. ## Availability This feature is currently available for the Reserved cloud service environment. > [!NOTE] > > **Supported formats:** Only **QCOW2** and **RAW** image formats are supported. Other formats (e.g., VMDK, VHD) must be converted before uploading. > [!NOTE] > > **Region-scoped:** Custom images are available only in the region where they were uploaded. ## Requirements * An existing **project** to place the resulting instance into * A custom image file in a supported format (**QCOW2** or **RAW**) ## Image Preparation Before uploading, ensure your image: * Uses a supported OS (Linux distributions with cloud-init support are recommended) * Has **cloud-init** installed and configured for first-boot setup (SSH key injection, hostname, etc.) * Is reasonably sized — large images will take longer to upload and provision * Has any required GPU/NVIDIA drivers pre-installed if you intend to use GPU node types ## Custom Image Lifecycle | Action | Details | | - | - | | **Upload** | Upload a QCOW2 or RAW image file via the console | | **Create instance** | Select the custom image as the base when creating a new instance | | **Delete** | Remove the image from your project | > [!WARNING] > > **Deleting a custom image** does not affect instances that were already created from it. Those instances continue to run with their own copy of the disk. ## Step-by-Step ### **Upload a custom image** 1. In the Console, open your project, then go to **Storage → Images** 2. Select the **"Upload Image"** button to begin the custom image upload flow 3. Provide your image file in a supported format (**QCOW2** or **RAW**) 4. Verify the image is available and visible within the list of Custom Images: you can filter between custom images and snapshots by clicking on "Category" on the right side and then filter for the respective image type ![Screenshot2026 03 02at16 09 42](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Screenshot2026-03-02at16.09.42.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=5a4e73d8a322519617d39f820d608fdf) ### **Create an instance from a custom image** 1. In the Console, open your project, then go to **Compute → Instances** and follow the [create instance flow](/docs/compute/create-new-instances) 2. When configuring the instance, select **Custom Image** as the image source (instead of pre-provisioned image or snapshot) ![Instance Flow Custom Image](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/Instance-flow-custom-image.png?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=dd5478f16a4c0ac1963b27e054e82aa0) ## Quotas To check your current image quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows image counts alongside GPU, server, cluster, network, and filesystem quotas. ## Common Issues / Troubleshooting * **Symptom:** Your custom image upload fails or the image is rejected. **Likely cause:** The image format is not supported (only QCOW2 and RAW are accepted). **Fix:** Convert your image to QCOW2 or RAW format before uploading. You can use `qemu-img convert` to convert between formats. * **Symptom:** An instance created from the custom image doesn't boot or has no SSH access. **Likely cause:** The image doesn't have cloud-init configured or the SSH key injection didn't work. **Fix:** Ensure cloud-init is installed and properly configured in the image. Verify that the image's boot configuration is compatible with the Nscale compute environment. *** ## Related Resources > **[Instances](/docs/compute/create-new-instances)** > > Create instances using your custom images > **[Snapshots](/docs/storage/snapshots)** > > Create point-in-time copies of existing instances instead > **[API Reference](/api-reference/images/create-a-compute-image-from-a-disk-image-url)** > > Manage images programmatically via the Networking and Storage API # Filesystem Source: https://docs.nscale.com/docs/storage/file-storage Filesystem is shared persistent NFS storage that can be mounted by multiple instances and clusters simultaneously. It is region-bound and can be attached to one or more VPCs in its region. Use it when you need shared, persistent storage accessible from more than one compute resource. You can also define snapshot policies to create recurring point-in-time snapshots and retain a defined number of them. > [!NOTE] > > **Prerequisites:** You need a [VPC network](/docs/network/vpc-networks) and at least one [instance](/docs/compute/create-new-instances) or [cluster](/docs/platform-services/managed-kubernetes) in the same VPC before you can use the filesystem. ## Summary This page explains how to create and use **Filesystem** storage in the nscale console. By following the steps, you will: * Create a **project-scoped**, **region-bound** shared filesystem * Attach the filesystem to one or more **networks** so instances and clusters in those networks can share it * Configure root access, extended POSIX ACL support, and access-time (`atime`) update behavior * Define **snapshot policies** to automate point-in-time filesystem snapshots * Retrieve the **NFS mount command** and use it to mount the filesystem from your compute resources **Who should use this:** console users who need shared, persistent storage that can be mounted by more than one instance or cluster (within the attached networks). ## Availability This feature is currently only available for the reserved cloud service environment. > [!WARNING] > > **Subnet sizing requirement:** Your VPC must have at least a **/24 CIDR block** (256 IP addresses). Make sure your subnet is sized appropriately before creating a filesystem. > [!NOTE] > > **Multiple network attachments:** A filesystem can be attached to more than one VPC in its region. Each attachment gets its own mount source. To stop a VPC from using the filesystem, remove it from the filesystem's **Associated VPCs**. ## Requirements * Permissions to **create and manage storage resources** in the console * A target **region** selected for the storage resource (Filesystem is region-bound) * One or more **networks** in the same region to attach the storage to * At least one **instance or cluster** in the same network where you will mount the filesystem > [!NOTE] > > If **no VPC** is selected, the **mount command** is **not** provided. You must select a VPC to get the mount command. ## Filesystem lifecycle | Action | Details | | - | - | | **Create** | Provide a name, capacity, and select the VPCs to attach to | | **Resize** | Increase the filesystem capacity at any time from the console | | **NFS settings** | Configure root squash, extended POSIX ACLs, and `atime` updates | | **Snapshot policy** | Configure recurring filesystem snapshots and retention | | **Mount** | Use the NFS mount command from any instance/cluster in an attached VPC | | **Detach** | Remove a VPC from the filesystem's **Associated VPCs** | | **Delete** | Permanently remove the filesystem and all data stored on it | > [!WARNING] > > **Deleting a filesystem permanently removes all data and associated snapshots.** This action cannot be undone. Ensure you have backups or have migrated data before deleting. ## NFS settings Use the NFS settings when creating or editing a filesystem to control root access, extended POSIX ACL support, and read-driven access-time updates. | Console setting | API field | Behavior | | - | - | - | | **Root squash** | `spec.storageType.NFS.rootSquash` | Maps requests from the root user on an NFS client to an unprivileged user when enabled | | **POSIX ACLs** | `spec.storageType.NFS.posixAcl` | Enables extended POSIX ACL support when set to `true` | | **`atime` update interval (seconds)** | `spec.storageType.NFS.atimeUpdateIntervalSeconds` | Sets the minimum age of the existing `atime` before a read updates it | Set **`atime` update interval (seconds)** to `0` to disable read-driven `atime` updates. A positive whole number updates `atime` during a read only when the existing value is older than the configured number of seconds. The accepted range is `0` through `86,399,999,999,999` seconds. > [!WARNING] > > Enabling POSIX ACLs may reduce metadata performance. Extended POSIX ACLs must be managed over NFSv3. Disabling this option does not remove existing ACLs; they may remain enforced. ## Snapshot policies Snapshot policies automate filesystem snapshots on a recurring schedule. Nscale enables **Default Snapshot Protection** by default, and you can add up to **4** snapshot policies with custom schedules and retention. > [!NOTE] > > Default Snapshot Protection is platform-managed. It runs daily at `04:00Z`, keeps the last `7` snapshots, and is controlled separately from user-managed snapshot policies. Use snapshot policies when you need recurring point-in-time protection for filesystem data. Deleting a filesystem is permanent and deletes its associated snapshots. ### Schedule options All snapshot policy times are in UTC and use `HH:MMZ` format, for example `04:00Z`. | Cadence | Required fields | Notes | | - | - | - | | **Hourly** | `interval: hourly` | Do not set `timeOfDay`, `dayOfWeek`, or `dayOfMonth` | | **Daily** | `interval: daily`, `timeOfDay` | Runs once per day at the specified UTC time | | **Weekly** | `interval: weekly`, `dayOfWeek`, `timeOfDay` | `dayOfWeek` must be `monday` through `sunday` | | **Monthly** | `interval: monthly`, `dayOfMonth`, `timeOfDay` | `dayOfMonth` must be between `1` and `28` | The retention value, `keep`, is the number of snapshots to retain and must be at least `1`. When updating policies through the API, policy names are identity keys. Changing a policy name creates a new policy and removes the old one. ### API behavior Default Snapshot Protection is managed with `spec.defaultSnapshotProtectionEnabled`. User-managed snapshot policies are managed inline on the filesystem resource as `spec.snapshotPolicies`. | Operation | `defaultSnapshotProtectionEnabled` value | Result | | - | - | - | | **Create** | Omitted | Enables Default Snapshot Protection | | **Create** | `false` | Creates the filesystem without Default Snapshot Protection | | **Update** | Omitted | Preserves the current Default Snapshot Protection setting | | **Update** | `true` or `false` | Enables or disables Default Snapshot Protection | | **Create/Update** | `null` | Invalid request | | Operation | `snapshotPolicies` value | Result | | - | - | - | | **Create** | Omitted or `[]` | Stores no user-managed snapshot policies | | **Create** | Non-empty list | Stores the supplied user-managed policies exactly | | **Update** | Omitted | Preserves existing user-managed policies | | **Update** | `[]` | Clears all user-managed policies | | **Update** | Non-empty list | Replaces the full user-managed policy list | Public API reads return user-managed snapshot policies only. The platform-managed Default Snapshot Protection policy is not included in `spec.snapshotPolicies` or `status.snapshotPolicies`. Omit `snapshotPolicies` when you do not want to change user-managed policies. Do not send `null`. > [!WARNING] > > Do not use `system-default` as a user-managed policy name while Default Snapshot Protection is enabled. That name is reserved for Nscale's platform-managed default protection. Example user-managed policy list: ```json theme={null} { "snapshotPolicies": [ { "name": "daily", "schedule": { "interval": "daily", "timeOfDay": "04:00Z" }, "retention": { "keep": 7 } }, { "name": "weekly", "schedule": { "interval": "weekly", "dayOfWeek": "monday", "timeOfDay": "02:30Z" }, "retention": { "keep": 4 } } ] } ``` ## Step-by-step 1. **Choose the project and region** * In the Console, select the **project** you want to use under **All Projects** * Select the **region** where you want the filesystem to live 2. **Create (or select) the network you will attach storage to** * Create a new network, or select an existing one in the same region * Confirm the network is in the **same region** as the storage you plan to create * You can attach the filesystem to more than one network in the same region 3. **Create the Filesystem** * Go to **Storage → Filesystem** in the console * Provide the required values (for example: name and capacity) * Configure **Root squash**, **POSIX ACLs**, and **`atime` update interval (seconds)** under the NFS settings * Create the filesystem * You should see the filesystem appear in the resource list, and its status move to a "ready/available" state 4. **Configure snapshot policies (optional)** * Use the **Snapshot policies** section when creating or editing the filesystem * Review Default Snapshot Protection, which is enabled by default * Add user-managed policies if you need additional cadences, UTC schedules, or retention rules * Save the filesystem and verify each user-managed policy reaches a ready/provisioned state 5. **Get the NFS mount command** * In the filesystem details, locate the action or section to Mount your filesystem * Copy the **NFS mount command** * You should see a mount command that you can run from a Linux host in the attached network 6. **Mount from your compute (instance or cluster)** * From a target instance (or nodes in your cluster) that are connected to the same network: * Run the mount command you copied * Confirm the mount worked by verifying the mount point is accessible and read/write as expected ![File Storage](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/File-storage.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=e1f427b0bfe0b2ce643f35f73ae80117) ## View filesystem details Click any filesystem in the list to view its detail page. The detail page includes: * **Overview** — filesystem status, capacity, attached VPCs, and mount command * **Configuration** — capacity, root squash, POSIX ACL, and `atime` update interval * **Instances** — all instances in the attached VPCs that can access this filesystem, with search filtering * **Snapshot policies** — schedules, retention, and provisioning state for each policy The **Instances** tab helps you see at a glance which compute resources are using the filesystem. ## Attachment status and mount options Each filesystem attachment reports its provisioning status. The status reflects the actual observed state of the attachment, not just the desired configuration: | Status | Description | | - | - | | **Provisioning** | The attachment is being set up | | **Provisioned** | The attachment is active and ready for use | | **Deprovisioning** | The attachment is being removed | | **Error** | Something went wrong during attachment provisioning | When an attachment is provisioned, the API also returns **mount options** — specifically a `remoteports` field containing the IP range of the NFS storage endpoints. You can use this range for client-side NFS mount tuning when you need to distribute NFS traffic across multiple storage IPs for better throughput and resilience. > [!NOTE] > > Mount options are returned in the API response under `mountOptions` on each attachment. For most use cases, the standard mount command shown in the console is sufficient. Use the `remoteports` value only when you need advanced NFS client configuration. ## Quotas To check your current filesystem quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows your filesystem storage usage (e.g., 1 GiB / 1 TiB) alongside GPU, server, cluster, and network quotas. ## Common issues / troubleshooting 1. **Symptom:** You can't attach the filesystem to the selected network **Likely cause:** The network is in a different region from the filesystem. **Fix:** Check the filesystem's region, and choose a network in the same region. 2. **Symptom:** The mount command fails from your instance/cluster **Likely cause:** The instance/cluster is not in the attached network, or network access rules prevent NFS connectivity. **Fix:** Confirm the compute resource is connected to the same network the filesystem is attached to. Then verify network/security rules permit NFS traffic (exact ports/rules depend on your setup). 3. **Symptom:** No mount command is shown in the filesystem details **Likely cause:** No VPC has been selected for the filesystem. **Fix:** Edit the filesystem and select a VPC. The mount command will appear once a VPC is attached. 4. **Symptom:** A snapshot policy is rejected or does not provision **Likely cause:** The policy name, schedule, or retention does not match the validation rules. Common issues include using a non-UTC time, setting `timeOfDay` on an hourly policy, omitting `dayOfWeek` on a weekly policy, or using a monthly `dayOfMonth` after `28`. **Fix:** Update the policy so the schedule fields match its cadence and `keep` is at least `1`. 5. **Symptom:** Existing snapshot policies changed after an API update **Likely cause:** API updates replace the full `snapshotPolicies` list when a non-empty list is supplied, or clear all user-managed policies when `[]` is supplied. **Fix:** Include every policy you want to keep in the update request. Omit `snapshotPolicies` if you only want to update other filesystem fields. 6. **Symptom:** A policy named `system-default` is rejected **Likely cause:** Default Snapshot Protection is enabled or is still cleaning up, so `system-default` is reserved for the platform-managed policy. **Fix:** Use a different policy name, or wait until Default Snapshot Protection has been disabled and cleanup has completed before claiming that name. 7. **Symptom:** POSIX ACL tools do not work on the mounted filesystem **Likely cause:** Extended POSIX ACLs are disabled, or you mounted the filesystem using NFSv4.1. NFSv3 is the supported management path for extended POSIX ACLs. **Fix:** Enable **POSIX ACLs** and mount the filesystem using NFSv3 before creating or modifying extended ACLs. 8. **Symptom:** Existing ACLs remain enforced after POSIX ACL is disabled **Likely cause:** Disabling POSIX ACL support does not delete existing ACL metadata. **Fix:** Re-enable **POSIX ACLs**, manage the existing ACLs over NFSv3, and then disable the setting again if required. 9. **Symptom:** File access does not update `atime` **Likely cause:** The interval is `0`, which disables read-driven updates, or the current `atime` is not yet older than a configured positive interval. **Fix:** Set a positive **`atime` update interval (seconds)** and wait until the existing `atime` is older than that interval before testing another read. *** ## Related resources > **[VPC Networks](/docs/network/vpc-networks)** > > Create the network your filesystem attaches to > **[Instances](/docs/compute/create-new-instances)** > > Mount the filesystem from your compute instances > **[Managed Kubernetes (NKS)](/docs/platform-services/managed-kubernetes)** > > Access shared storage from your Kubernetes clusters > **[File storage on NKS](/docs/platform-services/nks-file-storage)** > > Provision and mount filesystems from NKS pods with the CSI driver > **[API Reference](/api-reference/file-storage/list-file-storage)** > > Manage filesystems programmatically via the Networking and Storage API # Object Storage Source: https://docs.nscale.com/docs/storage/object-storage Object Storage provides S3-compatible storage for buckets and objects. It is project-scoped and region-bound. Use it when you need an S3 endpoint for datasets, application assets, backups, artifacts, or other object-based workloads. > [!NOTE] > > **Prerequisites:** You need an existing project, an available region, and permissions to create object storage endpoints and access keys before you can use Object Storage. ## Summary This page explains how to create and use **Object Storage** in the Nscale Console. By following the steps, you will: * Create a **project-scoped**, **region-bound** S3-compatible endpoint * Find and filter Object Storage endpoints by **region** and **status** * Manage endpoint **access keys** and **identity policies** from the endpoint details page * Retrieve the endpoint URL after provisioning completes and use it with an S3-compatible client **Who should use this:** console users who need S3-compatible object storage that can be accessed from applications, instances, clusters, CI jobs, or data tooling. ## Availability This feature is currently only available for the reserved cloud service environment. > [!WARNING] > > **One endpoint per project and region:** Each project can have only one Object Storage endpoint in a given region. If a project already has an endpoint in that region, choose another region or delete the existing endpoint first. > [!WARNING] > > **Access key secrets are shown once:** The secret access key is only returned when the access key is created. Copy it immediately and store it securely. If you lose it, create a new access key and delete the old one. ## Requirements * Permissions to **create and manage object storage resources** * A target **project** and **region** selected for the object storage endpoint * An **identity policy** that allows the S3 actions your workload needs * An S3-compatible client or SDK, such as the AWS CLI > [!NOTE] > > The endpoint URL is available only after the endpoint finishes provisioning. ## Object Storage Lifecycle | Action | Details | | - | - | | **Create endpoint** | Provide a name, project, and region | | **Configure identity policies** | Use the `system-default-admin` policy or add custom S3 policy documents for least-privilege access | | **Create access key** | Create credentials tied to an identity policy. The secret is returned only once | | **Use S3 client** | Use the endpoint URL with your access key ID and secret to create buckets and manage objects | | **Delete access key** | Revoke a credential without deleting the endpoint or stored objects | | **Delete endpoint** | Permanently remove the endpoint and the object storage resources associated with it | > [!WARNING] > > **Deleting an Object Storage endpoint permanently removes the endpoint and associated buckets/objects.** This action cannot be undone. Ensure data has been backed up or migrated before deleting. ## Identity Policies Identity policies define which S3 actions an access key can perform. Policies use AWS-style JSON policy documents with `Version`, `Statement`, `Effect`, `Action`, and `Resource` fields. If you create an endpoint without custom policies, Object Storage seeds a default `system-default-admin` policy that allows `s3:*` on all resources. For production workloads, create narrower policies for each workload or team. In the console, identity policies are managed from the **Identity Policies** tab. New policies are added by providing a policy name and uploading a `.json` policy document. Example read/write policy for all buckets: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket", "s3:GetObject", "s3:PutObject" ], "Resource": "*" } ] } ``` ## S3 API Compatibility Object Storage is S3-compatible for common bucket and object workflows, but it does not implement every AWS S3 feature. See the unsupported features below: | Unsupported feature | Description | | - | - | | **Public (anonymous) access** | Objects and buckets can't be made publicly readable. Setting a `public-read` ACL on an object or bucket does not grant anonymous access, and unauthenticated requests are denied. To share objects without distributing credentials, use [pre-signed URLs](#share-objects-with-pre-signed-urls). | | **Bucket CORS configuration** | Bucket-level CORS rules are not supported through the S3 API. Requests such as `PutBucketCors` return `NotImplemented`. | | **IAM API** | AWS IAM-compatible APIs for users, roles, and policies are not available on the Object Storage endpoint. Manage Object Storage access through identity policies and access keys. | | **Lifecycle rules** | S3 lifecycle configuration is not supported through `PutBucketLifecycleConfiguration`. This includes expiration rules, aborting incomplete multipart uploads, and noncurrent version cleanup. Implement lifecycle cleanup in your application or automation. | | **Bucket metrics configuration** | S3 bucket metrics configuration APIs are not supported. | | **Bucket replication** | S3 replication configuration, including cross-region replication and same-region replication, is not supported through `PutBucketReplication` or related APIs. | | **SSE-C** | Server-side encryption with customer-provided keys using `x-amz-server-side-encryption-customer-*` headers is not supported. | | **Signature Version 2** | Legacy SigV2 authentication is not supported. Use Signature Version 4 for all S3 requests. | | **Static website hosting** | S3 static website hosting configuration is not supported. Serve static content through an application, web server, or CDN layer instead. | | **Suspend versioning** | Enabling bucket versioning is supported, but suspending versioning after it has been enabled is not supported. | ## Step-by-Step 1. **Open Object Storage** * In the Console, open your project, then go to **Storage → Object Storage** * Use the search field to find an existing endpoint by name * Use the **Region** and **Status** filters to narrow the list ![Object Storage endpoint list](https://mintcdn.com/nscale/nb6MvZzHGaqDMUUZ/images/object-storage-list.png?fit=max\&auto=format\&n=nb6MvZzHGaqDMUUZ\&q=85\&s=fff48ea07eec5a7206c7feb5e95e319e) 2. **Create the Object Storage endpoint** * Click **Create Object Storage** * Enter an **Object Storage Name** * Select the **Project** * Select an available **Region** from the region picker * Click **Create Object Storage** and wait for the endpoint to reach **Provisioned** 3. **Open the endpoint details page** * Select the endpoint from the Object Storage list * Confirm the header shows the endpoint name and a **Provisioned** status badge * Use the **Overview**, **Access Keys**, and **Identity Policies** tabs to manage the endpoint ![Object Storage endpoint details](https://mintcdn.com/nscale/nb6MvZzHGaqDMUUZ/images/object-storage-details.png?fit=max\&auto=format\&n=nb6MvZzHGaqDMUUZ\&q=85\&s=2904ed14e6f0fe7d739df668b21774f8) 4. **Add or review identity policies** * Open the **Identity Policies** tab * To add a policy, click **Add Policy** * Provide a **Policy Name** and upload a `.json` custom policy document * Click **Add Policy** ![Identity Policies tab](https://mintcdn.com/nscale/nb6MvZzHGaqDMUUZ/images/object-storage-identity-policies.png?fit=max\&auto=format\&n=nb6MvZzHGaqDMUUZ\&q=85\&s=00410f8695ae13778f595ae40bc0d830) 5. **Create an access key** * Open the **Access Keys** tab * Click **Add Access Key** * Enter an access key name * Click **Next: Select Policy** * Select an existing identity policy, or upload a custom `.json` policy document and give it a policy name * Click **Add Access Key** * Copy the **Access Key ID** and **Secret Access Key** immediately from the creation dialog ![Access Keys tab](https://mintcdn.com/nscale/nb6MvZzHGaqDMUUZ/images/object-storage-access-keys.png?fit=max\&auto=format\&n=nb6MvZzHGaqDMUUZ\&q=85\&s=b03122d275b39f810575ab54d36fe6d9) 6. **Configure your S3 client** * Set the endpoint URL, access key ID, and secret access key in your S3 client * Use any S3-compatible workflow to create buckets and manage objects Example AWS CLI configuration: ```bash theme={null} export AWS_ACCESS_KEY_ID="" export AWS_SECRET_ACCESS_KEY="" export AWS_DEFAULT_REGION="" export EP="https://" aws --endpoint-url "$EP" s3api list-buckets aws --endpoint-url "$EP" s3 mb s3://example-bucket aws --endpoint-url "$EP" s3 cp ./data.csv s3://example-bucket/data.csv ``` > [!TIP] > > The Nscale CLI includes an S3 client with the same flag names and response shapes as `aws s3api`, for the operations it supports. Run `nscale s3api configure` to pick an endpoint and create an access key in one step. See [`nscale s3api`](/docs/cli/s3api). ## Share objects with pre-signed URLs Object Storage does not support public objects or anonymous access. To give someone temporary access to an object without sharing your access keys, generate a **pre-signed URL**. Anyone with the URL can download the object until the URL expires, and access stays time-limited and tied to a specific object, which is safer than making the object public. > [!NOTE] > > Pre-signed URLs are valid for a maximum of **7 days** (`604800` seconds). For continued access, generate and share a new URL before the current one expires. Generating a new URL does not extend the old one. The following example uses the AWS CLI to create a bucket, upload a file, generate a pre-signed URL, and download the file with that URL: ```bash theme={null} export AWS_ACCESS_KEY_ID="" export AWS_SECRET_ACCESS_KEY="" export AWS_DEFAULT_REGION="" export EP="https://" export BUCKET="example-bucket" # 1. Create a bucket aws --endpoint-url "$EP" s3 mb "s3://$BUCKET" # 2. Upload a file aws --endpoint-url "$EP" s3 cp ./demo.mov "s3://$BUCKET/demo.mov" # 3. Generate a pre-signed URL that is valid for 1 hour (3600 seconds) URL=$(aws --endpoint-url "$EP" s3 presign "s3://$BUCKET/demo.mov" --expires-in 3600) echo "$URL" # 4. Download the object with the pre-signed URL (no credentials required) curl -fSL -o downloaded-demo.mov "$URL" ``` Share the URL printed in step 3 with anyone who needs access. An unsigned request to the same object, such as `curl "$EP/$BUCKET/demo.mov"`, is denied. When you use pre-signed URLs: * **Sign with a least-privilege key.** The signing key must allow `s3:GetObject` for the object being shared. Consider generating URLs with a dedicated access key whose read-only identity policy is scoped to the objects you want to share. * **Keep expiry times short.** Choose the shortest `--expires-in` value that fits your use case, and treat the URL like a secret while it is valid. * **Revoke access early by deleting the key.** Deleting the access key that signed a URL invalidates every URL signed with it, even before they expire. ## Terraform Example If you provision infrastructure with Terraform, use the Object Storage example in the public `terraform-provider-nscale` repository as a starting point: > **[Object Storage Terraform Example](https://github.com/nscaledev/terraform-provider-nscale/blob/main/examples/object-storage/main.tf)** > > Create an Object Storage endpoint, identity policy, and access key with the nscale Terraform provider ## Common Issues / Troubleshooting 1. **Symptom:** You can't select a region when creating Object Storage **Likely cause:** The selected project already has an endpoint in that region. **Fix:** Choose another project, or delete the existing endpoint for that project/region if it is no longer needed. 2. **Symptom:** No endpoint URL is shown **Likely cause:** The endpoint is still provisioning or has not published its public exposure details yet. **Fix:** Wait for the endpoint status to become ready/provisioned. If the URL still does not appear, check the endpoint health status or contact support. 3. **Symptom:** You can't retrieve an access key secret later **Likely cause:** Secrets are returned only once, when the access key is created. **Fix:** Create a new access key, update your workload with the new credentials, then delete the old access key. 4. **Symptom:** S3 requests fail with access denied **Likely cause:** The access key is attached to an identity policy that does not allow the requested S3 action or bucket/object resource. **Fix:** Review the policy attached to the access key. Confirm it includes the required `s3:` actions and the correct bucket/object resources. 5. **Symptom:** You can't remove an identity policy **Likely cause:** One or more access keys still reference that policy. **Fix:** In the **Identity Policies** tab, check **Keys Using**. Delete or recreate the access keys that use the policy, then remove the policy. 6. **Symptom:** An object uploaded with a `public-read` ACL still returns access denied for unauthenticated requests **Likely cause:** Object Storage does not support public (anonymous) access. ACLs such as `public-read` do not make objects publicly readable. **Fix:** Generate a [pre-signed URL](#share-objects-with-pre-signed-urls) for the object and share that URL instead. *** ## Related Resources > **[CLI: Object Storage](/docs/cli/object-storage)** > > Manage object storage endpoints, policies, and access keys from the command line > **[Filesystem](/docs/storage/file-storage)** > > Use shared NFS storage when workloads need a mounted filesystem > **[Instances](/docs/compute/create-new-instances)** > > Run S3-compatible clients from your compute instances > **[API Reference](/api-reference/object-storage/list-endpoints)** > > Manage object storage endpoints and access keys programmatically via the Storage Service API # Snapshots Source: https://docs.nscale.com/docs/storage/snapshots A snapshot is a point-in-time disk copy of an instance. Snapshots are region-scoped and can be used to restore an instance to a previous state or to create new instances with the same disk contents. They are the quickest way to clone or back up an existing instance. > [!NOTE] > > **Prerequisite:** You need an existing [instance](/docs/compute/create-new-instances) to take a snapshot of. > [!NOTE] > > **Region-scoped:** Snapshots are only available in the region where they were created. When creating an instance from a snapshot, make sure you select the same region. ## Availability This feature is currently only available within the reserved cloud service environment. ## Requirements * Check if you have the required permissions for taking a snapshot * Make sure to have an instance set up you can take the snapshot of (the instance itself can either be stopped or running) * Check if you have sufficient snapshot quota > [!TIP] > > For the most consistent snapshot, it is recommended to **stop the instance** before taking a snapshot. Snapshots of running instances are supported but may capture in-flight writes. ## Snapshot vs Custom Image | | Snapshot | Custom Image | | - | - | - | | **Source** | Created from an existing instance's disk | Uploaded externally (QCOW2 or RAW file) | | **Use case** | Back up, restore, or clone an instance | Bring your own OS baseline or hardened image | | **Scope** | Region-scoped (same region as source instance) | Region-scoped (available in upload region) | | **Creation** | One-click from instance details | Upload flow in Storage → Images | ## Snapshot Lifecycle | Action | Details | | - | - | | **Create** | Take a point-in-time copy from an instance's disk | | **Create instance from snapshot** | Use the snapshot as the base image when creating a new instance | | **Delete** | Permanently remove the snapshot | > [!WARNING] > > **Deleting a snapshot is permanent.** The snapshot data cannot be recovered after deletion. Existing instances created from the snapshot are not affected. ## Step-by-step ### Taking a snapshot 1. In the Console, open your project, then go to **Compute → Instances** 2. Choose the instance you want to take a snapshot of within the list and click on it to be redirected to the instance details page 3. Click on **"Create image from disk"** in the details section on the right side 4. A point-in-time copy of your instance is created and will be added to the list of snapshots and images ![Screenshot2026 03 02at16 11 42](https://mintcdn.com/nscale/brZSlQQ_eSjy7uhb/images/Screenshot2026-03-02at16.11.42.png?fit=max\&auto=format\&n=brZSlQQ_eSjy7uhb\&q=85\&s=9770163f3da14b5300a656538da2b713) ### Creating an instance from a snapshot 1. In the Console, open your project, then go to **Compute → Instances** 2. Click **New Instance** and fill in the basic details (name, project) and networking (VPC, security group) 3. In the **Configure your instance** section, select **Snapshot** as the image source 4. Choose the snapshot you want to use from the list — make sure the **region matches** the region where the snapshot was created 5. Complete the remaining configuration and click **Create instance** > [!NOTE] > > If you don't see your snapshot in the list, check that the region selected for the new instance matches the region where the snapshot was created. ## Quotas To check your current snapshot and image quota, go to the **Resource Usage** section on the **Dashboard**. The dashboard shows your usage alongside GPU, server, cluster, network, and filesystem quotas. ### Common Issues / Troubleshooting * **Symptom:** You don't see the expected snapshot in the **Create instance** flow when selecting a snapshot. **Likely cause:** The snapshot is **region-scoped**, and the snapshot was created in a **different region** than the one selected for the new instance. **Fix:** In the instance creation flow, confirm the **Region** selection matches the region where the snapshot was created. If needed, restart the flow and select the correct region, then check the snapshot list again. * **Symptom:** Snapshot creation seems to hang or take a long time. **Likely cause:** The instance disk is large or the instance was running during the snapshot. **Fix:** For large disks, allow more time. For the most consistent results, stop the instance before taking a snapshot. *** ## Related Resources > **[Instances](/docs/compute/create-new-instances)** > > Create instances from snapshots or take snapshots of existing instances > **[Custom Images](/docs/storage/custom-images)** > > Upload your own OS images instead of using snapshots > **[API Reference](/api-reference/instances/snapshot-instance)** > > Manage snapshots programmatically via the Compute API # Chat Source: https://docs.nscale.com/docs/use-cases/chat This guide will walk you through integrating a chat model into your application using Nscale’s API. With our serverless architecture, you can focus on building your application without worrying about infrastructure management. ## Prerequisites 1. **Service Token:** Sign up on the Nscale platform to create your [**service token**](/docs/manage/service-tokens). 2. **Model Selection:** Choose a chat model from Nscale’s library. * Example: Llama 3.1 8B Instruct `meta-llama/Llama-3.1-8B-Instruct` ## Step 1: Set up your environment Before making requests, ensure you have the necessary tools installed for your language of choice: For Python: Install openai library ```bash theme={null} pip install openai ``` For Typescript: Install openai library ```bash theme={null} npm install openai ``` For cURL: Ensure cURL is installed on your system (it's usually pre-installed on most Unix-based systems). ## Step 2: Sending an inference request Let's walk through an example where we summarise a blog post into 100 words. **Request structure** Each request to the Nscale Chat Completions API endpoint should include the following: 1. Headers: * `"Authorization": "Bearer "` * `"Content-Type": "application/json"` 2. Payload: * `"model"`: `""` * `"messages"`: `""` Example use case: Summarise a blog post ```python Python theme={null} import os import openai nscale_service_token = os.getenv("NSCALE_SERVICE_TOKEN") nscale_base_url = "https://inference.api.nscale.com/v1" client = openai.OpenAI( api_key=nscale_service_token, base_url=nscale_base_url ) blog_text = "Serverless inference simplifies access to AI models..." response = client.chat.completions.create( model="meta-llama/Llama-3.1-8B-Instruct", messages=[ {"role": "system", "content": "Provide a summary of the blog post in 100 words."}, {"role": "user", "content": blog_text} ] ) print(response.choices[0].message.content) ``` ```typescript Typescript theme={null} import OpenAI from 'openai'; const nscaleServiceToken = process.env.NSCALE_SERVICE_TOKEN; const nscaleBaseUrl = "https://inference.api.nscale.com/v1"; const client = new OpenAI({ apiKey: nscaleServiceToken, baseURL: nscaleBaseUrl }); const blogText = "Serverless inference simplifies access to AI models..."; const response = await client.chat.completions.create({ model: "meta-llama/Llama-3.1-8B-Instruct", messages: [ { role: "system", content: "Provide a summary of the blog post in 100 words." }, { role: "user", content: blogText } ] }); console.log(response.choices[0].message.content); ``` ```bash cURL theme={null} curl https://inference.api.nscale.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $NSCALE_SERVICE_TOKEN" \ -d '{ "model": "meta-llama/Llama-3.1-8B-Instruct", "messages": [ { "role": "system", "content": "Provide a summary of the blog post in 100 words." }, { "role": "user", "content": "Serverless inference simplifies access to AI models..." } ] }' ``` ## Step 3: Understanding the response The API will return a JSON object containing the model's output and token usage: Example Response: ```json theme={null} { "choices": [ { "message": { "role": "assistant", "content": "In this article, the author discusses the challenges of deploying Artificial Intelligence (AI) models in real-world applications..." } } ], "usage": { "completion_tokens": 175, "prompt_tokens": 1172, "total_tokens": 1347 } } ``` Key Fields: * `choices`: An array of message objects containing the model's output. * `usage`: An object containing the input (prompt\_tokens), output (completion\_tokens), and total number of tokens used. ## Step 4: Using the CLI for Chat Inferencing You can also use the Nscale CLI to interact with chat models. This is a convenient way to test models or build command-line applications. ### Prerequisites * Ensure you have the [Nscale CLI installed](/docs/cli/overview) ### Examples Here are some examples of using the CLI for chat inferencing: ```bash theme={null} # Generate a single response nscale chat "What is machine learning?" -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct # Start an interactive chat session nscale chat -i -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct # Use a custom system message nscale chat --message "system:You are a creative storyteller" -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct # Get usage statistics in JSON format nscale chat "Explain quantum computing" --stats -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct # Limit the response length nscale chat "Write a story" --max-tokens 100 -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct # Supply chat history nscale chat -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct \ --message "system:You are a helpful assistant" \ --message "user:What is your name?" # Start interactive mode with chat history nscale chat -i -t $NSCALE_SERVICE_TOKEN -m meta-llama/Llama-3.1-8B-Instruct \ --message "system:You are a helpful assistant" \ --message "user:Hello" \ --message "assistant:Hello! How can I help?" # Use service token from environment variable export NSCALE_SERVICE_TOKEN=your_service_token nscale chat "What is machine learning?" -m meta-llama/Llama-3.1-8B-Instruct ``` For more details on CLI usage, refer to the [CLI documentation](/docs/cli/overview). ## Step 5: Monitoring and scaling Nscale handles scaling automatically based on traffic patterns—no manual intervention needed! Use the Nscale Console to monitor: * API usage by model * Spend breakdowns For custom models or high-throughput applications on dedicated endpoints, contact Nscale Support. ## Troubleshooting Common status codes and their meanings: | Status | Description | Response Format | | - | - | - | | 200 | Success (synchronous) | `application/json` response with completion | | 201 | Success (streaming) | `text/event-stream` with delta updates | | 401 | Invalid service token or unauthorized | Error object | | 404 | Model not found or unavailable | Error object | | 429 | Insufficient credit | Error object | | 500 | Internal server error | Error object | | 503 | Service temporarily unavailable | Error object | ### Success Response Format (200) ```json theme={null} { "id": "cmpl-123", "object": "chat.completion", "created": 1677652288, "model": "meta-llama/Llama-3.1-8B-Instruct", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "..." }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 56, "completion_tokens": 31, "total_tokens": 87 } } ``` ### Error Response Format ```json theme={null} { "error": { "code": "TOO_MANY_REQUESTS", "message": "You have insufficient credit to run this request", "param": null, "error_type": "INSUFFICIENT_CREDIT" } } ``` For the extensive list of error codes and handling, see the [error code page](https://nscale.mintlify.app/docs/faqs/error-codes) By following this guide, you'll be able to easily integrate chat models into your application using Nscale's serverless inference service. > **[Contact Support](mailto:helpdesk@nscale.com)** > > Need assistance? Get help from our support team # Image Generation Source: https://docs.nscale.com/docs/use-cases/image-generation This guide will walk you through integrating image generation models into your application using Nscale's API. With our serverless architecture, you can focus on building your application without worrying about infrastructure management. ## Prerequisites 1. **Service Token:** Sign up on the Nscale platform to create your [**service token**](/docs/manage/service-tokens). 2. **Model Selection:** Choose an image generation model from Nscale's [model library](/docs/ai-services/models). * Example: FLUX.1 \[schnell] `black-forest-labs/FLUX.1-schnell` ## Step 1: Set up your environment Before making requests, ensure you have the necessary tools installed for your language of choice: For Python: Install openai library ```bash theme={null} pip install openai ``` For Typescript: Install openai library ```bash theme={null} npm install openai ``` For cURL: Ensure cURL is installed on your system (it's usually pre-installed on most Unix-based systems). ## Step 2: Sending an image generation request Let's walk through an example where we generate an image based on a text prompt. **Request structure** Each request to the Nscale Image Generation API endpoint should include the following: 1. Headers: * `"Authorization": "Bearer "` * `"Content-Type": "application/json"` 2. Payload: * `"model"`: `""` * `"prompt"`: `""` * `"size"`: `""` * `"n"`: `""` Example use case: Generate a landscape at sunset ```python Python theme={null} import os import openai nscale_service_token = os.getenv("NSCALE_SERVICE_TOKEN") nscale_base_url = "https://inference.api.nscale.com/v1" client = openai.OpenAI( api_key=nscale_service_token, base_url=nscale_base_url ) response = client.images.generate( model="black-forest-labs/FLUX.1-schnell", prompt="A serene mountain landscape at sunset with a lake reflecting the orange sky", size="1024x1024", # Optional n=1 # Optional ) print(response.data[0].b64_json) ``` ```typescript TypeScript theme={null} import OpenAI from 'openai'; const nscaleServiceToken = process.env.NSCALE_SERVICE_TOKEN; const nscaleBaseUrl = "https://inference.api.nscale.com/v1"; const client = new OpenAI({ apiKey: nscaleServiceToken, baseURL: nscaleBaseUrl }); const response = await client.images.generate({ model: "black-forest-labs/FLUX.1-schnell", prompt: "A serene mountain landscape at sunset with a lake reflecting the orange sky", size: "1024x1024", // Optional n: 1 // Optional }); console.log(response.data[0].b64_json); ``` ```bash cURL theme={null} curl https://inference.api.nscale.com/v1/images/generations \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $NSCALE_SERVICE_TOKEN" \ -d '{ "model": "black-forest-labs/FLUX.1-schnell", "prompt": "A serene mountain landscape at sunset with a lake reflecting the orange sky", "size": "1024x1024", "n": 1 }' ``` ## Step 3: Understanding the Response The response from the image generation API contains: * A base64-encoded image in the `b64_json` field * A timestamp of when the image was created * The response is returned as a single object, with an array of generated images in the `data` field Here's the output from the example request: ![Example request generated image](https://mintcdn.com/nscale/eHooAh3A-xA3WCln/images/image-generation-example.jpg?fit=max\&auto=format\&n=eHooAh3A-xA3WCln\&q=85\&s=0142bdfe7cce10032fa316368da41d76) ## Step 4: Using the CLI for Image Generation You can also use the Nscale CLI to generate images. This is a convenient way to test models or build command-line applications. ### Prerequisites * Ensure you have the [Nscale CLI installed](/docs/cli/overview) ### Examples Here are some examples of using the CLI for image generation: ```bash theme={null} # Generate an image with default settings nscale images generate "A sunset over mountains" -t $NSCALE_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell # Generate an image with custom size nscale images generate "A futuristic city" -z 1024x1024 -t $NSCALE_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell # Generate and automatically open the image nscale images generate "A cat playing piano" -x -t $NSCALE_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell # Generate with ASCII preview nscale images generate "An abstract painting" -p -t $NSCALE_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell # Generate with custom output location nscale images generate "A forest landscape" -o ./my-image.png -t $NSCALE_SERVICE_TOKEN -m black-forest-labs/FLUX.1-schnell # Use service token from environment variable export NSCALE_SERVICE_TOKEN=your_service_token nscale images generate "A sunset over mountains" -m black-forest-labs/FLUX.1-schnell ``` For more details on CLI usage, refer to the [CLI documentation](/docs/cli/overview). ## Step 5: Monitoring and scaling Nscale handles scaling automatically based on traffic patterns—no manual intervention needed! Use the Nscale Console to monitor: * API usage by model * Spend breakdowns For custom models or high-throughput applications on dedicated endpoints, contact Nscale Support. ## Troubleshooting Common status codes and their meanings: | Status | Description | Response Format | | - | - | - | | 200 | Success | `application/json` response with image data | | 401 | Invalid service token or unauthorized | Error object | | 404 | Model not found or unavailable | Error object | | 429 | Insufficient credit | Error object | | 500 | Internal server error | Error object | | 503 | Service temporarily unavailable | Error object | ### Success Response Format (200) ```json theme={null} { "created": 1677652288, "data": [ { "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..." } ] } ``` ### Error Response Format ```json theme={null} { "error": { "code": "TOO_MANY_REQUESTS", "message": "You have insufficient credit to run this request", "param": null, "error_type": "INSUFFICIENT_CREDIT" } } ``` For the extensive list of error codes and handling, see the [error code page](https://nscale.mintlify.app/docs/faqs/error-codes) ## Available Models For a complete list of available image generation models and their pricing, please refer to our [models page](/docs/ai-services/models). > **[Contact Support](mailto:helpdesk@nscale.com)** > > Need assistance? Get help from our support team