Namespace SDK Examples

This repository contains examples demonstrating how to use the Namespace SDK across different programming languages.

Repository Structure

examples/
├── go/ # Go SDK examples
├── typescript/ # TypeScript SDK examples
└── README.md # This file

Go Examples

The Go examples are located in the go/ directory. Each example demonstrates different aspects of the Namespace SDK:

Available Examples

Example	Description
build	Building Docker images using BuildKit with authentication and secrets management
createinstance	Creating compute instances with specific configurations and running containers
createpartnerinstance	AWS identity federation with Namespace and creating instances with federated credentials
ensuretenant	Creating and managing tenants using AWS federation for identity management
ensurewithcache	Creating or reusing a uniquely tagged instance with a cache volume
buildandrun	Complete workflow: build image, create instance, run service, and connect via gRPC
macrun	Building and running Go applications on macOS/ARM64 instances
macoshttps	Running an HTTP service on macOS behind a TLS-terminating ingress
macosmtls	Running a TCP service on macOS and connecting through an mTLS ingress
sidecar	Advanced instance configuration with sidecar containers and SSH access

Getting Started with Go Examples

Prerequisites

• Go 1.21 or later
• Namespace authentication credentials
• For AWS federation examples: AWS credentials with appropriate permissions

Common SDK Patterns

• Authentication: Token loading from workstations (auth.LoadUserToken()) or instances (auth.LoadWorkloadToken())
• Compute API: Creating instances, waiting for readiness, describing instances
• Builds API: Building images with BuildKit, pushing to registry
• IAM API: Tenant creation and management with external account federation
• gRPC Communication: Client-server communication with TLS

Example Details

build

Demonstrates using the Namespace Builds SDK with BuildKit to build Docker images from Dockerfiles.

createinstance

Shows how to create compute instances with specific CPU/memory/architecture configurations and run containers.

createpartnerinstance

Demonstrates AWS identity federation with Namespace and creating instances with federated credentials.

ensuretenant

Shows how to create and manage tenants using AWS federation for identity management.

ensurewithcache

Shows how to create or reuse an instance with a unique tag and attach a cache volume that can be restored across instance lifetimes.

buildandrun

Complete end-to-end example: build a Docker image, create an instance, run a gRPC service, and connect to it.

macrun

Demonstrates building Go binaries for macOS/ARM64 and running them on Apple Silicon instances.

macoshttps

Builds an HTTP service for macOS/ARM64, runs it as an application, exposes it through a TLS-terminating HTTP ingress, and calls the resulting HTTPS endpoint.

From the go directory, run it with:

go run ./macoshttps -basedir ./macoshttps

macosmtls

Builds a TCP echo service for macOS/ARM64, runs it as an application, exposes it through an mTLS-authenticated TCP ingress, and calls it with a short-lived Namespace client certificate.

From the go directory, run it with:

go run ./macosmtls -basedir ./macosmtls

sidecar

Advanced example showing instance configuration with sidecar containers, volume mounting, and SSH access.

TypeScript Examples

The TypeScript examples are located in the typescript/ directory. The API is defined using Buf platform and uses TypeScript bindings generated by it. The underlying protocol is based on HTTP and uses text JSON encoding.

Available Examples

Example	Description
kubernetes-demo	Create an ephemeral Kubernetes cluster and obtain kubeconfig
containers-demo	Create compute instances with containers and stream logs
iam-demo	Authenticate with Namespace using OpenID Connect and create tenants
macos-app-demo	Run applications on macOS/ARM64 instances with pre-start hooks

Getting Started with TypeScript Examples

1. Prerequisites

   • Node.js 18 or later
   • Namespace authentication credentials

2. Install Dependencies

   cd typescript
   npm install

3. Authentication

   The examples require a tenant token, which can be obtained in two ways:

   • Using Namespace CLI (easiest for development):

     curl -fsSL https://get.namespace.so/cloud/install.sh | sh
     nsc login

     The token will be read from ~/Library/Application Support/ns/token.json

   • Using IAM API (for programmatic access): Set up AWS Workload Federation with Namespace using OpenID Connect and use the iam-demo example to obtain a tenant token

4. Common SDK Patterns

   • Compute API: Creating instances, waiting for readiness, streaming logs
   • IAM API: Tenant creation with OpenID Connect federation
   • Kubernetes: Creating ephemeral clusters and obtaining kubeconfig
   • Observability: Streaming instance logs in real-time

Example Details

kubernetes-demo

Creates an ephemeral Kubernetes cluster with ingress manager, waits for initialization, and downloads kubeconfig.

containers-demo

Demonstrates creating compute instances with container workloads and streaming logs from the observability API.

iam-demo

Shows how to authenticate with Namespace using OpenID Connect tokens, create tenants programmatically, and obtain tenant tokens. Requires setting up AWS Workload Federation with an OIDC issuer.

macos-app-demo

Runs applications on macOS/ARM64 instances with custom environment variables, pre-start hooks, and log collection.

Documentation

For more information about the Namespace SDK and APIs, please visit:

• Namespace Documentation
• SDK Reference

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

See LICENSE file for details.