@@ -5,30 +5,29 @@  # Installing Nimbus -![The global Nimbus network](./images/logo.jpg)+![Nimbus edge infrastructure](./images/logo.jpg) -Nimbus 1.0 is generally available. Install the CLI, or add the SDK to a project.--**CLI**+Nimbus 1.5 adds official packages for every major platform and a container+image.  ```bash-brew install nimbus            # macOS / Linux-npm install -g @nimbus/cli     # any platform with Node 18++brew install nimbus                      # macOS / Linux+npm install -g @nimbus/cli               # Node 18++docker pull ghcr.io/nimbus/cli:1.5       # container ``` -**SDK**+Language SDKs are published for TypeScript, Python, and Go:  ```bash npm install @nimbus/sdk+pip install nimbus-sdk+go get go.nimbus.dev/sdk ```  Verify:  ```bash nimbus --version-# nimbus 1.0.0+# nimbus 1.5.0 ``` -1.0 is a stable release: the `nimbus.toml` schema and the CLI surface are now-covered by semantic versioning.-
                    

                      @@ -5,27 +5,38 @@  # Quickstart -New to Nimbus? Watch the two-minute tour, then follow along below.+Watch the overview, then set up a project with zero-downtime deploys. -<div class="embed embed-video"><iframe src="https://www.youtube.com/embed/jNQXAC9IVRw" title="Nimbus in two minutes" allowfullscreen loading="lazy"></iframe></div>+<div class="embed embed-video"><iframe src="https://www.youtube.com/embed/jNQXAC9IVRw" title="Nimbus 1.5 overview" allowfullscreen loading="lazy"></iframe></div> <p class="embed-caption">Placeholder video. Swap in your product walkthrough.</p>--Initialise and run a live sync that re-deploys on every change:  ```bash nimbus init nimbus run --watch ``` -`--watch` is new in 1.0: Nimbus watches the source, syncs incrementally, and-pushes to your remotes whenever a file changes.+The same flow from each SDK: -Prefer code? The SDK does the same thing:--```js+```ts+// TypeScript import { Nimbus } from '@nimbus/sdk'- const nimbus = new Nimbus({ key: process.env.NIMBUS_KEY })-await nimbus.watch({ source: './data', remote: 'edge-1' })+await nimbus.deploy({ source: 'docs', strategy: 'drain' }) ``` +```python+# Python+from nimbus import Nimbus+nimbus = Nimbus(key=os.environ["NIMBUS_KEY"])+nimbus.deploy(source="docs", strategy="drain")+```++```go+// Go+n := nimbus.New(os.Getenv("NIMBUS_KEY"))+n.Deploy(ctx, nimbus.Deploy{Source: "docs", Strategy: "drain"})+```++`strategy: "drain"` is the 1.5 default: old instances finish in-flight requests+before they are retired.+
                    

                      @@ -5,32 +5,37 @@  # Configuration -![Nimbus regions around the world](./images/architecture.jpg)+![The Nimbus edge fleet](./images/architecture.jpg) -1.0 adds **regions**: a remote can fan out to several locations. Declare them in-`nimbus.toml`:+1.5 introduces **plugins**. Add a plugin block to `nimbus.toml` and Nimbus loads+it during sync:  ```toml [project] name = "docs"-concurrency = 8+concurrency = 12 -[[source]]-type = "local"-path = "./data"+[[plugin]]+name = "image-optimize"+version = "^2.0"++[[plugin]]+name = "html-minify"  [remote.edge] url = "https://edge.nimbus.dev"-regions = ["iad", "fra", "sin"]+regions = ["iad", "fra", "sin", "gru"]+strategy = "drain" ``` -Deploys go to every listed region in parallel. Check what a config resolves to-before you ship it:+Plugins run in order and can transform files before they are deployed. List what+is available:  ```bash-nimbus config show --resolved+nimbus plugin search+nimbus plugin add image-optimize ``` -As of 1.0 Nimbus refuses to start if `NIMBUS_KEY` is stored in a world-readable-file. Keep it in a secret manager or the environment.+The full architecture is in the spec sheet on the+[References](../references/) page. 
                    

                      @@ -5,25 +5,31 @@  # Deployment -Deploy to every region of a remote with one command:+## Zero downtime++1.5 deploys drain by default. Two instances run behind the region's load+balancer and are replaced one at a time:  ```bash-nimbus deploy --remote edge+nimbus deploy --remote edge --strategy drain ``` -Or trigger a deploy over the new REST API, handy from a webhook:+## Observability++Every deploy now emits OpenTelemetry traces and Prometheus metrics. Point them+at your collector:++```toml+[telemetry]+otlp_endpoint = "http://otel-collector:4317"+metrics = true+```++Scrape the node directly if you prefer:  ```bash-curl -X POST https://edge.nimbus.dev/run \-  -H "Authorization: Bearer $NIMBUS_KEY" \-  -H "Content-Type: application/json" \-  -d '{"source": "docs", "regions": ["iad", "fra"]}'+curl https://edge.nimbus.dev/metrics+# nimbus_deploy_duration_seconds{region="iad"} 3.2+# nimbus_active_instances{region="iad"} 2 ``` -Deploys are atomic per region: a region either serves the new manifest fully or-keeps the old one. Watch a rollout live:--```bash-nimbus deploy --remote edge --follow-```-
                    

                      @@ -5,28 +5,25 @@  # Security -![The Nimbus deploy dashboard](./images/dashboard.jpg)+![The Nimbus security dashboard](./images/dashboard.jpg) -1.0 keys are scoped and auditable. Create a key limited to one remote and one-capability:+1.5 adds short-lived deploy tokens on top of long-lived keys. Mint a token that+expires in an hour for CI:  ```bash-nimbus keys create --remote edge --scope deploy+nimbus token mint --remote edge --scope deploy --ttl 1h ``` -Every deploy is signed and recorded. List the audit log through the API:+Plugins are sandboxed and pinned by content hash. Review what a plugin can touch+before adding it:  ```bash-curl https://edge.nimbus.dev/audit \-  -H "Authorization: Bearer $NIMBUS_KEY"+nimbus plugin inspect image-optimize+# capabilities: read-files, write-files+# network:      none ``` -Rotating a key never interrupts serving. The old key stays valid for a grace-window:--```bash-nimbus keys rotate --remote edge --grace 24h-```+<div class="callout callout-warn"><div class="callout-title">Heads up</div>Only add plugins whose <code>network</code> capability is <code>none</code> unless you have reviewed the source. A plugin with network access can exfiltrate the files it processes.</div>  For the full history of security-relevant changes, see the [release changelog (PDF)](../documents/changelog.pdf).
                    

                      @@ -5,27 +5,23 @@  # Troubleshooting -![Tracing a sync through the pipeline](./images/flow.jpg)+![Tracing a deploy across regions](./images/flow.jpg) -**A region is stuck on the old manifest.** Deploys are atomic, so a region that-failed simply kept serving the previous version. Re-run with `--follow` to see-which region errored:+**A plugin failed the sync.** Run it in isolation with verbose logging:  ```bash-nimbus deploy --remote edge --follow+nimbus plugin run image-optimize ./data -v ``` -**`--watch` isn't picking up changes.** On some network file systems inotify-events are missed. Fall back to polling:+**Drain never finishes.** An instance is stuck on a long-lived connection. Cap+the drain window so it force-cycles:  ```bash-nimbus run --watch --poll 2s+nimbus deploy --remote edge --strategy drain --drain-timeout 30s ``` -**Debugging the API.** Add `-v` to any command to print the HTTP requests it-makes:+**Traces aren't showing up.** Confirm the collector endpoint resolves from inside+the node and that `metrics = true` is set under `[telemetry]`. -```bash-nimbus deploy --remote edge -v-```+<div class="callout callout-tip"><div class="callout-title">Tip</div>Add <code>-v</code> to any command to see the exact HTTP calls and plugin steps Nimbus runs.</div> 
                    

                      @@ -5,31 +5,31 @@  # API reference -The 1.0 REST API is stable. All endpoints require a bearer token.+1.5 adds plugin and telemetry endpoints. All require a bearer token or a+short-lived deploy token. -| Method | Path        | Description                    |-| ------ | ----------- | ------------------------------ |-| `GET`  | `/status`   | node health and last deploy    |-| `GET`  | `/manifest` | files currently served         |-| `GET`  | `/audit`    | signed deploy history          |-| `POST` | `/run`      | trigger a deploy               |+| Method | Path         | Description                     |+| ------ | ------------ | ------------------------------- |+| `GET`  | `/status`    | node health and last deploy     |+| `GET`  | `/manifest`  | files currently served          |+| `GET`  | `/metrics`   | Prometheus metrics              |+| `GET`  | `/audit`     | signed deploy history           |+| `POST` | `/run`       | trigger a deploy                |+| `POST` | `/plugins`   | register a plugin for a project | -## Example: trigger a deploy+## Example: deploy with a strategy  ```bash curl -X POST https://edge.nimbus.dev/run \-  -H "Authorization: Bearer $NIMBUS_KEY" \-  -H "Content-Type: application/json" \-  -d '{"source": "docs", "regions": ["iad"]}'+  -H "Authorization: Bearer $NIMBUS_TOKEN" \+  -d '{"source": "docs", "strategy": "drain", "regions": ["iad", "fra"]}' ```--Response:  ```json {-  "deploy": "dpl_5f3a",-  "regions": { "iad": "queued" },-  "manifest": "mf_91c2"+  "deploy": "dpl_8b21",+  "strategy": "drain",+  "regions": { "iad": "draining", "fra": "queued" } } ``` 
                    

                      @@ -6,19 +6,19 @@ # CLI reference  ```text-nimbus init                    scaffold a nimbus.toml-nimbus run [--watch] [--poll]  sync, optionally continuously-nimbus deploy --remote <r>     deploy to every region of a remote-nimbus config show --resolved  print the fully resolved config-nimbus keys create|rotate      manage API keys+nimbus init                       scaffold a nimbus.toml+nimbus run [--watch]              sync, optionally continuously+nimbus deploy --remote <r>        deploy (drain by default)+nimbus plugin search|add|inspect  manage plugins+nimbus token mint                 create a short-lived deploy token ``` -## Common flags+## Deploy flags -| Flag        | Description                                  |-| ----------- | -------------------------------------------- |-| `--watch`   | re-sync on every source change               |-| `--poll`    | use polling instead of file-system events    |-| `--follow`  | stream a deploy's per-region progress        |-| `-v`        | print the HTTP requests being made           |+| Flag               | Default | Description                          |+| ------------------ | ------- | ------------------------------------ |+| `--strategy`       | `drain` | `drain` or `replace`                 |+| `--drain-timeout`  | `60s`   | force-cycle instances after this     |+| `--follow`         | `false` | stream per-region progress           |+| `--regions`        | all     | limit the deploy to some regions     | 
                    

                      @@ -1,11 +1,13 @@ {-  "version": "1.0.0",-  "auth": "bearer",+  "version": "1.5.0",+  "auth": ["bearer", "deploy-token"],   "endpoints": [     { "method": "GET", "path": "/status", "desc": "node health and last deploy" },     { "method": "GET", "path": "/manifest", "desc": "files currently served" },+    { "method": "GET", "path": "/metrics", "desc": "Prometheus metrics" },     { "method": "GET", "path": "/audit", "desc": "signed deploy history" },-    { "method": "POST", "path": "/run", "desc": "trigger a deploy" }+    { "method": "POST", "path": "/run", "desc": "trigger a deploy" },+    { "method": "POST", "path": "/plugins", "desc": "register a plugin" }   ] } 
                    

                      @@ -1,8 +1,8 @@ key,default,description-project.name,,project identifier-project.concurrency,8,number of parallel workers-source.type,local,source kind (local or remote)-remote.regions,,list of region codes to deploy to-run.poll,,polling interval when watching (e.g. 2s)-NIMBUS_KEY,,scoped API key (env or secret manager only)+project.concurrency,12,number of parallel workers+plugin.name,,plugin to load during sync+remote.strategy,drain,deploy strategy (drain or replace)+deploy.drain_timeout,60s,force-cycle instances after this window+telemetry.otlp_endpoint,,OpenTelemetry collector endpoint+telemetry.metrics,false,expose Prometheus metrics 
                    

                      @@ -5,18 +5,19 @@  # References and further reading -- The Nimbus 1.0 REST API reference-- Regions and how atomic per-region deploys work-- The `@nimbus/sdk` TypeScript types+- The plugin author's guide+- Draining, connection lifetimes, and `--drain-timeout`+- Wiring Nimbus telemetry into Grafana++## What people are building++<div class="tweet-embed"><div class="tweet-head"><img class="tweet-avatar" src="./guides/images/avatar.jpg" alt="" /><div><div class="tweet-name">Priya Nair</div><div class="tweet-handle">@priya_builds</div></div><span class="tweet-bird">🐦</span></div><p class="tweet-body">Switched our docs + assets pipeline to Nimbus 1.5 plugins. Image optimization and zero-downtime deploys out of the box. Rollouts went from minutes to seconds.</p><p class="tweet-date">10:24 AM · Mar 4, 2025</p></div>  ## Spec sheet -<div class="embed embed-pdf"><object data="./documents/spec-sheet.pdf" type="application/pdf"><a href="./documents/spec-sheet.pdf">Open the Nimbus 1.0 spec sheet (PDF) →</a></object></div>+<div class="embed embed-pdf"><object data="./documents/spec-sheet.pdf" type="application/pdf"><a href="./documents/spec-sheet.pdf">Open the Nimbus 1.5 spec sheet (PDF) →</a></object></div>  ## Downloads--Everything below is captured in the backup and retrieved from the snapshot on-demand:  - [Spec sheet (PDF)](./documents/spec-sheet.pdf) - [Release changelog (PDF)](./documents/changelog.pdf)
                    

                      @@ -1,25 +1,25 @@-/* Nimbus 1.0 docs theme: clean sans, indigo accent, left-ruled code blocks. */+/* Nimbus 1.5 docs theme: refined slate, larger headings, dark code blocks. */ .doc {-  --accent: #4f46e5;+  --accent: #6366f1;   font-family:     'Inter', system-ui, -apple-system, sans-serif;-  line-height: 1.7;-  color: #1e1b2e;+  line-height: 1.72;+  color: #0f172a; }-.doc h1,-.doc h2,-.doc h3 {+.doc h1 {+  font-size: 2.1rem;+  font-weight: 800;+  letter-spacing: -0.03em;+  color: #0f172a;+}+.doc h2 {   font-weight: 700;   letter-spacing: -0.02em;-  color: #312e81;+  color: #1e293b;+  margin-top: 2em; }-.doc h1 {-  font-size: 1.9rem;-}-.doc h2 {-  margin-top: 1.9em;-  padding-left: 10px;-  border-left: 4px solid #4f46e5;+.doc h3 {+  color: #334155; } .doc a {   color: var(--accent);@@ -30,33 +30,43 @@   text-decoration: underline; } .doc code {-  background: #eef2ff;+  background: #eef0fb;   color: #4338ca;   border-radius: 4px; } .doc pre {-  background: #f5f5ff;-  border-left: 3px solid #4f46e5;-  border-radius: 0 8px 8px 0;+  background: #0f172a;+  color: #e2e8f0;+  border: 1px solid #1e293b;+  border-radius: 10px;+  box-shadow: 0 10px 30px -18px rgba(15, 23, 42, 0.7); } .doc pre code {   background: none;-  color: #1e1b2e;+  color: inherit; } .doc img {-  border-radius: 12px;-  box-shadow: 0 8px 24px -12px rgba(79, 70, 229, 0.4);+  border-radius: 14px;+  box-shadow: 0 14px 36px -18px rgba(15, 23, 42, 0.55); } .doc thead th {-  background: #eef2ff;-  color: #312e81;+  background: #f1f5f9;+  color: #1e293b;+}+.doc th,+.doc td {+  border-color: #e2e8f0; } .doc .embed-video {-  box-shadow: 0 12px 32px -14px rgba(49, 46, 129, 0.5);+  border-radius: 14px;+  box-shadow: 0 16px 40px -20px rgba(15, 23, 42, 0.6); }-.doc blockquote {-  border-left: 3px solid #4f46e5;-  background: #eef2ff;-  border-radius: 0 8px 8px 0;+.doc .callout {+  border-radius: 10px;+  background: #f8fafc;+}+.doc .tweet-embed {+  border-color: #e2e8f0;+  box-shadow: 0 10px 30px -20px rgba(15, 23, 42, 0.5); } 
                    

Binary file. The bytes differ between versions (for example an image or PDF that was replaced).

Binary file. The bytes differ between versions (for example an image or PDF that was replaced).

Binary file. The bytes differ between versions (for example an image or PDF that was replaced).

Binary file. The bytes differ between versions (for example an image or PDF that was replaced).

New in v4. It did not exist in v3.