Something went wrong. Try again.
Deployment and lifecycle management for Nix
Something went wrong. Try again.
1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144114511461147114811491150115111521153115411551156115711581159116011611162116311641165116611671168116911701171117211731174117511761177117811791180118111821183118411851186118711881189119011911192119311941195119611971198119912001201120212031204120512061207120812091210121112121213121412151216121712181219122012211222122312241225122612271228122912301231123212331234123512361237123812391240124112421243124412451246124712481249125012511252{ "components": { "responses": {}, "schemas": { "DeploymentInfo": { "properties": { "deployed_at": { "format": "date-time", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "garden_sid": { "type": "string", "x-struct": null, "x-validate": null }, "result": { "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "seeds": { "default": [], "items": { "$ref": "#/components/schemas/DeploymentSeedInfo" }, "type": "array", "x-struct": null, "x-validate": null }, "sid": { "type": "string", "x-struct": null, "x-validate": null }, "skipped": { "default": false, "description": "The request matched an existing deployment and no new one was created", "type": "boolean", "x-struct": null, "x-validate": null }, "state": { "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "sid", "garden_sid", "state" ], "title": "DeploymentInfo", "type": "object", "x-struct": "Elixir.SowerClient.Orchestration.DeploymentInfo", "x-validate": null }, "DeploymentSeedInfo": { "properties": { "log": { "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "name": { "type": "string", "x-struct": null, "x-validate": null }, "result": { "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "seed_sid": { "type": "string", "x-struct": null, "x-validate": null }, "seed_type": { "type": "string", "x-struct": null, "x-validate": null }, "state": { "nullable": true, "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "seed_sid", "name", "seed_type" ], "title": "DeploymentSeedInfo", "type": "object", "x-struct": "Elixir.SowerClient.Orchestration.DeploymentInfo.SeedInfo", "x-validate": null }, "DirectDeployment": { "properties": { "action": { "description": "Requested action: stage, activate, or restart. Defaults to activate unless overriding. Without override, the exact action must be permitted by the garden's direct policy, including windows and confirmation requirements; restart does not require override. Required explicitly when overriding policy.", "enum": [ "stage", "activate", "restart" ], "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "force": { "default": false, "description": "Deploy even when an identical closure was already deployed", "type": "boolean", "x-struct": null, "x-validate": null }, "garden": { "description": "Garden sid (grdn_…) or garden name", "example": "grdn_2f8b1c", "type": "string", "x-struct": null, "x-validate": null }, "override": { "default": false, "description": "Break glass: bypass deployment policy on both server and garden. Requires override permission, action, reason, and a connected garden advertising override support. Unsupported gardens are rejected with an upgrade-required error. Seed/action support and activator privileges still apply.", "type": "boolean", "x-struct": null, "x-validate": null }, "reason": { "description": "Why policy is being bypassed. Recorded in the audit trail.", "nullable": true, "type": "string", "x-struct": null, "x-validate": null }, "seed": { "description": "Seed sid to deploy", "example": "seed_9a3d21", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "garden", "seed" ], "title": "DirectDeployment", "type": "object", "x-struct": "Elixir.SowerClient.Orchestration.DirectDeployment", "x-validate": null }, "GardenRegistration": { "description": "HTTP registration request for a new garden", "properties": { "name": { "description": "Name of garden", "type": "string", "x-struct": null, "x-validate": null }, "public_key": { "description": "PEM-encoded RSA public key for private_key_jwt authentication", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "name", "public_key" ], "title": "GardenRegistration", "type": "object", "x-struct": "Elixir.SowerClient.GardenRegistration", "x-validate": null }, "Nix Cache": { "description": "A Nix binary cache", "example": { "public_key": "my.cache.org:1111111111111111", "sid": "example4ser3adju75ddusbr", "url": "https://my.cache.org" }, "properties": { "public_key": { "description": "Trusted public key for signed NARs", "type": "string", "x-struct": null, "x-validate": null }, "sid": { "description": "sid of the nix cache", "readOnly": true, "type": "string", "x-struct": null, "x-validate": null }, "url": { "description": "URL to binary cache", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "sid", "url", "public_key" ], "title": "Nix Cache", "type": "object", "x-struct": "Elixir.SowerClient.Nix.Cache", "x-validate": null }, "OAuthCredentials": { "description": "OAuth client registration returned to a garden after registration", "properties": { "client_id": { "description": "Boruta OAuth client ID", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "client_id" ], "title": "OAuthCredentials", "type": "object", "x-struct": "Elixir.SowerClient.Auth.OAuthCredentials", "x-validate": null }, "Seed": { "description": "A seed is an installable unit", "example": { "artifact": "/nix/store/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa-nixos", "name": "myhost", "seed_type": "nixos", "sid": "example4ser3adju75ddusbr", "tags": [] }, "properties": { "artifact": { "description": "Artifact of the seed", "type": "string", "x-struct": null, "x-validate": null }, "name": { "description": "Name of the seed", "type": "string", "x-struct": null, "x-validate": null }, "seed_type": { "description": "Type of the seed", "enum": [ "nixos", "home-manager", "nix-darwin", "service" ], "type": "string", "x-struct": null, "x-validate": null }, "sid": { "description": "sid of the seed set by the server", "nullable": true, "readOnly": true, "type": "string", "x-struct": null, "x-validate": null }, "tags": { "default": [], "description": "Tags associated with the seed", "items": { "$ref": "#/components/schemas/SeedTag" }, "type": "array", "x-struct": null, "x-validate": null } }, "required": [ "name", "seed_type", "artifact" ], "title": "Seed", "type": "object", "x-struct": "Elixir.SowerClient.Seed", "x-validate": null }, "SeedTag": { "description": "A tag associated with a seed", "example": { "key": "environment", "value": "production" }, "properties": { "key": { "description": "Tag key", "type": "string", "x-struct": null, "x-validate": null }, "value": { "description": "Tag value", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "key", "value" ], "title": "SeedTag", "type": "object", "x-struct": "Elixir.SowerClient.SeedTag", "x-validate": null }, "TokenInfo": { "description": "Information about an authenticated access token", "example": { "description": "CI/CD token", "expires_at": "2025-12-31", "permissions": [ "seed:read", "seed:write" ], "sid": "example4ser3adju75ddusbr" }, "properties": { "description": { "description": "Human-readable token description", "type": "string", "x-struct": null, "x-validate": null }, "expires_at": { "description": "Token expiration date", "format": "date", "type": "string", "x-struct": null, "x-validate": null }, "permissions": { "description": "Permission roles (e.g., seed:read, seed:write)", "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null }, "sid": { "description": "Token identifier", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "sid", "description", "permissions", "expires_at" ], "title": "TokenInfo", "type": "object", "x-struct": "Elixir.SowerClient.Auth.TokenInfo", "x-validate": null } }, "securitySchemes": { "authorization": { "bearerFormat": "sower", "description": "sower api token", "scheme": "bearer", "type": "http" } } }, "info": { "title": "sower", "version": "0.12.14" }, "openapi": "3.0.0", "paths": { "/api/v1/auth/verify": { "get": { "callbacks": {}, "description": "Validates the Bearer token and returns token metadata", "operationId": "VerifyToken", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TokenInfo" } } }, "description": "Token info response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" } }, "summary": "Verify access token", "tags": [] } }, "/api/v1/deployments": { "post": { "callbacks": {}, "operationId": "NewDeployment", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DirectDeployment" } } }, "description": "Direct deployment params", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentInfo" } } }, "description": "Deployment response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "403": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Denied by policy" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Garden or seed not found" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Ambiguous garden name or garden upgrade required" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Invalid request" } }, "summary": "Deploy a seed directly at a garden", "tags": [] } }, "/api/v1/deployments/{sid}": { "get": { "callbacks": {}, "operationId": "GetDeployment", "parameters": [ { "description": "Deployment SID", "example": "dply_example4ser3adju75d", "in": "path", "name": "sid", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentInfo" } } }, "description": "Deployment response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Deployment not found" } }, "summary": "Get a deployment", "tags": [] } }, "/api/v1/gardens/register": { "post": { "callbacks": {}, "operationId": "RegisterGarden", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GardenRegistration" } } }, "description": "Garden registration params", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "properties": { "oauth_credentials": { "$ref": "#/components/schemas/OAuthCredentials" }, "sid": { "description": "Garden SID", "type": "string", "x-struct": null, "x-validate": null } }, "required": [ "sid", "oauth_credentials" ], "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Garden registration response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "422": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Validation error" } }, "summary": "Register a new garden", "tags": [] } }, "/api/v1/gardens/{garden}/latest-seed": { "get": { "callbacks": {}, "operationId": "LatestGardenSeed", "parameters": [ { "description": "Garden SID or unambiguous name", "in": "path", "name": "garden", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Seed name", "in": "query", "name": "name", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Seed type", "in": "query", "name": "seed_type", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seed" } } }, "description": "Latest matching seed" }, "204": { "description": "No matching subscription or seed" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Garden not found" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Garden name is ambiguous" } }, "summary": "Find the latest seed for a garden's oldest matching subscription", "tags": [] } }, "/api/v1/nix/caches": { "get": { "callbacks": {}, "operationId": "ListNixCaches", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Nix Cache" }, "type": "array", "x-struct": null, "x-validate": null } } }, "description": "Nix Cache response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" } }, "summary": "List Nix Caches", "tags": [] } }, "/api/v1/seeds": { "get": { "callbacks": {}, "operationId": "ListSeeds", "parameters": [ { "description": "Seed name", "example": "host1", "in": "query", "name": "name", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Seed type, one of [nixos, home-manager, nix-darwin, service]", "example": "nixos", "in": "query", "name": "seed_type", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/Seed" }, "type": "array", "x-struct": null, "x-validate": null } } }, "description": "Seed response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Seed error response" } }, "summary": "List Seeds", "tags": [] }, "post": { "callbacks": {}, "operationId": "NewSeed", "parameters": [ { "description": "Rename the seed if matching artifact found", "example": "true", "in": "query", "name": "rename", "required": false, "schema": { "type": "boolean", "x-struct": null, "x-validate": null } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seed" } } }, "description": "Seed params", "required": false }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seed" } } }, "description": "Seed response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "409": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Seed conflict response" } }, "summary": "New Seed", "tags": [] } }, "/api/v1/seeds/latest": { "get": { "callbacks": {}, "operationId": "LatestSeed", "parameters": [ { "description": "Filter by tags (key=value format, can repeat)", "in": "query", "name": "tags", "required": false, "schema": { "items": { "type": "string", "x-struct": null, "x-validate": null }, "type": "array", "x-struct": null, "x-validate": null } }, { "description": "Seed name", "example": "host1", "in": "query", "name": "name", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } }, { "description": "Seed type", "example": "nixos", "in": "query", "name": "seed_type", "required": false, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seed" } } }, "description": "Seed response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Seed error response" } }, "summary": "Find latest Seed", "tags": [] } }, "/api/v1/seeds/{sid}": { "get": { "callbacks": {}, "operationId": "GetSeed", "parameters": [ { "description": "Seed SID", "example": "example4ser3adju75ddusbr", "in": "path", "name": "sid", "required": true, "schema": { "type": "string", "x-struct": null, "x-validate": null } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Seed" } } }, "description": "Seed response" }, "401": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "properties": { "error": { "type": "string", "x-struct": null, "x-validate": null } }, "type": "object", "x-struct": null, "x-validate": null } } }, "description": "Seed error response" } }, "summary": "Get Seed", "tags": [] } } }, "security": [ { "authorization": [] } ], "servers": [ { "url": "http://localhost:4002" } ], "tags": []}