Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Code BuildsBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

A code build runs code you wrote locally instead of a pipeline defined in YAML. Knowing how the platform runs your bundle helps you package it correctly and fix it when it fails to load.

How a Code Build Runs​

A code build's configuration holds settings and a code_bundle block instead of components. The block points to your code bundle, a tar.gz archive of your project, and to the entrypoint to import from it. For the bundle and revision fields, see Code Builds.

Each code build runs on an isolated worker. If the run has no session, the platform creates a temporary one for it. The worker doesn't share its operating system user with other pipelines, because your code can run arbitrary Python. A worker serves only one bundle, so two code builds never share a worker.

Bundle Verification and Limits​

Before it runs your code, the worker downloads the bundle and checks it:

  • The archive's SHA-256 hash must match the sha256 value in the code_bundle block. If the content was altered, the bundle is rejected.
  • The archive must be a safe tar.gz file. The worker refuses absolute paths, paths that leave the bundle, links that point outside it, and device files.
  • The archive can be at most 50 MB, and everything in it can extract to at most 500 MB. These are the default limits.

If a check fails, the build doesn't run. Fix the bundle and push a new revision.

Entrypoint Kinds​

The entrypoint has the format path/to/file.py:attribute. The file must be inside the bundle. For the pipeline, agent, and super_component kinds, the attribute can also be a function or class that takes no arguments. The worker calls it to build the object.

The kind decides how the worker runs the entrypoint:

  • pipeline: The worker runs the pipeline as it is.
  • agent: The worker wraps the agent in a pipeline as a component named agent.
  • super_component: The worker wraps the component in a pipeline as a component named app.
  • function: The worker wraps the function as a component named app. It passes the request payload to the function as keyword arguments and returns the result. A function can be a coroutine function.

The settings' inputs and outputs map onto these component names. Because the worker runs every kind as a pipeline, streaming and tracing work the same way as for YAML pipelines.

Load Errors​

A load error means the bundle is broken, not that the platform had a temporary failure. The worker reports a load error when:

  • The entrypoint isn't in the path/to/file.py:attribute format, or its kind isn't one of the four supported kinds.
  • The entrypoint file isn't in the bundle.
  • Importing the file fails, or the attribute doesn't exist.
  • The object isn't of the declared kind, for example an entrypoint declared as agent that isn't an agent.

To fix a load error, correct the code and push a new revision, or roll back to an earlier revision.

Debug Runs​

Debug runs aren't supported for code builds. A code build has no components to break at or snapshot, so a debug request returns a 400 error. To investigate a run, use traces instead. For details, see Trace Your Pipeline.