# The machine and the policy file decide an open-source agentic enterprise architecture

> An agentic enterprise architecture is what an agent run depends on, and two choices decide most of its risk: a machine per session, and a policy file beside the agent. Kortix is the open-source CompanyOS, and both choices arrive as a file and a machine a team can inspect.

URL: https://agenticenterpriseguide.com/agentic-enterprise-architecture

## The two files a session reads before it does anything

One sets what the agent may use, the other sets what it is told.

### kortix.yaml

`kortix.yaml`

```yaml
default_agent: worker
agents:
  worker:
    permission: allow
    workspace: { project_repository: true }
```

Source: https://github.com/kortix-ai/suna/blob/dev/packages/starter/templates/base/kortix.yaml

### agents/worker.md

`agents/worker.md`

```
You are **Worker**, the general-purpose agent of **{{projectName}}**.
My Kortix, the built-in agent people talk to, routes each task to the
project agent that fits it.
```

Source: https://github.com/kortix-ai/suna/blob/dev/packages/starter/templates/base/agents/worker.md

## The boot sequence that resolves the harness adapter

`harness/README.md`

```ts
const cfg = loadConfig()                 // reads KORTIX_HARNESS, then pi's env
const selected = resolveHarness(cfg)     // piDefinition
const runtime = selected.createService(cfg, projectEnv)
await runtime.lifecycle.start()
```

Source: https://github.com/kortix-ai/suna/blob/dev/apps/kortix-sandbox-agent-server/src/harness/README.md

One module imports the adapter, and every other module talks to the contract in front of it.

## What an agent run actually depends on

An agentic enterprise architecture is the list of systems a single agent run depends on, and most of that list is not the model. A run needs a machine, a loop that calls the model, a manifest, connectors with credentials, memory, and a person who can stop it. Each of those has to sit somewhere a reviewer can name.

Two of those systems decide how expensive the rest are to change. The first is the machine. Every session can get its own, on its own branch, or sessions can share a long-lived host with every other agent in the company. The second is the policy. The rule that binds an agent lives either in the same repository as the agent, or in a console the company rents.

An architecture review that stops at tiers, with a box for orchestration and another for knowledge, has answered neither question. Take the parts in the order a session touches them and name the artifact that holds each one. The diagram then becomes a checklist a platform team can argue about for an hour.

## The machine, and the branch that makes the work reviewable

Kortix answers the first decision in its FAQ. Every session boots an isolated Linux cloud computer with your repo and your tools already on it, on its own git branch. The session id, the sandbox id and the branch name are one and the same string. The branch is therefore the session's identity, written where git can read it.

Isolation earns its place for an unglamorous reason. On a shared host the working directory is a shared surface: one environment file, one package cache, one credential a second team's agent can read. A rule that leaks in one session leaks into the next. A machine per session turns that class of accident into a failure with a boundary around it. The machine is destroyed with everything on it when the session ends.

The branch carries the other half of the argument. A session that starts on its own branch produces a diff from its first edit. Review therefore starts at the first edit rather than at handoff, and the diff is the state the work is always in. An architect who has watched one session work can predict what month two of the program looks like.

## The harness is a module, and the model loop is inside it

The harness is the code that runs the loop. It builds the prompt, calls the model, executes the tool calls the model asks for, and writes the transcript. Every session has one. It is also the component most likely to be replaced within two years. It is the part tied to whichever model and pricing a vendor ships this quarter.

Kortix keeps that loop behind one boundary. In the sandbox agent server, `harness.ts` is the only module that imports a concrete adapter. Boot resolves the adapter once, and an unknown id fails the boot instead of falling back to something else. The boot sequence, four lines long, is that resolution; the folder beside it holds the contract, the adapter and the code both share.

One adapter is registered today, and there is no switch mid-session: one box, one harness, for the life of the box. The hedge is for year two rather than for a demo. Hosted tools are written once as harness-neutral modules. The transcript the platform publishes has a contract of its own, so a new loop arrives as an adapter behind the same interface. It does not arrive as a rewrite of everything around it.

## The manifest holds the roster and the grants

The manifest is `kortix.yaml`. The starter version is 35 lines, checked in November 2026. Its first comment says what the file is for: agents, what each may use, triggers and sandboxes, committed beside your files. `default_agent: worker` names the agent a session runs when nobody names one. `skills: {}` is an empty registry, and the worker block in the same file carries the prompt file, the permission mode and the grants.

The grants are the part a reviewer reads twice. `permission: allow` sits above `tools: all`, `skills: all`, `connectors: all` and `secrets: all`, so the starter agent may use everything the project has. That is the honest shape of a default. A new project starts open, the first change a team makes is to narrow it, and the diff shows what moved.

`workspace: { project_repository: true }` is what puts the repository inside the session's machine, so the agent works on the real files rather than a copy. A company that wants the manifest to mean something keeps it in the repository the agents work in, where the change history reaches it.

## Two files, and what editing each one changes

The manifest and the agent prompt do most of the work, and they fail in different ways. Editing `kortix.yaml` changes what an agent may use: its model, its permission mode, the tools, skills, connectors and secrets it enables, and whether it gets the repository. A mistake there widens what a system allows.

Editing `agents/worker.md` changes what the agent is told. The file opens by naming the agent and the project, then describes how tasks are routed, how memory is read, and when the agent stops to ask. A mistake there produces work that is wrong in a plausible way, which is the harder failure to catch later.

The split is worth preserving because the two edits need different reviewers. A grants change is a security question, and it can be reviewed from the diff alone. A prompt change is a domain question, and the answer is often that the written procedure is out of date. Both arrive as one change request against one repository, so the review happens once and the record sits beside the change.

## Connectors, and where the credential lives

Connector credentials are brokered server-side and never enter the machine; secrets are encrypted per project. The sentence matters more than it looks. A token written into the sandbox as an environment value can be read by any command the agent runs. An agent runs a lot of commands. Brokering keeps the token on the side of the boundary the agent cannot reach.

The systems an enterprise asks about first are the ones that hold a record: the ticketing tool, the CRM, the ERP, the data warehouse, the mailbox. Each arrives as a connector an agent enables by name in its manifest block, so the grant is reviewed next to the agent that holds it. People are not a connector. Members, groups and who may run which agent are account settings, separate from anything an agent can reach. [Read the docs](https://kortix.com/docs) for the connector list and the account model.

## Memory that survives the session

Memory decides whether year two costs less than year one. The starter keeps the project brain in `memory/`, with `MEMORY.md` as the index: purpose, connections, conventions, decisions and gotchas. The file says of itself that it lives in git and is curated through change requests.

Placement is the whole argument. Memory held in a vendor account gets rebuilt at the next vendor change, and the rebuild stays invisible until the answers go wrong. Memory held as markdown is a diff a person can read. A wrong belief can then be argued with like any other line in the repository. Agents read the index with their file tools before they start, which keeps the correction and the work on the same route.

## The gate: allow, ask or block, then a diff

Policy is the second decision, and Kortix states it plainly. You set allow, ask or block per action, and a rule can match on a glob, a regular expression, or the arguments of the call itself. The last part is what changes an architecture review. An approval that matches on a tool name is coarse; one that matches on the amount being moved is a control.

Above the rules sits a second gate. Session work reaches `main` through a change request, and merge is default-deny for an agent unless an admin grants it. The person who merges is making a decision rather than acknowledging a notification.

The default is the honest part of any gate, and the question to put to a vendor is what runs when no rule matches. An architecture that assumes a rule is already there is relying on a setting nobody wrote down. The first commit on a new project should therefore be the policy, not the agent.

## What this architecture refuses

It refuses a shared, long-lived agent host. A host that outlives its sessions collects state nobody declared: a package installed for one experiment, a checkout of a repository, a credential in a profile file. Ending the machine with the session is cheaper than auditing what the machine kept.

It also refuses credentials inside the machine. A design that puts the token in the sandbox has traded a boundary for convenience. The trade stays invisible until the first incident, when somebody has to work out which sessions read the token, and for how long.

The last refusal is policy outside the repository. A rule in a console cannot be reviewed with the agent it binds. It cannot be diffed when someone changes it, and it does not travel if the company changes platforms. A rule in the repository is the only form that survives all three.

## Where a reader goes next

An architecture earns its name once somebody writes the first policy against it. [The governance page](/agentic-enterprise-governance) sets out the five rules a first agent needs, and [the build page](/how-to-become-an-agentic-enterprise) puts them in the order a team commits them. [The definition page](/what-is-an-agentic-enterprise) covers what the term promises before any of this work starts.

## Four questions that come before the first architecture decision

### What are the four pillars of agentic architecture?

There is no single canonical set. Most published versions name the agents, the model and orchestration layer, the tools and data they reach, and the controls around them. A pillar list earns its place only when each pillar maps to a file or a system a reviewer can open.

### What is an agentic AI architecture for enterprises?

It is the set of systems one agent run depends on inside a company's own controls: a machine per session, the loop that calls the model, a manifest of agents and grants, connectors, memory, and a person who approves the work. Each of those lives somewhere a reviewer can name.

### What are agentic architectures?

Agentic architectures are designs for software that takes a goal, acts in real tools, and reports what it changed. The design answers four things a chat window never does: where the run happens, what it may touch, what it remembers, and who approves the result.

### What is an agentic enterprise?

An agentic enterprise is a company that runs work through agents it can account for: a roster it can read, rules per action, and a record of who approved what. Agents do the work, and people keep the boundary.

## Start where the risk is decided

One repository, one manifest, one policy file a reviewer can open.

[Try Kortix](https://kortix.com) · [Read the governance page](https://agenticenterpriseguide.com/agentic-enterprise-governance)