Glossary

Orka's docs use a handful of terms with precise meanings. This page defines all of them. If a term here is doing real work in a page you are reading, that page should link back here.

Core resources

Task — one unit of work, and the resource you create to make something happen. Three kinds: type: ai (Orka's own AI worker), type: agent (a coding-agent CLI), and type: container (an arbitrary command). See Architecture.

Agent — a reusable configuration a Task points at: which Provider and model to use, a system prompt, allowed tools, and runtime settings. Not a running process — a template.

Provider — an LLM backend (Anthropic, OpenAI, Azure OpenAI) and the Secret holding its API key.

Session — the conversation a Task belongs to. Several Tasks can share one Session so later work sees earlier context.

Skill — a reusable instruction bundle an Agent can load, similar to a prompt library entry with structure.

Tool — something a model can call: a built-in like web_search, or a Tool custom resource describing an HTTP endpoint or MCP server.

Built-in tool — a tool Orka ships, such as web_search, delegate_task, or create_pull_request. Some are selected by name; others are added automatically, for example memory tools on every native AI Task during the warning release. See Built-in tools and migration notes.

Coordinator — an Agent with coordination.enabled that delegates work to other Agents as child Tasks. See Multi-agent coordination.

Memory proposal — a suggested memory an agent submits for review. It becomes durable memory only after a person accepts and applies it. See Memory.

Chat orchestrator — the model behind the chat endpoint that creates, runs, and checks on Tasks for you. See Interactive chat.

Running coding agents

ACP — the Agent Client Protocol, a JSON-RPC protocol that coding-agent CLIs speak over stdin/stdout so a program can drive them instead of a person. Open and external to Orka. Orka speaks it to Codex, Claude Code, GitHub Copilot CLI, and OpenCode.

Agent runtime — one of those CLIs, packaged as a container image Orka knows how to drive. Four are built in; you can register your own with an adapter.

RuntimePool — a controller-owned resource for one long-lived runtime Pod, pinned to an image digest. It scales to zero when idle. Its capacity settings limit concurrent sessions and prompts within that Pod. Reusing a warm pool avoids starting a new runtime Pod for each Task.

RuntimeSession — one agent conversation inside a pool. It has its own private directory and its own operating-system user, so two sessions in one pool cannot read each other's files.

AgentRuntime — a registration for an operator-run agent runtime outside the built-in four, selected from an Agent with runtime.runtimeRef. See Bring your own agent runtime.

Supervisor — the small Orka process inside a runtime Pod that starts agent CLIs, keeps sessions apart, and speaks to the controller. The agent CLI never talks to the cluster directly.

PromptAttempt — the durable record of one prompt sent to a session, including whether it was delivered, so a controller restart never sends the same prompt twice.

Harness — the contract between the controller and the thing executing agent work. Orka supports orka.harness.v2 for built-in ACP runtimes and externally registered runtimes. Its controller identity is fixed to harness-v2. Orka harness v2 uses the orka.harness.v2 controller-to-supervisor contract. The supervisor separately speaks ACP to agent CLIs over stdin/stdout. The harness version describes Orka's contract, independently of the ACP protocol version. See installation ownership.

Producer — anything that creates Tasks: a person with the CLI, CI, a webhook, another agent. When a cluster runs several installations, each producer points at one installation's endpoint.

Safety and correctness

Fail closed — when Orka cannot confirm something is safe, it refuses instead of guessing. A missing runtime image makes Tasks fail with an error rather than silently using a different one; an unverifiable credential scope aborts the request. The opposite, failing open, would keep working with reduced guarantees.

Fence — a set of identifiers attached to a request that must all still match when the request is acted on: which controller, which pool, which Pod, which boot of that Pod, which session, which operation. If anything has been replaced in the meantime, the request is rejected rather than applied to the wrong target. This is what stops a stale message from a restarted controller landing in a new session.

Epoch — a counter that increases each time a controller takes leadership. It is part of every fence, so work authorized by a previous leader cannot be applied by the current one.

Digest-pinned — an image is referenced as repository@sha256:... rather than by tag, so the bytes cannot change under a running pool. Orka rejects tags for agent runtimes.

Scale to zero — an idle pool drops to no Pods and comes back when work arrives.

Drain — taking a pool out of service by letting in-flight sessions finish while refusing new ones. Replacement and scale-down wait for a drain to complete.

Clean-room publication — pushing an agent's work to a git forge from a separate Pod (the publisher) that has the credentials, rather than giving them to the agent. The agent produces a patch; the publisher applies and pushes it. The agent process never holds a token that can write to your repository.

Delivery receipt — the non-secret record in a Task's status.delivery of what happened to its workspace: validated unchanged, published and verified, or why not. A coding-agent Task that changes code is done only when this says so. See Delivery status.

Credentials and network

Provider proxy — the path for agent model traffic: the supervisor's per-session loopback proxy enforces provider routes and model selection, then calls the authenticated provider-auth-proxy service, which forwards to Vekil. Agent processes receive session proxy tokens; Vekil holds the provider API keys. See Provider proxy.

Vekil — the upstream component the provider proxy forwards to, which holds the real provider credentials and speaks the Anthropic, OpenAI, and Gemini APIs. See Provider proxy.

MCP — the Model Context Protocol, the standard way to expose tools to a model. Orka can present Tool resources to agents as MCP servers, scoped to a single prompt.

Transaction token (TxToken) — a short-lived, scoped token that travels with a request so downstream services can verify what was authorized, independent of who is calling. Orka keeps raw tokens out of Task specs, status, and logs. Delegated child tokens are stored in owner-referenced Kubernetes Secrets and mounted read-only into child workers. See Transaction tokens.

TTS — Token Transaction Service, the endpoint that exchanges a token for a narrower-scoped child token when one Task delegates to another. A child's scope must be a subset of its parent's.

Credential broker — the controller endpoint that hands credentials only to the publisher, after checking what the request is for. Keeps forge credentials out of agent Pods.

Outbound access policy — an OutboundAccessPolicy resource that tells a Tool how to reach an external API — by token exchange, through a trusted gateway, or with a person's linked account — without giving the agent the credential. See Outbound access.

Connector and Connection — a ConnectorProvider is an OAuth service, such as GitHub, that people may link; a Connection is one person's link to it, so agents they start can act as them. See Connectors.

Workspaces

Workspace (Task.spec.workspace) — the git repository an agent Task works in: the clone URL, branch, whether it may write, and which Secrets to read or publish with.

Execution workspace (Task.spec.execution.workspace) — a different thing with a confusingly similar name: where the agent process runs, when you want stronger isolation than a normal Pod. Off by default and behind feature flags. See Execution workspaces.

agent-sandbox — an execution workspace provider using kubernetes-sigs/agent-sandbox. See Agent sandbox.

Substrate — an execution workspace provider that runs agents inside gVisor-isolated actors. See Substrate.

Suspend and cold resume — pausing a workspace so its disk survives but nothing runs, then starting fresh against that disk later. Orka never restores process memory, because a restored process would also restore credentials that should have expired.

Other

Gateway — authenticated ingress and reliable outbound delivery for external systems such as Microsoft Teams, Telegram, or A2A clients, through an out-of-tree adapter. See Gateways.

Repository monitor — a durable queue that watches a GitHub repository and runs review, repair, and issue-implementation Tasks. See Repository monitors.

Repository scan — a RepositoryScan that builds a threat model for a repository, finds and validates security issues, and proposes fixes. See Security scanning.

Artifact — a file produced by a Task, stored by the controller and downloadable afterwards.

Execution event — a durable, ordered record of something that happened during a Task. See Execution events.