### Setup GolangCI-Lint Action (No Install)

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures the golangci-lint-action to skip the installation step, assuming it's already installed.

```yaml
- name: Setup golangci-lint
  uses: golangci/golangci-lint-action@v8
  with:
    version: 2.8
    install-mode: none
```

--------------------------------

### Setup GolangCI-Lint Action

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Installs the golangci-lint executable. Use `install-only: true` to only install and not run linters. Set `skip-cache: true` to prevent the action from using its own cache.

```yaml
- name: Setup golangci-lint
  uses: golangci/golangci-lint-action@v8
  with:
    version: 2.8
    install-only: true
    skip-cache: true
```

--------------------------------

### Setup PNPM Action

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Installs the pnpm action. No additional configuration is needed for caching as the pnpm/action-setup handles it.

```yaml
- name: Setup pnpm
  uses: pnpm/action-setup@v4
```

--------------------------------

### Example: Logged in

Source: https://namespace.so/docs/reference/cli/auth-generate-dev-token

This example shows the output of generating a development token when logged in. The token is printed to standard output.

```bash
$ nsc auth generate-dev-token
nsct_eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.tyh-VfuzIxCyGYDlkBA7DfyjrqmSHu6pQ2hoZuFqUSLPNY2N0mpHb3nk5K17HWP_3cYHBw7AhHale5wky6-sVA
```

--------------------------------

### Example Output of nsc cache sccache setup

Source: https://namespace.so/docs/reference/cli/sccache-setup

Shows the typical output format of environment variables when setting up the sccache cache.

```bash
$ nsc cache sccache setup
SCCACHE_WEBDAV_ENDPOINT=https://cache.namespace.so:8080
SCCACHE_WEBDAV_KEY_PREFIX=sccache/my-cache/
SCCACHE_WEBDAV_TOKEN=scc_token_abc123...
```

--------------------------------

### Set Up Android SDK

Source: https://namespace.so/docs/integrations/android-emulators

Install the Android SDK using the `android-actions/setup-android` action.

```yaml
- name: Set up Android SDK
  uses: android-actions/setup-android@v3
```

--------------------------------

### Setup Nix Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures the nscloud-cache-action to cache the Nix store and user cache. This setup should precede the Nix installation.

```yaml
- name: Set up nix cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: nix
```

--------------------------------

### Set Up JDK

Source: https://namespace.so/docs/integrations/android-emulators

Install a specific JDK version using the `actions/setup-java` action.

```yaml
- name: Set up JDK
  uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: 17
```

--------------------------------

### Setup Mise Action

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Installs Mise and its packages. Ensure `cache: false` is set to disable Mise's built-in cache, allowing the nscloud-cache-action to manage caching.

```yaml
- name: Setup mise
  uses: jdx/mise-action@v2
  with:
    cache: false
```

--------------------------------

### Start a Container Preview

Source: https://namespace.so/docs/solutions/previews

Start a preview for a specified container image. This command prints a preview URL for accessing the running container.

```bash
$ nsc run --image nginx -p 80
# Prints a preview URL, e.g.: https://4bi2reg-grijlvs6ciapa.ord2.namespaced.app
```

--------------------------------

### Example Docker Buildx Status Output

Source: https://namespace.so/docs/reference/cli/docker-buildx-status

This example shows the typical output format when checking the status of multiple platforms for the buildx builder.

```bash
$ nsc docker buildx status
Platform: linux/amd64
  Status:     ready
  Instance:   85a32emcg99ii
  Requests:   42

Platform: linux/arm64
  Status:     ready
  Instance:   h9am86n6gi25m
  Requests:   38
```

--------------------------------

### Install Nix

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Installs Nix, leveraging the pre-mounted `/nix` store provided by the nscloud-cache-action.

```yaml
- name: Install Nix
  uses: cachix/install-nix-action@v31
  with:
    extra_nix_config: |
      access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
      system-features = kvm nixos-test
```

--------------------------------

### Instance Report with Example Data

Source: https://namespace.so/docs/reference/cli/instance-report

This example demonstrates the output format of the `nsc instance report` command when run for the last hour and directed to stdout. It includes columns for instance details, resource usage, and GitHub Actions job information.

```bash
$ nsc instance report --start 2026-05-11T11:00:00Z --out -
Writing output to path: stdout
instance_id,created_at,started_at,destroyed_at,resources_cpu,resources_ram_gb,resources_cpu_actual_max,resources_ram_gb_actual_max_percent,github_job_id,github_job_name,github_job_workflow_name,github_run_id,github_run_attempt,job_created_at,job_started_at,job_completed_at
iekjd1l47to3k,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:11:10 +0000 UTC,8,16,0.7,0.17460646,75349817393,go test,Go,25669248595,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:43 +0000 UTC
mcja6q4oi4kh2,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:12:07 +0000 UTC,16,32,0.6451724,0.14323927,75349827012,validate,Validate,25669251386,1,2026-05-11 12:09:59 +0000 UTC,2026-05-11 12:10:04 +0000 UTC,2026-05-11 12:11:29 +0000 UTC
a5gkg10as2tdg,2026-05-11 12:09:57 +0000 UTC,2026-05-11 12:09:58 +0000 UTC,2026-05-11 12:10:46 +0000 UTC,2,4,0.94,0.2463041,75349817514,go lint,Go,25669248531,1,2026-05-11 12:09:55 +0000 UTC,2026-05-11 12:10:05 +0000 UTC,2026-05-11 12:10:22 +0000 UTC
```

--------------------------------

### Generate and Use Kubeconfig for an Instance

Source: https://namespace.so/docs/reference/cli/kubeconfig-write

This example demonstrates creating an instance, writing its kubeconfig, and then using that kubeconfig to deploy an application with kubectl.

```bash
nsc create
Created instance "1lf2ol9ioulce"
 deadline: 2023-04-25T13:24:53Z

nsc kubeconfig write 1lf2ol9ioulce
Wrote Kubeconfig for instance 1lf2ol9ioulce to ~/.cache/ns/tmp/kubeconfig/2342545987.yaml.

Start using it by setting:
  export KUBECONFIG=~/.cache/ns/tmp/kubeconfig/2342545987.yaml

$ export KUBECONFIG=~/.cache/ns/tmp/kubeconfig/2342545987.yaml
$ kubectl apply -f https://k8s.io/examples/application/nginx-app.yaml
service/my-nginx-svc created
deployment.apps/my-nginx created
```

--------------------------------

### Install Nix on Remote Instance

Source: https://namespace.so/docs/integrations/nix

Installs Nix on the remote compute instance using the Determinate installer. Replace `<id>` with your instance ID.

```bash
$ ssh <id>@ssh.ord2.namespace.so "curl -fsSL https://install.determinate.systems/nix | sh -s -- install linux --determinate --init none --no-confirm"
```

--------------------------------

### Setup Mise Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures the nscloud-cache-action to cache downloaded tools for Mise. This setup should precede the Mise installation.

```yaml
- name: Set up mise cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: mise
```

--------------------------------

### Example Docker login output

Source: https://namespace.so/docs/reference/cli/docker-login

This example shows the output after a successful `nsc docker login`, including the workspace container registry endpoint and a suggestion for the next step.

```bash
$ nsc docker login

You are now logged into your workspace container registry:

  nscr.io/8enum0hp1l5ii

Run your first build with:

  $ nsc build . --name test --push

Visit our docs for more details on Remote Builds:

  https://namespace.so/docs/solutions/docker-builders
```

--------------------------------

### Example: Configure Buildx and Use Remote Builders

Source: https://namespace.so/docs/reference/cli/docker-buildx-setup

This example demonstrates how to configure local Buildx to use Namespace Remote Builders and immediately set the Docker context to use them. After running this, Docker builds will automatically utilize the remote builder infrastructure.

```bash
$ nsc docker buildx setup --background --use
```

```bash
$ docker build . -t app:latest
```

--------------------------------

### Example of reading instance-id metadata

Source: https://namespace.so/docs/reference/cli/instance-metadata

This example demonstrates how to read the 'instance-id' metadata value. The command returns the associated value.

```bash
$ nsc instance metadata read instance-id
85a32emcg99ii
```

--------------------------------

### Example Artifact Upload

Source: https://namespace.so/docs/reference/cli/artifact-upload

Demonstrates uploading a file named 'text.txt' to 'target.txt' within the 'main' namespace.

```bash
% nsc artifact upload text.txt target.txt
Uploaded text.txt to target.txt (namespace main)
```

--------------------------------

### Configure sccache Locally with Token and Start Server

Source: https://namespace.so/docs/integrations/sccache

Sets up sccache configuration using a token saved to a file and starts the sccache server. This binds credentials to the user and enables local builds to utilize the shared cache.

```bash
$ export $(nsc cache sccache setup --token token.json --cache_name default)
$ sccache --start-server
```

--------------------------------

### Test Nix Installation

Source: https://namespace.so/docs/integrations/nix

Verifies that Nix is installed and working correctly on the remote instance. Replace `<id>` with your instance ID.

```bash
$ ssh <id>@ssh.ord2.namespace.so nix run nixpkgs#hello
```

--------------------------------

### Get pods from all namespaces using nsc kubectl

Source: https://namespace.so/docs/reference/cli/kubectl

This example demonstrates how to retrieve a list of all pods across all namespaces in a Namespace instance using the nsc kubectl command. It requires the instance ID and the 'get pods -A' kubectl arguments.

```bash
$ nsc kubectl 1lf2ol9ioulce get pods -A
NAMESPACE        NAME                                      READY   STATUS    RESTARTS   AGE
kube-system      coredns-5c6b6c5476-zh7rq                  1/1     Running   0          9s
kube-system      local-path-provisioner-5d56847996-lz8nd   1/1     Running   0          9s
metallb-system   controller-bdf98b979-qfwxr                0/1     Running   0          9s
metallb-system   speaker-rwxqr                             0/1     Running   0          9s
```

--------------------------------

### NPM tests on Playwright with nscloud-cache-action in a Container

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

This example demonstrates a complete GitHub Actions workflow for running NPM tests using Playwright within a container. It shows the necessary container configuration, including image, environment variables, volume mounts, and capabilities, along with steps for checking out code, installing sudo, setting up the PNPM cache, and running tests.

```yaml
name: NPM tests on Playwright
jobs:
  tests:
    runs-on: namespace-profile-my-profile-for-containers

    container:
      image: mcr.microsoft.com/playwright:v1.39.0
      env:
        NSC_CACHE_PATH: ${{ env.NSC_CACHE_PATH }} # env.NSC_CACHE_PATH contains the path to Cache Volume directory, that is `/cache`.
      volumes:
        - /cache:/cache # Where the Cache Volume is mounted.
      options: --cap-add=SYS_ADMIN # Required to by nscloud-cache-action to call `mount`.

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install sudo
        run: |
          apt-get update -y && apt-get install -y sudo

      - name: Setup PNPM cache
        uses: namespacelabs/nscloud-cache-action@v1
        with:
          cache: pnpm

      - name: Install dependencies and run tests
        run: |
          pnpm install
          pnpm run test

```

--------------------------------

### Example of adding a secret with description and label

Source: https://namespace.so/docs/reference/cli/vault-add

This example demonstrates adding a secret with a description and a key-value label. The secret value is entered interactively.

```bash
$ nsc vault add --description "Database password" --label env=production
Enter secret value: ****

Object ID:    sec_8fumgjd5jk
Description:  Database password
Version:      secv_hk6jk1j6d0
```

--------------------------------

### Download Artifact Example

Source: https://namespace.so/docs/reference/github-actions/download-artifact

This example demonstrates how to download a specific artifact named 'test-archive' to the '/tmp/destination' path using the download-artifact action.

```yaml
jobs:
  deploy:
    name: Demo Download Archive
    runs-on: namespace-profile-default
    steps:
      - name: Download Archive
        uses: namespace-actions/download-artifact@v2
        with:
          name: test-archive
          path: /tmp/destination
```

--------------------------------

### Setup Managed Claude Agent Environment

Source: https://namespace.so/docs/integrations/claude

Initiates the setup process for a managed Claude agent environment. You will be prompted to provide your Anthropic API key.

```bash
$ devbox claude managed-agents setup-environment
```

--------------------------------

### Triggering Remote Builds with Namespace

Source: https://namespace.so/docs/federation/rwx

Example RWX workflow configuration to install the Namespace CLI, log in, and trigger a remote build. It utilizes a federated OIDC token for authentication.

```yaml
# .rwx/main.yaml
tasks:
  - key: namespace-cli
    call: namespace/install-cli 1.0.0

  - key: namespace-login
    call: namespace/login-hook 1.0.0
    with:
      workspace-id: my-namespace-workspace-id

  - key: build-image
    use: [namespace-cli, namespace-login]
    run: nsc build --name my-app .
    env:
      NAMESPACE_OIDC_TOKEN:
        value: ${{ vaults.deploy-vault.oidc.namespace }}
        cache-key: excluded
```

--------------------------------

### Start VNC Session

Source: https://namespace.so/docs/reference/cli/vnc

Connect to a specific instance using its ID. If no instance ID is provided, it will list available instances.

```bash
nsc vnc [instance-id]
```

```bash
$ nsc vnc 85a32emcg99ii
Connected to instance.
Opening VNC client...
```

--------------------------------

### Download a File from an Instance

Source: https://namespace.so/docs/reference/cli/instance-download

Example of downloading the application log file from an instance to the current directory. The output confirms the download size and time taken.

```bash
$ nsc instance download 85a32emcg99ii /var/log/app.log ./app.log
Downloaded /var/log/app.log (342 KiB). Took 2.3s.
```

--------------------------------

### Basic Upload Artifact Example

Source: https://namespace.so/docs/reference/github-actions/upload-artifact

Demonstrates a basic workflow step to upload an artifact named 'test-archive' from the './archive' directory.

```yaml
jobs:
  upload:
    name: Demo Upload Archive
    runs-on: namespace-profile-default
    steps:
      - name: Upload Archive
        uses: namespace-actions/upload-artifact@v1
        with:
          name: test-archive
          path: ./archive
```

--------------------------------

### GitHub Actions: Setup Gradle Build Cache

Source: https://namespace.so/docs/integrations/gradle

Integrates Namespace's Gradle build cache setup into a GitHub Actions workflow.

```diff
 jobs:
   build:
     runs-on: namespace-profile-default
   steps:
     - uses: actions/checkout@v4
+    - name: Setup Gradle cache
+      run: |
+        nsc cache gradle setup --init-gradle /tmp/init.gradle
     - name: Gradle build
       run: |
         gradle --init-script=/tmp/init.gradle build
```

--------------------------------

### Example nsc login output

Source: https://namespace.so/docs/reference/cli/login

This example shows the expected output after running the `nsc login` command, including the prompt to complete the login in a browser and the success message.

```bash
$ nsc login
Login to Namespace
Please complete the login flow in your browser.

  https://cloud.namespace.so/login/workspace?id=<id>

You are now logged in, have a nice day.
```

--------------------------------

### Setup Node with Corepack enabled

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Sets up Node.js using actions/setup-node and enables Corepack, which is necessary for managing Yarn versions and caches.

```yaml
- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: '22'
    cache: ''

- name: Enable Corepack
  run: corepack enable
```

--------------------------------

### Install Dependencies and Run Playwright Tests

Source: https://namespace.so/docs/integrations/playwright

Standard commands to install npm dependencies, download Playwright browsers with system dependencies, and execute Playwright tests.

```yaml
- name: Install dependencies
  run: npm ci

- name: Install Playwright browsers
  run: npx playwright install --with-deps

- name: Run Playwright tests
  run: npx playwright test
```

--------------------------------

### List all repositories

Source: https://namespace.so/docs/reference/cli/registry-list

Use the `--repositories` flag to list all available repositories in the registry. This is useful for getting an overview of your stored container images.

```bash
nsc registry list --repositories
```

--------------------------------

### Create a Devbox with Interactive Prompts

Source: https://namespace.so/docs/devbox/managing

Use this command to create a new Devbox. It will guide you through the configuration with interactive prompts.

```bash
$ devbox create
```

--------------------------------

### Example output of 'nsc vault list'

Source: https://namespace.so/docs/reference/cli/vault-list

This example shows the typical table output when listing vault objects, including their ID, version, description, and creation date.

```bash
$ nsc vault list
OBJECT ID        VERSION            DESCRIPTION             CREATED
---------------------------------------------------------------------------------
sec_8fumgjd5jk   secv_hk6jk1j6d0    Test ECDSA SSH Key      2023-08-30T23:03:14Z
sec_rdb1lirdp4   secv_kuifdoaheg    TestSecret              2023-10-10T22:49:41Z
```

--------------------------------

### Example of assuming an AWS role and exporting credentials

Source: https://namespace.so/docs/reference/cli/aws-assume-role

This example demonstrates how to assume an AWS role and how the command outputs the exported environment variables for AWS credentials. The credentials obtained are temporary and valid for a specified duration.

```bash
$ nsc aws assume-role --role_arn arn:aws:iam::123456789012:role/my-role
Obtained credentials from Namespace (took 234ms).
Obtained credentials from AWS (took 456ms).
export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
export AWS_SESSION_TOKEN=AQoDYXdzEJr...
```

--------------------------------

### Setup GolangCI-Lint Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures the nscloud-cache-action to cache GolangCI-Lint analysis results.

```yaml
- name: Set up golangci-lint cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: golangci-lint
```

--------------------------------

### Example: Caching NPM Packages

Source: https://namespace.so/docs/reference/github-actions/runner-configuration

Use the nscloud-cache-action to mount volumes for caching NPM packages.

```yaml
jobs:
  build:
    runs-on: nscloud-ubuntu-22.04-amd64-4x8
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - uses: nscloud-cache-action@v1
        with:
          path: |
            ~/.npm
            ~/cache/node_modules
          # Optional: If you want to use a specific cache key
          # cache-key: npm-packages-{{ hashFiles('**/package-lock.json') }}
      - run: npm ci
      - run: npm run build
```

--------------------------------

### Setup Local Gradle Cache with Token

Source: https://namespace.so/docs/integrations/gradle

Configures the Gradle build cache for the current user on a local machine using a saved token.

```bash
$ nsc cache gradle setup --token token.json --user
```

--------------------------------

### Setup UV with built-in cache disabled

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures UV using setup-uv and disables its built-in cache to allow nscloud-cache-action to manage it.

```yaml
- name: Setup uv
  uses: astral-sh/setup-uv@v5
  with:
    enable-cache: false
```

--------------------------------

### Upload Configuration File Example

Source: https://namespace.so/docs/reference/cli/instance-upload

Demonstrates uploading a local configuration file to a specified path within a Namespace instance. The output confirms the upload details.

```bash
$ nsc instance upload 85a32emcg99ii ./config.yaml /etc/app/config.yaml
Uploaded config.yaml (12 KiB) to /etc/app/config.yaml. Took 1.2s.
```

--------------------------------

### Setup Gradle Cache Access via CLI

Source: https://namespace.so/docs/integrations/gradle

Generates short-term credentials and an init script to configure remote build caching for Gradle.

```bash
$ nsc cache gradle setup --init-gradle /tmp/init.gradle
```

--------------------------------

### Run nsc cache sccache setup

Source: https://namespace.so/docs/reference/cli/sccache-setup

Executes the command to set up a remote sccache cache and prints the necessary environment variables.

```bash
nsc cache sccache setup
```

--------------------------------

### Start RDP Session to a Windows Instance

Source: https://namespace.so/docs/reference/cli/rdp

Initiates an RDP session to a specific Windows instance by providing its ID. RDP credentials will be displayed on the CLI.

```bash
nsc rdp 85a32emcg99ii
```

--------------------------------

### Basic nscloud-setup Usage in GitHub Actions

Source: https://namespace.so/docs/reference/github-actions/nscloud-setup

This snippet demonstrates the basic integration of the `nscloud-setup` action within a GitHub Actions workflow. It checks out the code, sets up the Namespace environment, and then proceeds to create an ephemeral Kubernetes cluster using the `nsc` CLI.

```yaml
jobs:
  deploy:
    name: Ephemeral cluster
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: namespacelabs/nscloud-setup@v0
      - name: Create an ephemeral Kubernetes cluster
        run: |
          nsc cluster create
```

--------------------------------

### Setup Pantsbuild Remote Cache

Source: https://namespace.so/docs/reference/cli/pants-cache-setup

Use this command to set up a remote cache for Pantsbuild. Optionally specify the output path for the `pants.toml` configuration file.

```bash
nsc cache pants setup [--pants-toml <target pants toml path>]
```

--------------------------------

### Download Artifacts from Namespace Runners

Source: https://namespace.so/docs/federation/github-actions

Example of downloading artifacts in a GitHub Actions workflow running on Namespace runners. No additional setup is needed as the runner has inherent access.

```yaml
download:
  runs-on: namespace-profile-default # runs on Namespace
  steps:
    # No setup needed. Runner can already access Namespace artifacts.
    - uses: namespace-actions/download-artifact@v2
      with:
        name: test-archive
        path: /tmp/destination
```

--------------------------------

### Basic setup-turbocache GitHub Action

Source: https://namespace.so/docs/reference/github-actions/setup-turbocache

This snippet shows the basic configuration for the `setup-turbocache` action within a GitHub Actions workflow. It includes checking out the code, setting up the cache, and running a turbo build command.

```yaml
jobs:
  build:
    runs-on: namespace-profile-default

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Set up caching
        uses: namespace-actions/setup-turbocache@v0
      - name: Go turbo
        run: turbo build
```

--------------------------------

### Replace setup-buildx-action with nscloud-setup-buildx-action

Source: https://namespace.so/docs/solutions/github-actions/docker-builds

Remove `docker/setup-buildx-action` and replace it with `namespacelabs/nscloud-setup-buildx-action` to ensure compatibility with Namespace's remote builders.

```diff
- name: Set up Docker Buildx
- uses: docker/setup-buildx-action@v3
+ uses: namespacelabs/nscloud-setup-buildx-action@v0
- uses: docker/build-push-action@v5
with:
context: .

```

--------------------------------

### Example: Caching GitHub Tools (Go)

Source: https://namespace.so/docs/reference/github-actions/runner-configuration

Cache Go binaries using the runner's tool cache directory. The setup-go action automatically checks this directory before fetching from remote sources.

```yaml
jobs:
  build:
    runs-on: nscloud-ubuntu-22.04-amd64-4x8
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.21'
          cache-path: |-
            ~/go/pkg/mod
            ~/.cache/go-build
      # Optional: If you want to use a specific cache key
      # - uses: nscloud-cache-action@v1
      #   with:
      #     path: |
      #       ~/go/pkg/mod
      #       ~/.cache/go-build
      #     cache-key: go-modules-{{ hashFiles('**/go.sum') }}
      - run: go build ./...
```

--------------------------------

### Export sccache environment variables in shell

Source: https://namespace.so/docs/reference/cli/sccache-setup

Exports the environment variables output by `nsc cache sccache setup` for use in the current shell session, then starts the sccache server.

```bash
export $(nsc cache sccache setup)
sccache --start-server
```

--------------------------------

### Access Cache Volumes from Containers

Source: https://namespace.so/docs/reference/github-actions/runner-configuration

Configure a custom container to access Cache Volumes by mounting a directory (e.g., /cache) and setting the NSC_CACHE_PATH environment variable. This example shows setup for Rust caching.

```yaml
tests:
  runs-on: namespace-profile-my-profile-for-containers

  container:
    image: <my-image-ref>
    env:
      NSC_CACHE_PATH: ${{ env.NSC_CACHE_PATH }} # env.NSC_CACHE_PATH contains the path to Cache Volume directory, that is `/cache`.
    volumes:
      - /cache:/cache # Where the Cache Volume is mounted.
    options: --cap-add=SYS_ADMIN # Required to by nscloud-cache-action to call `mount`.

  steps:
    - uses: actions/checkout@v4

    - name: Install sudo
      run: |
        apt-get update -y && apt-get install -y sudo

    - name: Setup cache
      uses: namespacelabs/nscloud-cache-action@v1
      with:
        cache: rust
```

--------------------------------

### Install Devbox CLI on macOS/Linux

Source: https://namespace.so/docs/devbox

Installs the Devbox CLI using a curl script. Ensure you restart your terminal after installation for the command to be available.

```bash
$ curl -fsSL get.namespace.so/devbox/install.sh | bash
```

--------------------------------

### Install Poetry

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Installs Poetry using pipx, which is a prerequisite for enabling the 'poetry' cache mode in the nscloud-cache-action.

```yaml
- name: Install Poetry
  run: pipx install poetry
```

--------------------------------

### Run Compose and Wait for Containers

Source: https://namespace.so/docs/reference/cli/run-compose

Starts containers from a compose file and waits until all containers have successfully started running.

```bash
nsc run-compose --wait
```

--------------------------------

### Set up multiple caches (Go and Rust)

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Demonstrates how to configure the nscloud-cache-action to cache multiple ecosystems simultaneously, in this case, Go and Rust.

```yaml
- name: Set up Go and Rust cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: |
      go
      rust
```

--------------------------------

### Install Devbox CLI on Windows

Source: https://namespace.so/docs/devbox

Installs the Devbox CLI using PowerShell. A terminal restart may be required for the 'devbox' command to be recognized.

```powershell
irm https://get.namespace.so/devbox/install.ps1 | iex
```

--------------------------------

### Enable Kubernetes Ingress Manager and Configure Kubeconfig

Source: https://namespace.so/docs/solutions/previews/kubernetes

Create a preview cluster, enable the ingress manager, and set up your local kubectl configuration.

```bash
$ nsc create --features EXP_KUBERNETES_INGRESS_MANAGER
# Outputs the ID of the created cluster, e.g.: dr9flh12238uk
$ nsc kubeconfig write dr9flh12238uk --output_to /path/kubeconfig.yaml
$ export KUBECONFIG=/path/kubeconfig.yaml
```

--------------------------------

### Example of Deleting a Vault Object

Source: https://namespace.so/docs/reference/cli/vault-delete

This example demonstrates how to delete a specific object from the vault using its ID and shows the expected success output.

```bash
$ nsc vault delete --object_id sec_8fumgjd5jk
Successfully deleted object sec_8fumgjd5jk.
```

--------------------------------

### Deploy and Expose Kubernetes Application

Source: https://namespace.so/docs/solutions/previews/kubernetes

Use these commands to create a deployment and expose it as a LoadBalancer service.

```bash
$ nsc kubectl 072higp5dg0bg create deployment app --image=myapp:latest
$ nsc kubectl 072higp5dg0bg expose deployment app --type=LoadBalancer --port=80
```

--------------------------------

### Create a Kubernetes Preview Cluster

Source: https://namespace.so/docs/solutions/previews/kubernetes

Create a new Kubernetes cluster to host your preview environment. The command outputs the ID of the created cluster.

```bash
$ nsc create
# Outputs the ID of the created cluster, e.g.: 072higp5dg0bg
```

--------------------------------

### Basic Instance Creation

Source: https://namespace.so/docs/reference/cli/create

Creates a new ephemeral Kubernetes instance using the default machine shape (4 CPUs, 8 GiB RAM).

```bash
$ nsc create
  Created instance "h9am86n6gi25m"
    deadline: 2023-04-25T08:48:38Z
```

--------------------------------

### Start VNC Session via CLI

Source: https://namespace.so/docs/architecture/compute/ssh-remote-display

Use the Namespace CLI to start a VNC session for macOS runners. VNC support for other platforms is under development.

```bash
$ nsc vnc <instance-id>
```

--------------------------------

### Configure Docker buildx with Namespace Remote Builders

Source: https://namespace.so/docs/reference/github-actions/nscloud-setup-buildx-action

This example demonstrates how to integrate the nscloud-setup-buildx-action into a GitHub Actions workflow. It ensures Docker is configured to use remote builders provided by Namespace, facilitating distributed image builds. Ensure nscloud-setup is run beforehand for authentication.

```yaml
jobs:
  docker:
    runs-on: ubuntu-latest
    # These permissions are needed to interact with GitHub's OIDC Token endpoint.
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: namespacelabs/nscloud-setup@v0
      - name: Configure Docker to use Namespace Remote Builders
        uses: namespacelabs/nscloud-setup-buildx-action@v0
      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          push: true
          tags: user/app:latest
```

--------------------------------

### Instance Download Usage

Source: https://namespace.so/docs/reference/cli/instance-download

The basic syntax for downloading a file from an instance. Specify the instance ID, the remote path of the file, and optionally, the local path to save it.

```bash
nsc instance download [instance-id] <remote-path> [local-path]
```

--------------------------------

### Instance Creation with Custom Machine Type and Output File

Source: https://namespace.so/docs/reference/cli/create

Creates a Kubernetes instance with a specified machine shape (4 CPUs, 16 GiB RAM) and writes the instance ID to a file for automation.

```bash
$ nsc create --machine_type 4x16 --output_to /tmp/instance_id
  Created instance "hrc4b9nvoj7ki"
    deadline: 2023-04-25T08:58:58Z

$ cat /tmp/instance_id
  hrc4b9nvoj7ki
```

--------------------------------

### Example Output of Trust Relationships

Source: https://namespace.so/docs/reference/cli/auth-trust-relationships-list

This is an example of the output you can expect when listing trust relationships. It includes the ID, Issuer, Subject Match pattern, and creation timestamp for each relationship.

```bash
$ nsc auth trust-relationships list
Trust Relationships:

ID: tr_abc123
Issuer: https://accounts.google.com
Subject Match: projects/123456789/serviceAccounts/my-service@my-project.iam.gserviceaccount.com
Created: 2024-01-15 10:30:00 UTC

ID: tr_def456  
Issuer: https://fly.io/example-org
Subject Match: example-org:app:*
Created: 2024-01-10 14:22:00 UTC

ID: tr_ghi789
Issuer: https://cloud.rwx.com/mint
Subject Match: org:my-org:vault:deploy-vault
Created: 2024-01-08 09:15:00 UTC

```

--------------------------------

### Set up Apt Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Enables caching for APT packages. Ensure the `apt-config` executable is available before running this action.

```yaml
- name: Set up apt cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: apt
```

--------------------------------

### Configure Cache Access and Start sccache

Source: https://namespace.so/docs/integrations/sccache

Generates short-term credentials and exports environment variables for sccache configuration. After exporting, start the sccache server to enable remote caching.

```bash
$ export $(nsc cache sccache setup --cache_name default)
$ sccache --start-server
```

--------------------------------

### GitHub Actions: Setup Pants Cache

Source: https://namespace.so/docs/integrations/pants

Integrates Namespace Pants cache setup into a GitHub Actions workflow. This step ensures that the Pants cache is configured before the build or test steps.

```yaml
jobs:
  build:
    runs-on: namespace-profile-default
  steps:
    - name: Setup Pants cache
      run: |
        nsc cache pants setup --pants-toml=/tmp/pants.toml
    - name: Pants test
      run: |
        pants --pants-config-files=\
/your/own/pants.toml
/tmp/pants.toml
```

--------------------------------

### Observe resource utilization of a created instance

Source: https://namespace.so/docs/reference/cli/top

After creating an instance, use this command with the instance ID to observe its resource utilization.

```bash
nsc top hk99v6hn1tk9m
```

--------------------------------

### Start Nginx Container

Source: https://namespace.so/docs/reference/cli/expose

Run an Nginx container within the ephemeral instance using Docker. This command starts Nginx and maps port 80 on the container to port 80 on the instance.

```bash
oiepencpc41im:~# docker run --name nginx-foobar -p 80:80 -d nginx
```

--------------------------------

### Example: Caching Docker Images

Source: https://namespace.so/docs/reference/github-actions/runner-configuration

Cache Docker image pulls across workflow invocations to reduce pull times. This example assumes a prior run has already pulled and cached the image.

```yaml
jobs:
  build:
    runs-on: nscloud-ubuntu-22.04-amd64-4x8
    steps:
      - uses: actions/checkout@v4
      - name: Setup Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Cache Docker layer
        uses: nscloud-cache-action@v1
        with:
          path: /var/lib/docker
          # Optional: If you want to use a specific cache key
          # cache-key: docker-images-{{ github.sha }}
      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: my-dockerhub-username/my-app:latest
```

--------------------------------

### Claude Agent Configuration Example

Source: https://namespace.so/docs/integrations/claude

An example JSON configuration for a Claude agent designed to connect with the Namespace Devbox Agent Runner. This configuration includes agent name, description, model, system prompt, and tool definitions.

```json
{
  "name": "Namespace Devbox Agent",
  "description": "Managed agent running on a Namespace Devbox, with access to tools and resources on the Devbox.",
  "model": "claude-sonnet-4-6",
  "system": "You are a coding agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.",
  "mcp_servers": [],
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "skills": []
}
```

--------------------------------

### Use the token with the nsc CLI

Source: https://namespace.so/docs/reference/cli/token-create

Demonstrates how to create a token and save it to a file, then use that file with the NSC_TOKEN_FILE environment variable to authenticate subsequent 'nsc' CLI commands.

```bash
# 1. Create the token and save it to a file.
nsc token create \
  --name "cli-token" \
  --grant '{"resource_type":"instance","resource_id":"*","actions":["create","get","list","destroy"]}' \
  --token_file token.json

# 2. Use it for subsequent nsc CLI commands.
$ NSC_TOKEN_FILE="./token.json" nsc instance list
```

--------------------------------

### Skip GitHub's Built-in Action Cache

Source: https://namespace.so/docs/solutions/github-actions/caching

Disable GitHub's built-in action caching for specific setup actions (e.g., `actions/setup-go`, `actions/setup-node`) when using Namespace's caching to prevent superfluous network transfers and reduce setup time.

```yaml
- name: Setup Go
  uses: actions/setup-go@v6
  with:
    go-version: "1.21"
    cache: false # Use Namespace caching instead
```

```yaml
- name: Setup Node.js
  uses: actions/setup-node@v6
  with:
    node-version: "18"
    package-manager-cache: false # Use Namespace caching instead
    cache: ""
```

--------------------------------

### Create a Bare Compute Instance

Source: https://namespace.so/docs/integrations/nix

Creates a new bare compute instance on Namespace. Ensure you have your SSH key ready.

```bash
$ nsc create --bare --ssh_key ~/.ssh/id_ed25519.pub
```

--------------------------------

### Remove setup-qemu-action for Remote Builders

Source: https://namespace.so/docs/solutions/github-actions/docker-builds

When using Namespace's remote builders for multi-platform builds, QEMU emulation is not required and `docker/setup-qemu-action` can be safely removed.

```diff
steps:
- 	uses: docker/setup-qemu-action@v3
- 	uses: docker/setup-buildx-action@v3
- uses: docker/build-push-action@v5
with:
context: .

```

--------------------------------

### Deploy Application using Kubectl

Source: https://namespace.so/docs/solutions/previews/kubernetes

Deploy a simple Nginx application to the configured Kubernetes preview cluster using `kubectl run`.

```bash
$ kubectl run nginx --image=nginx
```

--------------------------------

### Create a Devbox with Inline Parameters

Source: https://namespace.so/docs/devbox/managing

Pass parameters directly on the command line to specify the Devbox name, size, and image, skipping interactive prompts.

```bash
$ devbox create --name my-devbox --size M --image builtin:agents
```

--------------------------------

### Set up Poetry cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Configures the nscloud-cache-action to cache Poetry packages. Ensure Poetry is installed before this step.

```yaml
- name: Set up poetry cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: poetry
```

--------------------------------

### List Instances (Human-Friendly Format)

Source: https://namespace.so/docs/reference/cli/list

Prints a list of instances in a human-readable table format. This is the default output when no format option is specified.

```bash
nsc list
```

--------------------------------

### Set up Bun Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Enables caching for Bun packages. This action should be run after `oven-sh/setup-bun`.

```yaml
- name: Setup Bun
  uses: oven-sh/setup-bun@v2
  with:
    cache: false

- name: Set up bun cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: bun
```

--------------------------------

### Example: Custom Cache Identity

Source: https://namespace.so/docs/reference/github-actions/runner-configuration

Specify custom cache tags for full control over cache isolation boundaries.

```yaml
jobs:
  build:
    runs-on: nscloud-ubuntu-22.04-amd64-4x8
    steps:
      - uses: actions/checkout@v4
      - uses: nscloud-cache-action@v1
        with:
          path: |
            ~/.npm
            ~/cache/node_modules
          cache-key: custom-cache-tag-{{ github.sha }}
```

--------------------------------

### Start RDP Session for Windows Instance

Source: https://namespace.so/docs/architecture/compute/windows

Initiates an RDP session to a Windows instance using the Namespace CLI. RDP credentials will be displayed on the CLI and must be manually entered into an RDP client.

```bash
$ nsc rdp <instance-id>
```

--------------------------------

### Setup PNPM Cache

Source: https://namespace.so/docs/reference/github-actions/nscloud-cache-action

Enables caching for pnpm packages using the nscloud-cache-action. Assumes the pnpm executable is available.

```yaml
- name: Set up pnpm cache
  uses: namespacelabs/nscloud-cache-action@v1
  with:
    cache: pnpm
```

--------------------------------

### Create Instance with Cache Volume

Source: https://namespace.so/docs/solutions/github-actions/caching

Use this command to create a new Namespace instance and attach a specified cache volume. Ensure the tag and size match your dashboard configuration.

```bash
$ nsc create --volume cache:<cache-tag>:/cache:<size>gb
```