MachineMachine
MachineMachine
MachineGetting startedQuickstartAccounts & access
Your project
AgentsLegacy kortix.tomlManifest referenceModelsAgent permissionsSecrets
Running work
Change requestsRuntime & sandboxSessions
Connect & automate
ComputersConnectorsInkbox: iMessage, SMS, email & callsMCP serverPixio: images, video & audioRemindersSlack & channelsMicrosoft TeamsTriggers
Feature flags
Apps

Develop

CLI
TypeScript SDKFull exampleAuthenticationSign in with KortixSessionsAppsReact hooksSDK reference
Machine as a BackendAPI reference
GitHub

Running work

How work moves from prompt to merged change, and the three ways it starts.

Kortix does work inside a session: a branch and a sandbox for one unit of work. A session ends when its change request (CR) merges back to the default branch. This page walks through the loop, then shows the three ways a session can start.

Sessions

A branch and a sandbox for one unit of work.

Change requests

The reviewed merge back to the default branch.

Runtime

Env vars, tokens, and the sandbox image a session runs in.

What happens when a session starts

  1. Kortix creates the session row and cuts a branch from the default branch. The branch name is the session id.
  2. Kortix resolves a sandbox image: the default image, or your own Dockerfile (for example Dockerfile.ml) if the manifest declares one.
  3. The sandbox boots. Its daemon, kortix-agent, clones the repo to /workspace. It starts OpenCode. Session status becomes running.
  4. The agent works. It uses secrets through the environment variables Kortix sets, then commits and pushes to the session branch.
  5. The agent opens a change request. You review it and merge it — the only way work reaches the default branch.

:::info[Git is the only durable record] Stopping a session pauses the sandbox but keeps its files. Deleting a session destroys the sandbox for good. Only work committed and pushed to the branch survives, and only a merged change request makes it permanent. :::

Three ways work runs

A session starts one of three ways.

ModeHow it works
On-demandYou ask in chat and get the result now.
Human-assistedThe agent works and checks in with you for the calls that matter.
AutomatedA trigger — a schedule or webhook — starts the session end to end.

Related

Projects

A git repo with a manifest.

Agents

A markdown persona with scoped tools.

Models

Which model a session uses, and who pays.

Triggers

Schedules and webhooks that start sessions.

Connectors

Scoped reach into external apps.

Slack & channels

Chat surfaces that start sessions.

Computers

Machines distinct from session sandboxes.

Accounts

Principals, roles, and assignments — who can do what.
PreviousSecretsNextChange requests

On this page

What happens when a session startsThree ways work runsRelated