Skip to main content
You bring a working agent in a GitHub repository. Onecortex turns a commit of it into a tested image, runs that image, and puts an authenticated HTTPS endpoint in front of it. The endpoint keeps answering from the version that is live while a new one builds, and while a new one fails.

​
From a push to a live endpoint

  1. A build starts when you click Deploy, when you create the agent, or when you push to its branch with automatic deploys on.
  2. The source is fetched from GitHub at that commit, read only.
  3. agent.yml is validated. A mistake stops the build here, with its line and a corrected snippet. See the agent.yml reference.
  4. The build files are generated. Onecortex writes a Dockerfile and adds the shim beside your code. Your source is never modified.
  5. The image is built for 64 bit ARM Linux, with your dependencies installed from your lockfile.
  6. The image is smoke tested. It has to start, answer a health check, and answer one real invocation with a well formed stream. An image that fails never becomes a version.
  7. The version is released and goes live. The endpoint now answers from it. The previous version is kept, for rollback.
Every stage and what fails at it is on Builds.

​
The words

Organization. Your team’s account, and the boundary of everything in it: agents, keys, members, configuration. Nothing in one organization is visible from another. Agent. One deployable agent from one folder of one repository, with one endpoint. Its ID starts agt_. Build. One attempt to turn a commit into an image. It passes through nine stages and succeeds, fails or is cancelled. A build that fails produces nothing and changes nothing that is live. Version. An image that built and passed its smoke test, numbered 1, 2, 3 per agent. The last ten are kept, and any of them can be put live again. Deployment. Putting a version live. A release is a deployment of a new version, and a rollback is a deployment of an older one, with no build behind it. Runtime. Where your agent runs: an isolated, managed environment per agent that starts on demand and keeps a session’s state while it is in use. Shim. The code Onecortex adds to your image at build time. It finds your agent object, calls it the way its framework expects, and turns what it does into events. The part specific to one framework is its adapter. Gateway. What answers https://api.onecortex.io. It checks the API key, finds the agent, applies rate limits, calls the runtime and streams the events back. Session. A conversation key you choose, or one Onecortex generates. Calls with the same session reach the same running instance of your agent. See Sessions.

​
What a deploy guarantees

  • A failed build never takes down a working agent. The live version keeps serving until a new one has passed its smoke test.
  • An image that fails its smoke test never becomes a version. There is no override.
  • Rollback is to a version that already passed, so it needs no build and is typically done in seconds.
  • Your source is never modified. The build adds files beside it. The GitHub app reads your repository and never writes to it.
  • Every failure names a stage and a cause. A build never just says it failed.

​
Next

Deploy your first agent

The whole path, in about ten minutes.

Write agent.yml

Every field, with examples.
Last modified on September 28, 2026