How Nyxory works

Nyxory is a recipe + primitives system, not a deploy state machine. The product surface is three things your agent calls; the cookbook does the rest.

The three endpoints

nyx_deploy_start(repo, hint?)

The starting gun. Scans the repo, returns a context bundle — repo digest, your project’s current state, quota headroom, the public URL pattern — plus the cookbook recipes relevant to the detected (or hinted) stack. Your agent goes from there.

It does not start a deploy. There’s no orchestration on our side; the name is about the agent starting the workflow with everything it needs in hand.

nyx_help(question, context?)

Bidirectional. Your agent hits something it can’t reason through alone — a private repo without a deploy key, a build failing on a specific error, an unfamiliar runtime config — and asks back. We return the cookbook content that addresses it. If the question is genuinely unsupported, we surface “escalate to user” so your agent can ask you.

The nyx_* primitives

The actual tools your agent uses to do work: nyx_app_create, nyx_secret_set, nyx_domain_add, nyx_app_deployments, and so on. These are the verbs. The cookbook tells your agent which verbs to use, in what order, with what care.

See the full set in Reference / MCP tools.

A typical sequence

sequenceDiagram
  participant Agent
  participant Nyxory as Nyxory MCP
  participant Cookbook

  Agent->>Nyxory: nyx_deploy_start(repo)
  Nyxory->>Cookbook: lookup(stack)
  Cookbook-->>Nyxory: recipes + context
  Nyxory-->>Agent: recipes + project state

  Agent->>Nyxory: nyx_app_create(...)
  Agent->>Nyxory: nyx_secret_set(...)

  Note over Agent: stuck on a specific subtask
  Agent->>Nyxory: nyx_help(question)
  Nyxory->>Cookbook: relevant recipe
  Cookbook-->>Nyxory: recipe content
  Nyxory-->>Agent: recipe

  Agent->>Nyxory: ...continues
  Nyxory-->>Agent: live URL

The agent never blocks on us beyond what a tool call takes. There’s no polling, no state machine drifting in the background, no “wait for Nyxory to finish step 3”.

Why this shape

• Recipes are static and versioned with the backend. A recipe that worked yesterday works today. We don’t generate plans at runtime — predictability and debuggability matter more than novelty.
• Your agent retains autonomy. The recipe is a suggestion shaped by experience, not an SOP. When the agent sees something the recipe didn’t anticipate, it deviates.
• Reproducible. Two deploys of the same repo by the same agent produce equivalent results. They may differ on the margins (a manifest field, a default), but both work.

Next: The cookbook →