Build contract
A build is an immutable attempt to turn one repository commit and one set of server settings into one deployable artifact. After the build starts, changing a branch, editing an environment variable, or updating server settings does not change that build. Those changes apply to the next build that uses them.| Property | Contract |
|---|---|
| Source revision | Resolved to an exact commit before build work begins. |
| Server configuration | Entrypoint, dependency file, build-relevant settings, and environment scope are captured at build start. |
| Output | A successful build produces a new artifact and manifest. A failed build does not modify the live deployment. |
| Mutability | Build records and artifacts are historical. Rebuild instead of editing an existing build. |
| Promotion | Build success makes an artifact eligible for deployment; it does not always change live traffic. |
Debug build problems from the build record, not from the current branch tip.
The current branch may have moved since the failed build started.
Build states
| State | Meaning |
|---|---|
queued | Horizon has accepted the build request and is waiting to start work. |
building | Horizon is installing dependencies, packaging the server, inspecting the manifest, or publishing the artifact. |
succeeded | The artifact is ready to deploy. |
failed | The build did not produce a deployable artifact. Open build logs for the failing step. |
canceled | The build was stopped before completion. |
What starts a build
Default branch push
A push to the configured default branch can create a production build.
Pull request
A pull request can create a preview build with preview-scoped environment
variables.
Manual build
A user with server edit access can start a build from the dashboard.
Configuration change
Changes to build-relevant settings, such as the entrypoint or dependency
file, take effect on the next build.
What does not start a build
Not every server change produces a new artifact. Some changes affect gateway or dashboard state without rebuilding Python code.| Change | Usually requires a new build? | Why |
|---|---|---|
| Source code change | Yes | The artifact must include the new code. |
| Entrypoint or dependency file change | Yes | Horizon must package and inspect with the new build configuration. |
| Environment variable value change | Yes, for hosted server runtime behavior | Existing artifacts keep the values they were built with. |
| Server access grant change | No | Access metadata is evaluated by Horizon and can update without changing Python code. |
| Server display name or description | No | Dashboard metadata does not affect the artifact. |
| Capability policy change | Redeploy may be required for hosted capability enforcement | The deployed endpoint must use the updated policy metadata. |
Build inputs
| Input | Contract |
|---|---|
| Repository revision | Horizon builds from the selected commit. Builds are immutable once started. |
| Entrypoint | Defaults to main.py unless the server is configured with another entrypoint. |
| Dependencies | Horizon installs dependencies from the configured dependency file or discovered Python project files. |
| Environment variables | Production builds use production variables. Preview builds use preview variables plus branch overrides. |
| Access settings | Authentication and authorization metadata are packaged with the deployment path used by the gateway. |
Source resolution
Horizon records the repository, branch context, and exact commit for every hosted build. Branch names are useful for starting builds, previews, and promotion workflows, but the artifact is tied to the commit that was resolved at build start. This matters when a pull request receives several pushes quickly. An older build may finish after a newer build. Use the deployment page to confirm which artifact is selected before assuming the latest completed build is live.Build output
A successful build produces:- A deployable artifact.
- A discovered MCP manifest for tools, resources, prompts, and templates.
- Build logs for audit and debugging.
- Metadata that Horizon uses for deployment, routing, and observability.
Concurrency and ordering
Horizon prevents conflicting deployment updates for the same deployment target, but build completion order can still differ from commit order. Treat promotion as the moment a deployment changes, not build completion.| Scenario | Expected behavior |
|---|---|
| Two preview builds run for the same branch | The deployment should serve the artifact selected by the preview workflow, not simply whichever build logs you opened last. |
| A default-branch build succeeds while a preview build fails | The production artifact can still be healthy; preview failure is scoped to its branch context. |
| A build fails after a previous build succeeded | The previous successful artifact remains available for deployment or rollback. |
Manifest inspection
Build inspection loads the server entrypoint and records the MCP capabilities Horizon can see. The dashboard, Inspector, ChatMCP, remix composition, and capability policies all depend on that manifest. If a capability is missing after a successful build, check whether the server registers the tool, resource, prompt, or template during import or startup. Conditional registration can make local behavior differ from build inspection, especially when it depends on environment variables.Troubleshooting
Dependency installation fails
Dependency installation fails
Check the dependency file path, Python version requirements, private package
credentials, and any build-time environment variables.
The entrypoint cannot be loaded
The entrypoint cannot be loaded
Confirm the configured file exists in the repository revision and can be
imported without running interactive code.
The manifest is empty or incomplete
The manifest is empty or incomplete
Make sure tools, resources, and prompts are registered before the server is
inspected. Build logs usually show whether inspection succeeded.
A new environment variable is missing
A new environment variable is missing
Start a new build after saving the variable. Existing artifacts keep the
environment available when they were built.
A successful build did not change production traffic
A successful build did not change production traffic
Confirm whether the build was for a preview deployment, whether automatic
promotion is enabled, and which artifact the live deployment currently
selects.
A tool disappeared after a build
A tool disappeared after a build
Compare the manifest on the previous successful build with the new build.
Then check registration code and environment-dependent imports.
Related docs
Hosted servers
Start with the hosted-server contract across source, deployments, access,
runtime, and observability.
Deployments
Serve successful builds as live or preview deployments.
Environment variables
Manage production, preview, and branch-scoped variables.
Compute model
Understand how artifacts run after deployment.