Builds & the execution surface

When your agent deploys on nyxory, its commands don’t run on your laptop — and they don’t run “in the cluster” with cluster credentials either. They run on a per-project execution surface we operate for you. This page explains that surface, because it’s the part of the platform your agent touches most.

Delegation, not credentials

Conventional remote execution hands the caller a credential — an SSH key, a kubeconfig, a cloud token — and the security model degrades to “protect the credential.”

nyxory inverts that. Your agent holds exactly one thing: a nyx_ token. It never sees a kubeconfig, never sees cloud credentials, never sees the cluster. A tool call expresses intent (“run this command in this project”); the platform authenticates the call, checks that you own the project, and only then performs the privileged act — inside your project’s isolated environment and nowhere else. Every project is its own namespace with its own service account, network policies, and resource quota.

The workspace

Each project has a persistent /workspace where the deploy work happens:

• nyx_shell runs commands there — cloning your repo, inspecting package.json, running a tsc --noEmit before paying for a full build.
• nyx_read_file / nyx_write_file / nyx_edit_file give your agent precise file access — reading configs, writing Kubernetes manifests. Your repo’s source is read-only to the platform: writes under the cloned repo are blocked, so the agent can fix manifests and build artifacts but never silently rewrites code you authored.
• nyx_set_secret stores secrets encrypted at write time. They’re injected into your apps as env vars and never echoed back through any tool.

Builds run off to the side

nyx_build_and_push_image builds your container on our infrastructure — not on your machine, and not in your workspace. Each build runs in a single-purpose, isolated build environment with no access to other tenants, cluster internals, or platform credentials, then pushes to our registry and returns an image_ref your agent pastes into the Deployment manifest.

Two builders are supported:

• Buildpacks (cnb, the default) — zero config. The build detects your stack (Node, Python, Go, …) and produces an image without a Dockerfile.
• dockerfile — used when your repo ships a real Dockerfile, with monorepo subpaths supported via a context argument.

Tags are derived from your git SHA — no latest, fully reproducible rollbacks.

Deploys are explicit

Nothing deploys as a side effect. nyx_deploy_manifests applies exactly the manifests your agent wrote to your project — you can always ask your agent to show them first, and you can export them at any time. Rollout status, history, and logs come back through nyx_app_get, nyx_app_deployments, and nyx_app_logs.

Private repos just work

Public repos clone straight into the workspace. Private GitHub repos go through the nyxory GitHub App: a one-time install in your browser, after which clones — including the clone inside an isolated build — use short-lived tokens minted per operation. No deploy keys, no PATs, nothing to rotate. See Deploy from a private repo.

Next steps

• How nyxory works — the brain call and the full deploy sequence
• Deploy a Next.js app — the flow end to end
• Projects & accounts — how RAM/CPU ceilings shape what the agent can deploy