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



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



# Changelog
Source: https://docs.nscale.com/changelog/changelog

News and improvements from the Nscale team.

<Update label="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
</Update>

<Update label="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
</Update>

<Update label="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
</Update>

<Update label="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
</Update>

<Update label="July 2025">
  ## Serverless Fine-tuning

  <Frame>
    <img alt="Serverless Fine-tuning" />
  </Frame>

  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":"<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

  ```
</Update>

<Update label="March 2025">
  ## Serverless Inference

  <Frame>
    <img alt="Serverless Inference" />
  </Frame>

  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
        }'
  ```
</Update>


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


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

Our model list is available in the Nscale Console under **AI Services → Models**, or on [our website <Icon icon="arrow-up-right" />](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)
</Tip>

<Card title="Looking for a model?" icon="headset">
  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.
</Card>


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

<img alt="Workbench visual" />

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

<Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
  Need assistance? Get help from our support team
</Card>


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

<CardGroup>
  <Card title="Serverless" icon="bolt" href="https://petstore.swagger.io/?url=https://inference.api.nscale.com/openapi.yaml">
    Serverless AI inference and model access.
  </Card>

  <Card title="Compute" icon="server" href="https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/compute/latest/openapi.yaml">
    Provisioning and lifecycle management of Compute instances.
  </Card>

  <Card title="Identity" icon="id-badge" href="https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/identity/latest/openapi.yaml">
    Organizations, users, and access control.
  </Card>

  <Card title="Region" icon="globe" href="https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/region/latest/openapi.yaml">
    Networking and storage resources scoped to a region.
  </Card>

  <Card title="Storage" icon="database" href="https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/storage/latest/openapi.yaml">
    Object storage endpoints and access keys.
  </Card>

  <Card title="Reservation" icon="calendar-check" href="https://petstore.swagger.io/?url=https://raw.githubusercontent.com/nscaledev/openapi/main/reservation/latest/openapi.yaml">
    GPU capacity reservations and placement.
  </Card>
</CardGroup>


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

```bash theme={null}
nscale contexts set --name <name> --org <organization-id> [--project <project-id>] [--region <region-id>] [--user <user>]
```

### Flags

| Flag               | Description                     |
| ------------------ | ------------------------------- |
| `--name string`    | Context name                    |
| `--org string`     | Organization ID                 |
| `--project string` | Project ID                      |
| `--region string`  | Region ID                       |
| `--user string`    | Keyring user credentials to use |

### Examples

```bash theme={null}
nscale contexts set --name prod --user default --org <organization-id> --project <project-id> --region <region-id>
```

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

```bash theme={null}
nscale contexts use <name>
```

### Example

```bash theme={null}
nscale contexts use prod
```

***

## list

List all configured contexts.

**Aliases:** `list`, `ls`

```bash theme={null}
nscale contexts list
```

***

## delete

Delete a context by name.

**Aliases:** `delete`, `rm`, `remove`

```bash theme={null}
nscale contexts delete <name>
```

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

```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<br/>{ client_id, scope }
  API-->>CLI: { device_code, user_code,<br/>verification_uri,<br/>expires_in: 600,<br/>interval: 5 }
  CLI->>Browser: Display verification URI<br/>and user code
  Browser->>API: GET /auth/device?code=XXXX-YYYY
  Browser->>API: POST /api/auth/device/verify<br/>{ code }
  API-->>Browser: { valid: true, scope }
  Browser->>API: GET /auth/device/callback
  Note over API: authorizeDevice() stores tokens<br/>in secure session store
  loop Poll until authorized
    CLI->>API: POST /api/oauth2/token<br/>{ grant_type: device_code,<br/>device_code, client_id }
    API-->>CLI: authorization_pending / slow_down
  end
  API-->>CLI: { access_token, refresh_token,<br/>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 "client_id=<CLI_CLIENT_ID>&scope=openid%20profile%20email"
```

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" \
  -d "client_id=<CLI_CLIENT_ID>"
```

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=<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<void> {
  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)


# File storage
Source: https://docs.nscale.com/docs/cli/filestorage

Manage file storage resources.

**Aliases:** `filestorage`, `fs`

## Subcommands

* [list](#list) — List file storage resources
* [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

***

## list

List file storage resources, optionally filtered by organization, project, or region.

```bash theme={null}
nscale filestorage list [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale filestorage list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific file storage resource.

```bash theme={null}
nscale filestorage get --id <storage-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>File storage ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new file storage resource. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale filestorage create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

```bash theme={null}
nscale filestorage update --id <storage-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>File storage ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale filestorage update --id <storage-id> --file storage.json
nscale filestorage update --id <storage-id> --stdin < storage.json
cat storage.json | nscale filestorage update --id <storage-id> --stdin
```

***

## delete

Delete an existing file storage resource.

```bash theme={null}
nscale filestorage delete --id <storage-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | File storage ID                                |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale filestorage delete --id <storage-id> --org <org-id> --yes
```

***

## Related

<CardGroup>
  <Card title="File Storage (Console)" icon="browser" href="/docs/storage/file-storage">
    Create and manage file storage via the Console UI.
  </Card>
</CardGroup>


# 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 available flavors

***

## list

List available flavors, optionally filtered by organization and region.

```bash theme={null}
nscale flavors list [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
# List all flavors in a region
nscale flavors list --org <org-id> --region <region-id>

# Output as JSON
nscale flavors list --org <org-id> --region <region-id> --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.

## 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 <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## get

Get details for a specific group.

```bash theme={null}
nscale groups get --id <group-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Group ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new group in the specified organization. Supports interactive mode or JSON input.

```bash theme={null}
nscale groups create --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale groups create --org <org-id> --file group.json
nscale groups create --org <org-id> --stdin < group.json
cat group.json | nscale groups create --org <org-id> --stdin
# Interactive mode
nscale groups create
```

***

## update

Update an existing group.

```bash theme={null}
nscale groups update --org <org-id> --id <group-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Group ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale groups update --org <org-id> --id <group-id> --file group.json
nscale groups update --org <org-id> --id <group-id> --stdin < group.json
cat group.json | nscale groups update --org <org-id> --id <group-id> --stdin
```

***

## delete

Delete an existing group.

```bash theme={null}
nscale groups delete --org <org-id> --id <group-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Group ID                                       |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request 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`

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale images list --org <org-id> --region <region-id>
```

***

## create

Create a new custom image. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale images create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### 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 --id <image-id> [flags]
```

### Flags

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `--id string`     | Image ID                                       |
| `--org string`    | Organization ID                                |
| `--region string` | Region ID                                      |
| `--dry-run`       | Preview the request payload without persisting |
| `-y, --yes`       | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale images delete --id <image-id> --org <org-id> --yes
```

***

## Related

<CardGroup>
  <Card title="Custom Images (Console)" icon="browser" href="/docs/storage/custom-images">
    Upload and use custom OS images via the Console UI.
  </Card>
</CardGroup>


# 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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale inferencing list-endpoints --org <org-id>
```

***

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

<CardGroup>
  <Card title="Models" icon="cloud" href="/docs/ai-services/models">
    Learn about available models on the Nscale platform.
  </Card>

  <Card title="Chat Use Case" icon="message" href="/docs/use-cases/chat">
    End-to-end guide for chat inferencing.
  </Card>
</CardGroup>


# Instances
Source: https://docs.nscale.com/docs/cli/instances

Manage compute instances.

**Aliases:** `instances`, `inst`

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--network string</code></td><td>Network ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale instances list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific instance.

```bash theme={null}
nscale instances get --id <instance-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Instance ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new compute instance. Accepts input from a JSON file or stdin. Optionally supply a cloud-init configuration or bind an SSH certificate authority.

```bash theme={null}
nscale instances create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--cloud-init-path string</code></td><td>Path to a cloud-init YAML file</td></tr>
    <tr><td><code>--ssh-ca-id string</code></td><td>SSH certificate authority ID to bind (pass empty string to clear)</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

```bash theme={null}
nscale instances update --id <instance-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Instance ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--ssh-ca-id string</code></td><td>SSH certificate authority ID to bind to the instance (pass an empty string to clear)</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale instances update --id <instance-id> --file instance.json
nscale instances update --id <instance-id> --stdin < instance.json
cat instance.json | nscale instances update --id <instance-id> --stdin
```

***

## delete

Delete an existing instance.

```bash theme={null}
nscale instances delete --id <instance-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Instance ID                                    |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

***

## start

Start a stopped instance.

```bash theme={null}
nscale instances start --id <instance-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Instance ID                                    |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm start                    |

***

## stop

Stop a running instance.

```bash theme={null}
nscale instances stop --id <instance-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Instance ID                                    |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm stop                     |

***

## reboot

Reboot an instance. Use `--hard` for a hard reboot.

```bash theme={null}
nscale instances reboot --id <instance-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Instance ID                                    |
| `--org string` | Organization ID                                |
| `--hard`       | Use hard reboot                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm reboot                   |

***

## snapshot

Create an image snapshot from an instance. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale instances snapshot --id <instance-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Instance ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm snapshot</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale instances snapshot --id <instance-id> --file snapshot.json
nscale instances snapshot --id <instance-id> --stdin < snapshot.json
cat snapshot.json | nscale instances snapshot --id <instance-id> --stdin
```

***

## ssh

Open an interactive SSH session to an instance using the system SSH client.

```bash theme={null}
nscale instances ssh --id <instance-id> [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 --id <instance-id>
nscale instances ssh --org <org-id>
nscale instances ssh --id <instance-id> --ssh-user ubuntu
nscale instances ssh --id <instance-id> -l ubuntu
nscale instances ssh -l ubuntu
nscale instances ssh --id <instance-id> -- -L 8443:127.0.0.1:443
```

***

## sshkey

Get the SSH key for an instance.

```bash theme={null}
nscale instances sshkey --id <instance-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Instance ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## consoleoutput

Retrieve the serial console output of an instance.

```bash theme={null}
nscale instances consoleoutput --id <instance-id> --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Instance ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--length int</code></td><td>Output length in bytes (0 uses API default)</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## consolesession

Get a VNC console session URL for an instance.

```bash theme={null}
nscale instances consolesession --id <instance-id> --org <org-id>
```

### Flags

| Flag           | Description     |
| -------------- | --------------- |
| `--id string`  | Instance ID     |
| `--org string` | Organization ID |

***

## Related

<CardGroup>
  <Card title="Instances (Console)" icon="browser" href="/docs/compute/create-new-instances">
    Create and manage instances via the Console UI.
  </Card>

  <Card title="Custom Images" icon="image" href="/docs/storage/custom-images">
    Upload and use custom OS images for instances.
  </Card>
</CardGroup>


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

Once authenticated, your credentials are saved and reused automatically for subsequent commands.

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=<your-service-token>
nscale instances list --org <org-id>
```

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 `--user` flag:

```bash theme={null}
nscale logout --user <username>
```


# Networks
Source: https://docs.nscale.com/docs/cli/networks

Manage VPC networks.

**Aliases:** `networks`, `net`, `vpc`

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale networks list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific network.

```bash theme={null}
nscale networks get --id <network-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Network ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new VPC network. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale networks create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

```bash theme={null}
nscale networks update --id <network-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Network ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale networks update --id <network-id> --file network.json
nscale networks update --id <network-id> --stdin < network.json
cat network.json | nscale networks update --id <network-id> --stdin
```

***

## delete

Delete an existing network.

```bash theme={null}
nscale networks delete --id <network-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Network ID                                     |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

***

## Related

<CardGroup>
  <Card title="VPC Networks (Console)" icon="browser" href="/docs/network/vpc-networks">
    Create and manage VPC networks via the Console UI.
  </Card>
</CardGroup>


# Object storage
Source: https://docs.nscale.com/docs/cli/object-storage

Manage object storage endpoints, identity policies, and access keys.

**Aliases:** `object-storage`, `os`

## Subcommands

* [list](#list) — List object storage endpoints
* [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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale object-storage list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific object storage endpoint.

```bash theme={null}
nscale object-storage get --id <endpoint-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new object storage endpoint. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale object-storage create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### 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 --id <endpoint-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Object storage endpoint ID                     |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale object-storage delete --id <endpoint-id> --org <org-id> --yes
```

***

## list-policies

List identity policies for an object storage endpoint.

```bash theme={null}
nscale object-storage list-policies --id <endpoint-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## 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 --id <endpoint-id> --name <policy-name> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--name string</code></td><td>Identity policy name</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## 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 --id <endpoint-id> --name <policy-name> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--name string</code></td><td>Identity policy name</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON policy document file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale object-storage create-policy --id <endpoint-id> --name read-only --file policy.json
cat policy.json | nscale object-storage create-policy --id <endpoint-id> --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 --id <endpoint-id> --name <policy-name> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--name string</code></td><td>Identity policy name</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON policy document file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale object-storage update-policy --id <endpoint-id> --name read-only --file policy.json
cat policy.json | nscale object-storage update-policy --id <endpoint-id> --name read-only --stdin
```

***

## delete-policy

Delete an identity policy from an object storage endpoint.

```bash theme={null}
nscale object-storage delete-policy --id <endpoint-id> --name <policy-name> --org <org-id> [flags]
```

### Flags

| Flag            | Description                                    |
| --------------- | ---------------------------------------------- |
| `--id string`   | Object storage endpoint ID                     |
| `--name string` | Identity policy name                           |
| `--org string`  | Organization ID                                |
| `--dry-run`     | Preview the request payload without persisting |
| `-y, --yes`     | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale object-storage delete-policy --id <endpoint-id> --name read-only --org <org-id> --yes
```

***

## list-access-keys

List access keys for an object storage endpoint.

```bash theme={null}
nscale object-storage list-access-keys --id <endpoint-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## 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 --id <endpoint-id> --name <key-name> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Object storage endpoint ID</td></tr>
    <tr><td><code>--name string</code></td><td>Access key name</td></tr>
    <tr><td><code>--policy string</code></td><td>Identity policy name to associate with the access key</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale object-storage create-access-key --id <endpoint-id> --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 --id <endpoint-id> --access-key-id <access-key-id> --org <org-id> [flags]
```

### Flags

| Flag                     | Description                                    |
| ------------------------ | ---------------------------------------------- |
| `--id string`            | Object storage endpoint ID                     |
| `--access-key-id string` | Access key ID                                  |
| `--org string`           | Organization ID                                |
| `--dry-run`              | Preview the request payload without persisting |
| `-y, --yes`              | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale object-storage delete-access-key --id <endpoint-id> --access-key-id <access-key-id> --org <org-id> --yes
```

***

## Related

<CardGroup>
  <Card title="Object Storage (Console)" icon="browser" href="/docs/storage/object-storage">
    Create and manage object storage via the Console UI.
  </Card>
</CardGroup>


# 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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

## Global flags

These flags are available on every command:

| Flag                | Description                                                                  |
| ------------------- | ---------------------------------------------------------------------------- |
| `--ci`              | Indicates the CLI is running in a CI environment (also set via `CI` env var) |
| `--context string`  | Specify the context to use                                                   |
| `-u, --user string` | Specify the user credentials to use (default: `"default"`)                   |
| `-h, --help`        | Show help for any command                                                    |

## Environment variables

| Variable               | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| `CI`                   | Override the `--ci` flag                                                        |
| `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 --name my-context --org <org-id>

# Switch to a context
nscale contexts use my-context

# List all contexts
nscale contexts list
```

## Output formats

Most `list` and `get` commands support a `--json` flag for machine-readable output:

```bash theme={null}
nscale instances list --org <org-id> --json
```

`--json` and `-q` are mutually exclusive — pick whichever fits your downstream tooling.

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

For example, `list` commands will present an organization picker if `--org` is not provided:

<img alt="Instances list with interactive org picker" />

`create` commands will prompt for each required field when no `--file` or `--stdin` input is given:

<img alt="Instances create with interactive field prompts" />

To suppress interactive prompts (e.g. in scripts), pass `--ci` or set the `CI` environment variable.

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

| Command                                        | Description                                                |
| ---------------------------------------------- | ---------------------------------------------------------- |
| [`contexts`](/docs/cli/contexts)               | Manage CLI contexts                                        |
| [`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                                   |
| [`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 (feature-gated)                      |
| [`projects`](/docs/cli/projects)               | Manage projects                                            |
| [`regions`](/docs/cli/regions)                 | List available regions                                     |
| [`reservations`](/docs/cli/reservations)       | Manage GPU reservations (feature-gated)                    |
| [`securitygroups`](/docs/cli/securitygroups)   | Manage security groups                                     |
| [`serviceaccounts`](/docs/cli/serviceaccounts) | Manage service accounts                                    |
| [`ssh-cas`](/docs/cli/ssh-cas)                 | Manage SSH certificate authorities                         |
| [`version`](/docs/cli/version)                 | Display the CLI version                                    |


# Placements
Source: https://docs.nscale.com/docs/cli/placements

Manage GPU placements.

**Aliases:** `placements`, `placement`

<Note>
  Placements are gated behind a feature flag. The `placements` command is hidden and unavailable unless the feature is enabled for your organization.
</Note>

## Subcommands

* [list](#list) — List placements
* [get](#get) — Get placement details
* [create](#create) — Create a new placement
* [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

***

## list

List placements, optionally filtered by organization, project, or reservation.

```bash theme={null}
nscale placements list [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--reservation string</code></td><td>Reservation ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale placements list --org <org-id> --reservation <reservation-id>
```

***

## get

Get details for a specific placement.

```bash theme={null}
nscale placements get --id <placement-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Placement ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new placement. Accepts input from a JSON file or stdin, with an optional cloud-init configuration for the placed servers.

```bash theme={null}
nscale placements create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--cloud-init-path string</code></td><td>Path to a cloud-init YAML file</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

***

## delete

Delete an existing placement.

```bash theme={null}
nscale placements delete --id <placement-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Placement ID                                   |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale placements delete --id <placement-id> --org <org-id> --yes
```

***

## servers

List the servers in a placement.

```bash theme={null}
nscale placements servers --id <placement-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Placement ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## server-reboot

Reboot an existing server in a placement. Use `--hard` for a hard reboot.

```bash theme={null}
nscale placements server-reboot --id <placement-id> --server <server-id> --org <org-id> [flags]
```

### Flags

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `--id string`     | Placement ID                                   |
| `--server string` | Server ID                                      |
| `--org string`    | Organization ID                                |
| `--hard`          | Use hard reboot                                |
| `--dry-run`       | Preview the request payload without persisting |
| `-y, --yes`       | Automatically confirm reboot                   |

### Example

```bash theme={null}
nscale placements server-reboot --id <placement-id> --server <server-id> --org <org-id> --yes
```

***

## server-stop

Stop an existing server in a placement.

```bash theme={null}
nscale placements server-stop --id <placement-id> --server <server-id> --org <org-id> [flags]
```

### Flags

| Flag              | Description                                    |
| ----------------- | ---------------------------------------------- |
| `--id string`     | Placement ID                                   |
| `--server string` | Server ID                                      |
| `--org string`    | Organization ID                                |
| `--dry-run`       | Preview the request payload without persisting |
| `-y, --yes`       | Automatically confirm stop                     |

### Example

```bash theme={null}
nscale placements server-stop --id <placement-id> --server <server-id> --org <org-id> --yes
```

***

## Related

<CardGroup>
  <Card title="Reservations" icon="calendar-check" href="/docs/cli/reservations">
    Reserve GPU capacity and check available reservation units.
  </Card>
</CardGroup>


# Projects
Source: https://docs.nscale.com/docs/cli/projects

Manage projects within an organization.

Projects help organize resources within an organization.

## 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 <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## get

Get details for a specific project.

```bash theme={null}
nscale projects get --id <project-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Project ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new project in the specified organization. Supports interactive mode or JSON input.

```bash theme={null}
nscale projects create --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale projects create --org <org-id> --file project.json
nscale projects create --org <org-id> --stdin < project.json
cat project.json | nscale projects create --org <org-id> --stdin
# Interactive mode
nscale projects create
```

***

## update

Update an existing project.

```bash theme={null}
nscale projects update --org <org-id> --id <project-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Project ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale projects update --org <org-id> --id <project-id> --file project.json
nscale projects update --org <org-id> --id <project-id> --stdin < project.json
cat project.json | nscale projects update --org <org-id> --id <project-id> --stdin
```

***

## delete

Delete an existing project.

```bash theme={null}
nscale projects delete --org <org-id> --id <project-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Project ID                                     |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request 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.

## 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 "$id" --yes
done
```

## Reshape the output

Filters can transform the response into a new structure. 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"}
]
```

## 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. Each filter's results are zipped column-wise (space-separated per line), which is handy for tabular output:

```bash theme={null}
nscale instances list -q ".[].metadata.id" -q ".[].metadata.name"
```

```text theme={null}
bed4405e-bd2f-491a-a515-3612e6d4230f instance-1
f1facb11-d3de-417f-92c0-dc582cea4c80 instance-2
```

Iteration stops at the shortest stream; a warning is emitted on stderr when a later filter runs out first.


# 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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale regions list --org <org-id> --json
```


# Reservations
Source: https://docs.nscale.com/docs/cli/reservations

Manage GPU reservations.

**Aliases:** `reservations`, `reservation`, `res`

<Note>
  Reservations are gated behind a feature flag. The `reservations` command is hidden and unavailable unless the feature is enabled for your organization.
</Note>

## Subcommands

* [list](#list) — List reservations
* [get](#get) — Get reservation details
* [capacity](#capacity) — List available reservation units
* [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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale reservations list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific reservation.

```bash theme={null}
nscale reservations get --id <reservation-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Reservation ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>
    <tr><td><code>--accelerator string</code></td><td>Accelerator model, for example <code>GB300</code></td></tr>
    <tr><td><code>--unit string</code></td><td>Reservation unit, for example <code>NVL72</code></td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale reservations capacity --region <region-id> --accelerator GB300
```

***

## create

Create a new reservation. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale reservations create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### 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 --id <reservation-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Reservation ID                                 |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

### Example

```bash theme={null}
nscale reservations delete --id <reservation-id> --org <org-id> --yes
```

***

## Related

<CardGroup>
  <Card title="Placements" icon="server" href="/docs/cli/placements">
    Place workloads onto reserved capacity and manage their servers.
  </Card>
</CardGroup>


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

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>
    <tr><td><code>--network string</code></td><td>Network ID</td></tr>
    <tr><td><code>--region string</code></td><td>Region ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale securitygroups list --org <org-id> --region <region-id>
```

***

## get

Get details for a specific security group.

```bash theme={null}
nscale securitygroups get --id <sg-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Security group ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new security group. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale securitygroups create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

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

```bash theme={null}
nscale securitygroups update --id <sg-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Security group ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale securitygroups update --id <sg-id> --file securitygroup.json
nscale securitygroups update --id <sg-id> --stdin < securitygroup.json
cat securitygroup.json | nscale securitygroups update --id <sg-id> --stdin
```

***

## delete

Delete an existing security group.

```bash theme={null}
nscale securitygroups delete --id <sg-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Security group ID                              |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

***

## Related

<CardGroup>
  <Card title="Instances (Console)" icon="browser" href="/docs/compute/create-new-instances">
    Security groups are configured during instance creation.
  </Card>
</CardGroup>


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

## 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 <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## get

Get details for a specific service account.

```bash theme={null}
nscale serviceaccounts get --id <sa-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Service account ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new service account. Supports interactive mode or JSON input.

```bash theme={null}
nscale serviceaccounts create --org <org-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale serviceaccounts create --org <org-id> --file serviceaccount.json
nscale serviceaccounts create --org <org-id> --stdin < serviceaccount.json
cat serviceaccount.json | nscale serviceaccounts create --org <org-id> --stdin
# Interactive mode
nscale serviceaccounts create
```

***

## update

Update an existing service account.

```bash theme={null}
nscale serviceaccounts update --org <org-id> --id <sa-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Service account ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm update</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Examples

```bash theme={null}
nscale serviceaccounts update --org <org-id> --id <sa-id> --file serviceaccount.json
nscale serviceaccounts update --org <org-id> --id <sa-id> --stdin < serviceaccount.json
cat serviceaccount.json | nscale serviceaccounts update --org <org-id> --id <sa-id> --stdin
```

***

## 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 <org-id> --id <sa-id> [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>Service account ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm token rotation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale serviceaccounts rotate --org <org-id> --id <sa-id> --yes
```

***

## delete

Delete an existing service account.

```bash theme={null}
nscale serviceaccounts delete --org <org-id> --id <sa-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | Service account ID                             |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

***

## Related

<CardGroup>
  <Card title="Service Tokens (Console)" icon="browser" href="/docs/manage/service-tokens">
    Generate and manage service tokens via the Console UI.
  </Card>
</CardGroup>


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

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

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>--project string</code></td><td>Project ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### Example

```bash theme={null}
nscale ssh-cas list --org <org-id>
```

***

## get

Get details for a specific SSH certificate authority.

```bash theme={null}
nscale ssh-cas get --id <ssh-ca-id> --org <org-id>
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--id string</code></td><td>SSH certificate authority ID</td></tr>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

***

## create

Create a new SSH certificate authority. Accepts input from a JSON file or stdin.

```bash theme={null}
nscale ssh-cas create [flags]
```

### Flags

<table>
  <thead><tr><th>Flag</th><th>Description</th></tr></thead>

  <tbody>
    <tr><td><code>--org string</code></td><td>Organization ID</td></tr>
    <tr><td><code>-f, --file string</code></td><td>Path to a JSON file</td></tr>
    <tr><td><code>--stdin</code></td><td>Read JSON from standard input</td></tr>
    <tr><td><code>--dry-run</code></td><td>Preview the request payload without persisting</td></tr>
    <tr><td><code>-y, --yes</code></td><td>Automatically confirm creation</td></tr>

    <tr>
      <td><code>--json</code></td>
      <td>Emit the full JSON payload (mutually exclusive with <code>-q</code>)</td>
    </tr>

    <tr>
      <td><code>-q, --query stringArray</code></td>
      <td>jq filter for value extraction (see <a href="/docs/cli/query-output">Query output with <code>-q</code></a>)</td>
    </tr>
  </tbody>
</table>

### 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 --id <ssh-ca-id> --org <org-id> [flags]
```

### Flags

| Flag           | Description                                    |
| -------------- | ---------------------------------------------- |
| `--id string`  | SSH certificate authority ID                   |
| `--org string` | Organization ID                                |
| `--dry-run`    | Preview the request payload without persisting |
| `-y, --yes`    | Automatically confirm deletion                 |

***

## Related

<CardGroup>
  <Card title="Instances" icon="server" href="/docs/cli/instances">
    Bind a certificate authority when creating an instance with <code>--ssh-ca-id</code>.
  </Card>
</CardGroup>


# 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 are deprecated.** The cluster API has been 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).
</Warning>

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

<img alt="image.png" title="image.png" />

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

<img alt="compute_cluster_selection.png" title="compute_cluster_selection.png" />

Select **Create new resource**.

<img alt="cluster_new.png" />

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.

  <img alt="cluster_set_up_1.png" />
* Select the desired **node type**.

  <img alt="cluster_set_up_2.png" />
* 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).

  <img alt="cluster_set_up_3.png" />
* Optionally, you can provide a **cloud-init configuration** to run custom setup scripts during the first boot of each node.

  <img alt="cluster_set_up_4-cloud_init.png" />
* 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.

  <img alt="cluster_set_up_5.png" />

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

<img alt="htop.png" />

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

<img alt="Screenshot from 2025-10-06 11-18-40.png" />

Once you are in the cluster, use the **“+ Add Workload Pool”** button to start the new pool configuration.

<img alt="Screenshot from 2025-10-06 11-19-59.png" />

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.

<img alt="Screenshot from 2025-10-06 13-43-07.png" />

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

<img alt="Screenshot from 2025-10-06 13-50-39.png" />

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.

<img alt="Screenshot from 2025-10-06 13-51-56.png" />

The pool should now show that only 3 Virtual Machines remain active out of the 3 originally in the pool.

<img alt="Screenshot from 2025-10-06 13-52-31.png" />

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

<img alt="Screenshot from 2025-10-06 13-49-11.png" />

To confirm the delete operation, enter the name of the pool in the confirmation panel.

<img alt="Screenshot from 2025-10-06 13-53-35.png" />

The selected pool is not part of the cluster.

<img alt="Screenshot from 2025-10-06 13-54-33.png" />

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

<img alt="Screenshot from 2025-10-06 13-55-08.png" />

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.

<img alt="Screenshot from 2025-10-06 13-56-15.png" />


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

## 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**.
</Warning>

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

<Info>
  **Naming rules:** Instance names must be **unique** and contain only **alphanumeric characters and hyphens**.
</Info>

## Instance lifecycle

Instances move through the following states:

| State            | Description                                                     |
| ---------------- | --------------------------------------------------------------- |
| **Provisioning** | The instance is being created and resources are being allocated |
| **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.
</Warning>

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

<img alt="Instance" />

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

<img alt="New Instance Flow 1 1" />

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

<Info>
  **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 platform validates all of this and rejects incompatible combinations.
</Info>

<Accordion title="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.
</Accordion>

<img alt="New Instance Flow 2" />

6. Review the configuration summary and click **Create instance**

* You should be forwarded to the **instance details page** while provisioning is in progress
* From the details page, you can monitor status and **download the SSH key** to access the instance via terminal

<img alt="Instances Details View" />

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

<CardGroup>
  <Card title="CLI: Instances" icon="square-terminal" href="/docs/cli/instances">
    Manage instances from the command line.
  </Card>

  <Card title="CLI: Security Groups" icon="square-terminal" href="/docs/cli/securitygroups">
    Manage security groups from the command line.
  </Card>
</CardGroup>


# Placements
Source: https://docs.nscale.com/docs/compute/placements

Schedule bare-metal GB300 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, a [VPC network](/docs/network/vpc-networks) in the reservation's region, and at least one [security group](/docs/network/security-groups) in that VPC.
</Note>

## 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 GB300 NVL72 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. For GB300 NVL72, **1 host = 1 compute tray** within an NVLink domain.
* **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.
</Note>

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

<Info>
  **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.
</Info>

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

<Steps>
  <Step title="Set up your placement">
    Give the placement a name under **Placement name**. Names must be unique and can only contain lowercase alphanumeric characters and dashes.

    The **Parent reservation** is fixed—the placement is scoped to the reservation you launched the flow from and can't be changed.
  </Step>

  <Step title="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.
    </Warning>

    <img alt="Configure your placement" />
  </Step>

  <Step title="Configure each host">
    Choose what every host in the placement runs:

    * **Security groups** — attach one or more security groups from the selected VPC to control network traffic.
    * **OS Image** — select the operating system and default packages installed on every node.
  </Step>

  <Step title="Choose an SSH key">
    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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

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

<img alt="Placement detail" />

## Manage servers

The **Servers** tab lists every server the placement launched. Each server reports a provisioning status:

| Status             | Description                    |
| ------------------ | ------------------------------ |
| **Provisioning**   | The server is being created    |
| **Provisioned**    | The server is ready for use    |
| **Error**          | The server failed to provision |
| **Deprovisioning** | The server is being torn down  |

**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.
</Note>

## Delete a placement

Deleting a placement stops and removes all of its servers and releases their hosts back to the reservation.

<Steps>
  <Step title="Open the placement">
    Go to the placement's detail view, open the actions menu, and choose **Delete Placement**.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

<Tip>
  Once a placement is deleted and its hosts are released, that capacity is free for a new placement in the same reservation.
</Tip>

## Next steps

* Review [reservations](/docs/compute/reservations) and how capacity is reserved.
* 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 GB300 NVL72 GPU capacity for a project, then launch workloads onto it with placements.

A reservation ring-fences one or more contiguous **NVLink domains** of GB300 NVL72 capacity for a single project in a region. The capacity is exclusively yours for the life of the reservation—no noisy neighbors, no rescheduling—and it is the foundation you build [placements](/docs/compute/placements) on top of to launch servers.

<Note>
  **GB300 NVL72 is reserved capacity.** It is not available through the standard [instance creation](/docs/compute/create-new-instances) flow. To run on GB300, you reserve capacity first, then create a [placement](/docs/compute/placements) inside the reservation.
</Note>

## Summary

This page walks you through working with **reservations** in the Nscale Console—the capacity model for GB300 NVL72 and future 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 GB300 NVL72
* 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. For GB300, **1 unit = 1 NVLink domain = 18 hosts**. GB300 NVL72 is the only unit available today.        |
| **Reservation**      | One or more contiguous units, ring-fenced for a project in a region. Exclusive and immutable.                                            |
| **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 (one compute tray) 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 racks. The total number of servers across all placements can never exceed the reservation's capacity.

<Info>
  **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). For GB300 NVL72, one unit corresponds to one full NVLink domain of 18 hosts.
</Info>

## Availability

Reservations are the capacity model for **bare-metal GPU regions**, starting with GB300 NVL72. 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.
* **Immutable.** A reservation can't be edited after creation. You can add or remove placements, or delete the reservation entirely, but you can't resize it in place.

<Info>
  **Naming rules:** Reservation names must be **unique** and can only contain **lowercase alphanumeric characters and dashes**.
</Info>

## Reservation lifecycle

A reservation moves through the following provisioning states:

| State              | Description                                                                             |
| ------------------ | --------------------------------------------------------------------------------------- |
| **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—for example, the requested contiguous capacity could not be claimed |
| **Deprovisioning** | The reservation is being torn down following a delete                                   |

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

<Steps>
  <Step title="Open the create flow">
    In the Console, open your project, then go to **Compute → Reservations** and click **Reserve Capacity**.

    <img alt="Reservations list view" />
  </Step>

  <Step title="Set up your reservation">
    Give the reservation a name under **Reservation Name**. Names must be unique and can only contain lowercase alphanumeric characters and dashes.

    Click **Configuration** to continue.
  </Step>

  <Step title="Configure your reservation">
    Choose how much capacity to reserve and where:

    * **Flavour** is fixed to **GB300 NVL72**—the only flavour supported today.
    * **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.
    </Warning>

    Click **Review your reservation** to continue.

    <img alt="Configure your reservation" />
  </Step>

  <Step title="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 edited after creation**.

    Click **Reserve Capacity** to submit. The reservation begins provisioning and appears in your reservations list.
  </Step>
</Steps>

<Tip>
  Capacity is claimed asynchronously. A reservation starts in **Provisioning** and moves to **Provisioned** once all its NVLink domains are ring-fenced—typically around a minute. You can create placements as soon as it is provisioned.
</Tip>

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

<img alt="Reservation detail overview" />

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

<Steps>
  <Step title="Open the reservation">
    Go to the reservation's detail view and review its placements—deleting the reservation will remove all of them.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Next steps

* [Create a placement](/docs/compute/placements) to launch servers from your reservation.
* 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.
</Note>

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

## Step 2: Register the CA with Nscale

Register the CA public key using the API. The CA is scoped to an organization and project.

<CodeGroup>
  ```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": "<org-id>",
        "projectId": "<project-id>",
        "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": "<org-id>",
              "projectId": "<project-id>",
              "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": "<org-id>",
  			"projectId":      "<project-id>",
  			"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: "<org-id>",
          projectId: "<project-id>",
          publicKey: pubKey,
        },
      }),
    }
  );

  console.log(await response.json());
  ```
</CodeGroup>

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": "<org-id>",
      "projectId": "<project-id>",
      "regionId": "<region-id>",
      "flavorId": "<flavor-id>",
      "imageId": "<image-id>",
      "networkId": "<network-id>",
      "sshCertificateAuthorityId": "<ssh-ca-id>"
    }
  }'
```

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@<instance-ip>
```

<Info>
  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).
</Info>

## 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/<ssh-ca-id>" \
  -H "Authorization: Bearer $NSCALE_TOKEN"
```

### Delete a CA

```bash theme={null}
curl -X DELETE "https://region.nks.europe-west4.nscale.com/api/v2/sshcertificateauthorities/<ssh-ca-id>" \
  -H "Authorization: Bearer $NSCALE_TOKEN"
```

<Warning>
  You cannot delete an SSH CA that is referenced by active instances. Remove or update the instances first.
</Warning>

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

<CardGroup>
  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Create instances that trust your SSH CA
  </Card>

  <Card title="Security groups" icon="shield" href="/docs/network/security-groups">
    Allow SSH traffic to your instances
  </Card>

  <Card title="Service tokens" icon="key" href="/docs/manage/service-tokens">
    Create API tokens for programmatic access
  </Card>

  <Card title="API reference" icon="code" href="/api-reference">
    Full API documentation for SSH CAs
  </Card>
</CardGroup>


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

<img alt="Basic Rag Figure Pn" />

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

<img alt="Offline Document Indexing Pn" />

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.

<img alt="Col Pali Retrieval Pn" />

[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)
```

<Card title="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.
</Card>

## 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! 🚀


# 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 <Icon icon="arrow-up-right" />](/docs/manage/service-tokens)
</Warning>

## 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": "<an error type>",
    "param": "<optional, additional details about the error>",
    "code": "<a specific error code>"
  }
}
```

<Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
  If you encounter any of these errors and need further assistance, please Contact Support.
</Card>


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

<img />

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

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/docs/getting-started/quickstart">
    Learn how to get started with Nscale
  </Card>

  <Card title="Serverless Inference" icon="cloud" href="/docs/ai-services/models">
    Get started with Serverless Inference
  </Card>

  <Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
    Get help from our support team
  </Card>

  <Card title="Get GPU Clusters" icon="server" href="https://www.nscale.com/contact/sales">
    Slurm, Kubernetes and Bare metal clusters
  </Card>
</CardGroup>

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

<Steps>
  <Step title="Create an account">
    Head to [console.nscale.com](https://console.nscale.com/login) and create an account
  </Step>

  <Step title="Add credit to your account">
    From the dashboard, add a minimum of \$5 of credit to start using our service
  </Step>

  <Step title="Call your first endpoint">
    Call the [inference endpoint](/api-reference/inference/create-chat-completion) with your Service token
  </Step>
</Steps>

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.

<CardGroup>
  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Create GPU and CPU virtual machines with SSH access
  </Card>

  <Card title="VPC Networks" icon="earth-europe" href="/docs/network/vpc-networks">
    Isolated private networks for your resources
  </Card>

  <Card title="Filesystem" icon="files" href="/docs/storage/file-storage">
    Shared persistent NFS storage for instances and clusters
  </Card>

  <Card title="Managed Kubernetes" icon="cloud" href="/docs/compute/managed-kubernetes">
    Provision isolated Kubernetes clusters for container workloads
  </Card>

  <Card title="Security Groups" icon="shield" href="/docs/network/security-groups">
    Firewall rules controlling inbound and outbound traffic
  </Card>

  <Card title="Terraform Provider" icon="cube" href="/docs/manage/terraform">
    Manage Nscale infrastructure as code
  </Card>
</CardGroup>

## Get help

<Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
  For technical issues or assistance with our platform.
</Card>


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

<img />

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

<img />

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

<img />

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

## Getting Assistance from Nscale Support

<CardGroup>
  <Card title="Nscale Cloud Customers" icon="cloud">
    For assistance with services on the [Cloud Console](https://console.nscale.com/), send an email to [helpdesk@nscale.com](mailto:helpdesk@nscale.com)
  </Card>

  <Card title="Nscale Private Cloud Customers" icon="building">
    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.
  </Card>
</CardGroup>

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

<Card title="Nscale Ticketing Service" icon="ticket" href="https://nscale.atlassian.net/servicedesk/customer/portals">
  [https://nscale.atlassian.net/servicedesk/customer/portals](https://nscale.atlassian.net/servicedesk/customer/portals)
</Card>

### Support Portal - First-time Login

An account is created for you during onboarding. Follow these steps to sign in for the first time.

<Steps>
  <Step title="Navigate to the portal">
    Open the [Nscale Ticketing Service](https://nscale.atlassian.net/servicedesk/customer/portals), or use the link in your invitation email.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Check your email">
    You'll receive a password-reset email. Only act on it if **you** just requested the reset.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Sign in">
    Enter your email address and new password to sign in.
  </Step>
</Steps>

<Note>
  If you need further assistance with this process, contact your Nscale Account Manager or email [helpdesk@nscale.com](mailto:helpdesk@nscale.com).
</Note>

## Add a Customer to Your Service Space

Both admins and agents can add customers to a service space.

<Steps>
  <Step title="Open Customers">
    From your service space, select **Customers**.
  </Step>

  <Step title="Start adding customers">
    On the **Customers** tab, select **Add customers**.
  </Step>

  <Step title="Enter customer details">
    Enter the customer's username or email address. To add several customers at once, separate the entries with commas.
  </Step>
</Steps>

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

<Card title="Contact Escalations Team" icon="phone" href="mailto:escalations@nscale.com">
  For urgent escalations, please contact our escalations team at [escalations@nscale.com](mailto:escalations@nscale.com)
</Card>


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

<details>
  <summary>Alternative: run NVDebug from a jumphost</summary>

  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
  ```
</details>

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 <swp interface number> detail`, `net show interface pluggables`, and `sudo l1-show <swp interface number>`. 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 <lid> -p <physical_port_no> -c` output. Note whether the port was isolated in UFM and whether `perfquery -x <lid> <logical_port>` 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 CET          | 15 Minutes                | 4 hrs                 |
| P2 (High)     | 24x7, 365 days             | 0900 – 1700 CET        | 0900 – 1700 CET          | 1 Hour                    | 24 hrs                |
| P3 (Medium)   | 24x7, 365 days             | 0900 – 1700 CET        | 0900 – 1700 CET          | 1 Hour                    | 1 week                |
| P4 (Low)      | 24x7, 365 days             | 0900 – 1700 CET        | 0900 – 1700 CET          | 1 Hour                    | 1 month               |
| Request       | 24x7, 365 days             | 0900 – 1700 CET        | 0900 – 1700 CET          | 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.

<AccordionGroup>
  <Accordion title="P1 (Critical)" icon="circle-exclamation">
    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.
  </Accordion>

  <Accordion title="P2 (High)" icon="triangle-exclamation">
    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.
  </Accordion>

  <Accordion title="P3 (Medium)" icon="circle-info">
    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.
  </Accordion>

  <Accordion title="P4 (Low)" icon="circle">
    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.
  </Accordion>

  <Accordion title="Requests" icon="message-question">
    General usage enquiries, documentation errors, product feature requests, and requests for assistance.
  </Accordion>
</AccordionGroup>

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

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





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

* Upon successful transaction, the credits will be added to your account balance.

**Minimum and maximum purchase limits**:

<Note>
  The platform supports credit purchases from \$5 up to a maximum of \$10,000 per transaction.
</Note>

**Credit expiry**:

Purchased credits expire **3 years** after the date of purchase. You can view the expiry date for each credit commit in the **Credit** tab under **Usage & Billing**. Startup credits have a separate expiry policy.

## **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.&#x20;

## **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
</Note>

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

<Card title="Get support" icon="headset" href="mailto:helpdesk@nscale.com">
  Need help with billing? Reach out to our support team to get help.
</Card>


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

<img />


# 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, clusters)
* 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

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.
2. Create a new project and give it a clear, descriptive name (for example, `team-ml-prod` or `payments-staging`).
3. 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 and adjust basic details such as the project name.

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

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

<Steps>
  <Step title="Log in">
    Log in to the [Nscale Ticketing Service](https://nscale.atlassian.net/servicedesk/customer/portals)
  </Step>

  <Step title="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`
  </Step>

  <Step title="Submit your ticket">
    Submit the ticket to Nscale Support. We will use the information and get back to you as soon as possible.
  </Step>
</Steps>


# 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).
</Note>

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

<Info>
  **Roles are predefined.** You assign existing roles to groups; you don't create custom roles in the Console.
</Info>

## Roles

Nscale provides the following roles. Roles apply either across the whole organization or only within the projects a group is assigned to.

| Role              | Scope                    | What it allows                                                                                                                   |
| ----------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Administrator** | Organization             | Full control of the organization—manage members, groups, projects, and all resources.                                            |
| **Auditor**       | Organization             | Read-only access to everything in the organization.                                                                              |
| **User**          | Organization and project | Read access at the organization level, plus the ability to create and manage resources in the projects the group is assigned to. |
| **Reader**        | Project                  | Read-only access within the projects the group is assigned to.                                                                   |

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

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

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 specialised role (for example, a role for a specific service) 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 specialised 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

<Steps>
  <Step title="Open the People tab">
    Go to **Settings → People** and find the **Organization Members** card.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Send the invite">
    Click **Invite**. Each invited member appears with a **Pending** status until they join, after which they become **Active**.
  </Step>
</Steps>

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

<Steps>
  <Step title="Open the People tab">
    Go to **Settings → People** and find the **Organization Groups** card.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Save the group">
    Click **Create group**. The group appears in the Organization Groups list.
  </Step>
</Steps>

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

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

<img />

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

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

<CardGroup>
  <Card title="CLI: Service Accounts" icon="square-terminal" href="/docs/cli/serviceaccounts">
    Manage service accounts from the command line.
  </Card>
</CardGroup>


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

## 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"
    }
  }
}
```

<Info>
  **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.
</Info>

## 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="<your-region-id>"
export NSCALE_ORGANIZATION_ID="<your-organization-id>"
export NSCALE_PROJECT_ID="<your-project-id>"
export NSCALE_SERVICE_TOKEN="<your-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       = "<your-region-id>"
  # organization_id = "<your-organization-id>"
  # project_id      = "<your-project-id>"
  # service_token   = "<your-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.
</Warning>

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

<CardGroup>
  <Card title="Service Tokens" icon="key" href="/docs/manage/service-tokens">
    Generate the token used to authenticate the Terraform provider
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/instances/list-instances">
    The underlying API that the Terraform provider calls
  </Card>

  <Card title="Terraform Registry" icon="cube" href="https://registry.terraform.io/providers/nscaledev/nscale/latest/docs">
    Full provider documentation and resource reference
  </Card>

  <Card title="GitHub Examples" icon="github" href="https://github.com/nscaledev/terraform-provider-nscale/tree/main/examples">
    Example Terraform configurations
  </Card>
</CardGroup>


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

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

<Info>
  **Default behaviour:** With no rules defined, all inbound and outbound traffic is **denied**. You must add rules to allow the traffic your workloads need.
</Info>

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

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

## 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 four 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
* **Settings** — rename the security group or delete it

### Managing security groups

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 **rename** a security group:

1. Open the security group detail page and go to the **Settings** tab
2. Edit the name and save

To **delete** a security group:

1. Ensure no resources are attached to it (check the **Instances** tab)
2. Go to the **Settings** tab and click **Delete**, or use the actions menu from the list page

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

<CardGroup>
  <Card title="VPC Networks" icon="earth-europe" href="/docs/network/vpc-networks">
    Create the VPC your security group belongs to
  </Card>

  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Attach security groups when creating instances
  </Card>

  <Card title="Terraform Provider" icon="cube" href="/docs/manage/terraform">
    Manage security groups as infrastructure as code
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/security-groups/list-security-groups">
    Manage security groups programmatically via the Networking and Storage API
  </Card>
</CardGroup>


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

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

<Info>
  VPCs are project-scoped — you can create and use multiple VPCs within the same project.
</Info>

<Warning>
  Your VPC's workload subnet must have at least a **/24 CIDR block** (256 IP addresses). This is the minimum for any network.
</Warning>

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

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

<img alt="VPC list with the Create VPC button" />

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

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

   <img alt="VPC creation — Details step" />

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

   <Info>
     This IP allocation is permanent. To change it, you'd need to delete this VPC and reprovision all your machines.
   </Info>

   <img alt="VPC creation — Network Configuration step" />

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

   <img alt="VPC creation — Add Routes step" />

10. Click **Create VPC**.

11. Verify the result — the new VPC appears in the **VPC list** for the selected project and begins provisioning.

<img alt="VPC list showing the new VPC" />

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

<img alt="VPC creation — Advanced Configuration with IP reservations" />

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

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

<CardGroup>
  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Create compute instances inside your VPC
  </Card>

  <Card title="Security Groups" icon="shield" href="/docs/network/security-groups">
    Control traffic rules for resources in your VPC
  </Card>

  <Card title="Filesystem" icon="files" href="/docs/storage/file-storage">
    Attach shared persistent storage within your VPC
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/networks/list-networks">
    Manage VPCs programmatically via the Networking and Storage API
  </Card>
</CardGroup>


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

## Availability

This feature is currently available for the Reserved cloud service environment.

<Info>
  **Supported formats:** Only **QCOW2** and **RAW** image formats are supported. Other formats (e.g., VMDK, VHD) must be converted before uploading.
</Info>

<Info>
  **Region-scoped:** Custom images are available only in the region where they were uploaded.
</Info>

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

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

<img alt="Screenshot2026 03 02at16 09 42" />

### **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)

<img alt="Instance Flow Custom Image" />

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

<CardGroup>
  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Create instances using your custom images
  </Card>

  <Card title="Snapshots" icon="camera" href="/docs/storage/snapshots">
    Create point-in-time copies of existing instances instead
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/images/create-a-compute-image-from-a-disk-image-url">
    Manage images programmatically via the Networking and Storage API
  </Card>
</CardGroup>


# 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 attaches to a single VPC. 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/compute/managed-kubernetes) in the same VPC before you can use the filesystem.
</Note>

## 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 a **single network** so multiple instances/clusters in that network can share it
* 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 same network).

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

<Warning>
  **Single network attachment:** Each filesystem can only be attached to **one VPC at a time**. Plan your network layout accordingly. To move a filesystem to a different VPC, you must detach it first.
</Warning>

## Requirements

* Permissions to **create and manage storage resources** in the console
* A target **region** selected for the storage resource (Filesystem is region-bound)
* A **network** to attach the storage to (Filesystem attaches to a single network)
* At least one **instance or cluster** in the same network where you will mount the filesystem

<Info>
  If **no VPC** is selected, the **mount command** is **not** provided. You must select a VPC to get the mount command.
</Info>

## Filesystem lifecycle

| Action              | Details                                                                 |
| ------------------- | ----------------------------------------------------------------------- |
| **Create**          | Provide a name, capacity, and select the VPC to attach to               |
| **Resize**          | Increase the filesystem capacity at any time from the console           |
| **Snapshot policy** | Configure recurring filesystem snapshots and retention                  |
| **Mount**           | Use the NFS mount command from any instance/cluster in the attached VPC |
| **Detach**          | Detach the filesystem from its current VPC before moving it to another  |
| **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.
</Warning>

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

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

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

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
   * **Important:** Filesystem supports **a single network attachment**. Plan accordingly if you have multiple networks
3. **Create the Filesystem**
   * Go to **Storage → Filesystem** in the console
   * Provide the required values (for example: name and capacity)
   * 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

<img alt="File Storage" />

## View filesystem details

Click any filesystem in the list to view its detail page. The detail page includes:

* **Overview** — filesystem status, capacity, attached VPC, and mount command
* **Instances** — all instances in the attached VPC 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.

## 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 filesystem is already attached to a different network (single network attachment), or the network is in a different region.

   **Fix:** Verify the filesystem's current attachment and region. If it's attached already, detach it first and re-attach to the intended network. Ensure network and filesystem are 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.

***

## Related resources

<CardGroup>
  <Card title="VPC Networks" icon="earth-europe" href="/docs/network/vpc-networks">
    Create the network your filesystem attaches to
  </Card>

  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Mount the filesystem from your compute instances
  </Card>

  <Card title="Managed Kubernetes" icon="cloud" href="/docs/compute/managed-kubernetes">
    Access shared storage from your Kubernetes clusters
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/file-storage/list-file-storage">
    Manage filesystems programmatically via the Networking and Storage API
  </Card>
</CardGroup>


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

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

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

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

<Info>
  The endpoint URL is available only after the endpoint finishes provisioning.
</Info>

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

## 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 bellow:

| Unsupported feature              | Description                                                                                                                                                                                                                                                  |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **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

   <img alt="Object Storage endpoint list" />
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

   <img alt="Object Storage endpoint details" />
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**

   <img alt="Identity Policies tab" />
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

   <img alt="Access Keys tab" />
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="<access-key-id>"
export AWS_SECRET_ACCESS_KEY="<secret-access-key>"
export AWS_DEFAULT_REGION="<region-name>"
export EP="https://<endpoint-dns-name>"

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

## Terraform Example

If you provision infrastructure with Terraform, use the Object Storage example in the public `terraform-provider-nscale` repository as a starting point:

<Card title="Object Storage Terraform Example" icon="code" href="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
</Card>

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

***

## Related Resources

<CardGroup>
  <Card title="Filesystem" icon="files" href="/docs/storage/file-storage">
    Use shared NFS storage when workloads need a mounted filesystem
  </Card>

  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Run S3-compatible clients from your compute instances
  </Card>

  <Card title="Managed Kubernetes" icon="cloud" href="/docs/compute/managed-kubernetes">
    Use Object Storage from applications running in Kubernetes clusters
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/object-storage/list-endpoints">
    Manage object storage endpoints and access keys programmatically via the Storage Service API
  </Card>
</CardGroup>


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

<Info>
  **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.
</Info>

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

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

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

<img alt="Screenshot2026 03 02at16 11 42" />

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

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

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

<CardGroup>
  <Card title="Instances" icon="rectangle-history-circle-plus" href="/docs/compute/create-new-instances">
    Create instances from snapshots or take snapshots of existing instances
  </Card>

  <Card title="Custom Images" icon="rectangle-history-circle-plus" href="/docs/storage/custom-images">
    Upload your own OS images instead of using snapshots
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/instances/snapshot-instance">
    Manage snapshots programmatically via the Compute API
  </Card>
</CardGroup>


# 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 <SERVICE-TOKEN>"`
   * `"Content-Type": "application/json"`
2. Payload:
   * `"model"`: `"<model id e.g., meta-llama/Llama-3.1-8B-Instruct>"`
   * `"messages"`: `"<array of messages to send to the model>"`

Example use case: Summarise a blog post

<CodeGroup>
  ```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..." }
      ]
    }'
  ```
</CodeGroup>

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

<Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
  Need assistance? Get help from our support team
</Card>


# 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 <SERVICE-TOKEN>"`
   * `"Content-Type": "application/json"`
2. Payload:
   * `"model"`: `"<model id e.g., black-forest-labs/FLUX.1-schnell>"`
   * `"prompt"`: `"<text description of the desired image>"`
   * `"size"`: `"<image size, defaults to 512x512>"`
   * `"n"`: `"<number of images to generate, defaults to 1>"`

Example use case: Generate a landscape at sunset

<CodeGroup>
  ```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
    }'
  ```
</CodeGroup>

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

<img alt="Example request generated image" />

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

<Card title="Contact Support" icon="headset" href="mailto:helpdesk@nscale.com">
  Need assistance? Get help from our support team
</Card>