> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How Onecortex works

> What happens between a push to your repository and a live endpoint, what each word in Onecortex means, and the guarantees a deploy keeps.

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.

```mermaid theme={null}
flowchart LR
  repo["Your repository<br/>agent.yml + code"] --> build
  subgraph build["The build"]
    direction LR
    fetch["Fetch source"] --> validate["Validate agent.yml"] --> gen["Generate build files"] --> image["Build image"] --> smoke["Smoke test"]
  end
  smoke -- passes --> version["Version N"]
  smoke -- fails --> failed["Build failed:<br/>stage and cause"]
  version --> deploy["Deployment:<br/>Version N goes live"]
  deploy --> runtime["Your agent's runtime"]
  caller["Your app"] -- "POST /invoke<br/>+ API key" --> gateway["Gateway"]
  gateway --> runtime
  runtime -- "events, streamed" --> gateway
  failed -. "live version keeps serving" .-> runtime
```

## 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](/deploy/auto-deploy) 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](/agent-yml).
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](/deploy/versions-and-rollback).

Every stage and what fails at it is on [Builds](/deploy/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](/build/streaming). 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](/production/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](/build/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

<Columns cols={2}>
  <Card title="Deploy your first agent" icon="rocket" href="/quickstart">
    The whole path, in about ten minutes.
  </Card>

  <Card title="Write agent.yml" icon="file-code" href="/agent-yml">
    Every field, with examples.
  </Card>
</Columns>