Welcome to Nanorack

Nanorack is a developer-first platform designed for running containerized services with zero infrastructure overhead.

Describe your application in a nanorack.yaml manifest. Nanorack provisions automated HTTPS, sets up private networking between services, securely delivers secrets, mounts NVMe storage, and streams live logs out of the box.

Quickstart

Deploying a service takes less than a minute. Create a nanorack.yaml manifest in your project directory and deploy using the nanorack CLI.

1. Write your manifest

project: shop
stage: prod
region: dc1
---
name: hello-world
image: nginx:latest
port: 80
cpu: 0.1
memory: 64

public:
  expose: http

2. Deploy via CLI

$ nanorack login
$ nanorack deploy nanorack.yaml
Stage shop/prod [dc1]
  dc1    deploy    hello-world  ok
done: 1 deployed, 0 unchanged, 0 stopped

3. Open your service

Every service with expose: http gets a free HTTPS subdomain automatically. Use nanorack get to find it:

$ nanorack get hello-world
hello-world  status=running replicas=1/1 domain=hello-world-prod-8k3fa.nrck.dev endpoints=

Manifest Reference

A nanorack.yaml file contains a coordinate document defining where the stage lives, followed by one or more service documents separated by ---.

Coordinate Fields

Service Fields

Stages & Service Discovery

Projects in Nanorack are organized into Stages (e.g. prod, staging).

Services within the same stage can communicate with each other using simple internal hostnames. For example, if you run a service named db in your stage, any other service in that stage can connect directly to db.internal.

Services in different stages or different projects are isolated from one another and cannot communicate over the private network.

Secrets Management & Registry Auth

Set stage secrets via CLI without putting credentials in source code:

$ nanorack secret set DB_PASSWORD "your-secret-key"

Secrets are encrypted at rest using per-project data encryption keys (AES-256-GCM) and never touch your image, manifest, or build logs. Secrets are scoped to the stage, so every service in the stage sees the same set, and prod and staging keep separate values.

Static File Delivery

At container boot, secrets arrive as a read-only JSON file bind-mounted at /secrets/secrets.json — a flat map of key-value strings that your application can read during initialization.

Dynamic IMDS API (169.254.169.254)

Workloads can also fetch secrets dynamically at runtime via the host-local Instance Metadata Service (IMDS) at http://169.254.169.254/secrets. This allows applications to pick up rotated secrets without needing a container restart.

Security Requirement (SSRF Guard): Every IMDS request MUST include the X-Nanorack-Metadata: 1 HTTP header. Requests lacking this header are rejected locally to prevent Server-Side Request Forgery (SSRF) vulnerabilities in application code from leaking secrets:

curl -H "X-Nanorack-Metadata: 1" http://169.254.169.254/secrets

Private Registry Authentication

To deploy images from private container registries (such as Docker Hub, GitHub GHCR, or AWS ECR), set your registry credentials via CLI or the web dashboard:

$ nanorack registry set ghcr.io "username" "ghp_yourtoken"

Private registry credentials are encrypted at rest and served over the host-local IMDS metadata API at /registry-auth when pulling container images. Your credentials are never embedded into container images, stored in Nomad job specifications, or exposed in version control.

Public Access & Custom Domains

Configure public internet access for your services in nanorack.yaml:

Web Ingress (HTTP): Set expose: http to route web traffic to your service over HTTPS. Every exposed service gets a free generated subdomain; add domain: api.example.com to serve from your own domain with an automatically issued SSL certificate.

Direct Ports (TCP/UDP): Set expose: port for game servers, database brokers, or non-HTTP protocols. Each replica is assigned its own raw public port — reachable over both TCP and UDP — stable across redeploys; run nanorack get <service> to list the endpoints.

Compute Tiers

Nanorack provides two compute tiers for running your workloads:

App Tier (tier: app, the default): Sandboxed containers designed for web applications, APIs, background workers, and stateless microservices. Allocations start at 0.1 vCPU and 16 MB of memory.

Sys Tier (tier: sys): A dedicated virtual machine with its own kernel, built for databases, game servers, and workloads that need full kernel control. Allocations start at 0.3 vCPU and 128 MB of memory.

Disk Storage & Volumes

All storage runs on the same local NVMe drives — there is no slower tier. The only difference between the two kinds is what happens to the data when you redeploy:

Ephemeral Disk: Set disk: 10 for temporary space (build files, caches, scratch data). It is tied to the deployment — every redeploy or reschedule starts with a clean, empty disk. Never store anything there you can't lose.

Dedicated Volume: Set a volume with size (GB) and mount (path) for storage that is kept — your data survives restarts, redeploys, and reschedules. Use it for databases and anything stateful. A service with a volume runs exactly one replica.

Logs & Metrics

Stream real-time logs or check resource telemetry directly from your terminal:

$ nanorack logs web
$ nanorack metrics web

Both commands read the stage coordinate from the manifest in your current directory. Logs and metrics are also available in the dashboard.

CLI Reference

The nanorack CLI is the primary way to interact with the platform. All commands run from your project directory, where they pick up the stage coordinate from your manifest.