> ## Documentation Index
> Fetch the complete documentation index at: https://docs.karta.sh/llms.txt
> Use this file to discover all available pages before exploring further.
# Glossary
> Definitions for the core Karta terms used across the docs.
This glossary defines the terms that carry product, API, security, and
operations meaning in the Karta docs. These definitions are also used for inline
hover tooltips across prose pages.
## Core model
### Karta platform
Karta is a managed agent platform for running harness-native agent projects for
users, teams, and jobs. It adds durable kartas, sessions, releases, identity,
isolation, metering, budgets, webhooks, audit, and API surfaces around those
projects.
Aliases: Karta; Karta, the platform
### durable computer
A durable computer is a long-lived execution and workspace unit behind an agent
endpoint, scoped to one chosen user, role, job, account, or fleet member.
### durable workspace
A durable workspace is the persistent file and state workspace attached to a
karta across sessions.
### durable memory
Durable memory is the accumulated files, history, and context that persist for a
karta between sessions.
### karta
A karta is a durable agent instance created from one agent project: one per user
for a personal AI assistant, one per team virtual employee, one singleton for a
backend task, or one per fleet member. Each karta has its own workspace and
accumulated memory.
Aliases: kartas; karta, the running durable computer instance
### agent instance
An agent instance is one durable karta created from an agent project, with its
own workspace, sessions, and memory.
### Agent
An agent is the deployable unit you ship to Karta: a folder that configures a
harness with instructions, sub-agents, skills, tools, hooks, and related
configuration.
Aliases: agents
### agent project
An agent project is the folder form of an agent. Use this term when you need to
emphasize local files, repository layout, or what the CLI scans and deploys.
### harness application
Harness application is older wording for an agent project. New docs should use
agent or agent project unless they are explaining legacy output or migration.
Aliases: harness applications, agent application, agent applications
### harness
A harness is the agent runtime, such as Claude Code, OpenCode, DeepAgents,
Goose, or Codex CLI. It owns the agent loop, tools, MCP, context, memory
format, and conversation history.
Aliases: agent harness, agent harnesses
### supported harness
A supported harness is a harness format that Karta can detect, scaffold,
package, and run. The current list is documented in
[Supported harnesses](/build/supported-harnesses).
### sub-agent
A sub-agent is a harness-native role or persona inside one agent project, such
as a Markdown file in Claude Code's `.claude/agents/` directory. Karta packages
sub-agents with the parent agent release; they are not separate deployed agents
with their own stable endpoints.
Aliases: sub-agents; specialist agent; specialist agents; harness sub-agent; harness sub-agents
### session
A session is the multi-turn conversation handle Karta exposes. It tracks
metadata, participants, the current sub-agent, release pinning, and pending
approvals; the harness owns the full conversation history.
### participant
A participant is a human or AI actor in a session. Karta attributes messages to
participants so multi-party conversations keep sender identity.
### release
A release is an immutable, versioned build of an agent. Activating a release is
a pointer flip, and rollback flips the pointer back.
### stable agent endpoint
The stable agent endpoint is the long-lived URL for a deployed agent. New
releases activate behind the same endpoint, so clients do not change URLs on
deploy.
Aliases: stable agent URL
### trust boundary
A trust boundary is a deliberate separation between systems with different
authority. Karta's key boundary is that the agent runtime does not hold account,
billing, or key-management authority.
### runtime/management boundary
The runtime/management boundary separates the systems that run agent sessions
from the systems that manage account state, billing, keys, releases, budgets,
and audit.
Aliases: runtime/management separation
### identity
Identity is the user, organization, key, or actor context Karta uses to decide
who a request represents and which boundary it belongs to.
### isolation
Isolation is Karta's boundary model for separating organizations, kartas,
sessions, browser credentials, and runtime execution. It does not mean every
shared-service component is a customer-managed data partition.
### one agent, many kartas
One agent, many kartas is the deployment pattern where one agent project and
release serves many separate durable kartas.
### virtual employee
A virtual employee is a durable karta that performs work for a team rather than
one individual end user.
### backend task singleton
A backend task singleton is one durable karta used by a scheduled,
event-triggered, or on-demand backend task that needs memory across runs.
### backend-job karta
A backend-job karta is a durable karta used by a server-side workflow or
scheduled job rather than an interactive user.
### fleet-member karta
A fleet-member karta is a durable karta representing one member of a repeated
fleet of similar agents or jobs.
### tenant boundary
A tenant boundary is the public docs boundary for ownership and access, usually
organization plus the selected karta or session.
### default-deny
Default-deny is the API behavior of returning no cross-organization or
cross-session information when a caller lacks ownership or scope.
## Authoring and deploy
### CLAUDE.md
`CLAUDE.md` is the Claude Code instructions file that can be the minimal
complete agent project.
### .claude directory
The `.claude` directory is the Claude Code configuration folder for sub-agents,
skills, settings, tools, permissions, and MCP.
### .opencode directory
The `.opencode` directory is the OpenCode configuration folder Karta uses to
detect and run an OpenCode-based agent project.
### .deepagents directory
The `.deepagents` directory is the DeepAgents configuration folder Karta uses
to detect and run a DeepAgents-based agent project.
### .goose directory
The `.goose` directory is the Goose configuration folder Karta uses to detect
and run a Goose-based agent project.
### .codex directory
The `.codex` directory is the Codex CLI configuration folder Karta uses to
detect and run a Codex CLI-based agent project.
### agent instructions
Agent instructions are the harness-native prompt and context files that define
the default behavior of the agent.
Aliases: system instructions
### sub-agent file
A sub-agent file is a Markdown-with-frontmatter file that defines one
harness-native sub-agent.
Aliases: sub-agent files; specialist agent file; specialist agent files
### agent frontmatter
Agent frontmatter is YAML metadata on a sub-agent file, such as name,
description, model, tools, skills, permissions, and type.
### reusable skill
A reusable skill is a harness-native skill package an agent can invoke when its
description and bindings match a task.
Aliases: agent skill, agent skills
### MCP server configuration
MCP server configuration is the harness configuration that declares external
MCP tools an agent may call.
Aliases: .mcp.json
### hooks
Hooks are lifecycle extension points that let an agent project or SDK run code
around session and turn behavior.
### runtime policy
Runtime policy is configuration that controls runtime behavior such as approval
handling, hidden events, and idle timeouts.
### permission mode
Permission mode is the setting that decides whether a deployed agent prompts
interactively or auto-approves allowed actions for the session.
### karta.toml
`karta.toml` is the deploy manifest in an agent project. It names the agent,
controls whether it is deployable, and declares build hints and environment
configuration.
### deploy gate
The deploy gate is the `deploy = true` setting in `karta.toml`. Karta only
builds and deploys agents whose gate is enabled.
Aliases: deploy = true
### environment variable
An environment variable is runtime configuration declared by the agent project
and bound locally or in production. Secret values are stored and displayed as
secrets, not plain text.
Aliases: env binding, env secret
### buildpack
A buildpack is a build mode where Karta infers and installs runtime dependencies
from a standard project layout instead of requiring a Dockerfile.
### folder upload
Folder upload is the deploy path for a non-git directory. The CLI packages the
current folder and uploads it so Karta can build a release.
Aliases: tarball upload
### hosted git
Hosted git is Karta's git-push deploy path. The CLI wires a `karta` remote, and
`git push karta main` builds enabled agents from the pushed tree.
Aliases: git push deploy
### deploy loop
The deploy loop is the sequence of shipping an agent project, serving the active
release at a stable endpoint, and consuming it through the session API, widget,
SDK, or adapter.
### rollback
Rollback activates a previous release without rebuilding and without changing
the agent endpoint.
### preview release
A preview release is a temporary release used to test a change before promoting
it to the production release path.
### local parity
Local parity means `karta dev` exposes the same session API shape locally that
production serves, so a frontend or backend can test against the production
contract before deploy.
### Karta CLI
The Karta CLI is the `karta` command-line tool for login, setup, local dev,
deploy, rollback, logs, sessions, keys, and usage.
Aliases: @karta.sh/cli, TypeScript CLI package
### device-flow login
Device-flow login is the browser approval flow where the CLI prints a code and
receives a named revocable credential after approval.
Aliases: browser approval
### named profile
A named profile is a local CLI credential profile in `~/.karta/config.toml`
selected by `--profile`.
### env drift
Env drift is a mismatch between declared environment variables, local `.env`
values, and production bindings.
### hot reload
Hot reload is the local dev behavior where edits such as `CLAUDE.md` changes
are picked up without restarting the full integration flow.
### Dockerfile build
Dockerfile build is a release build mode where Karta builds from a
repository-provided Dockerfile.
### file-copy build
File-copy build is a release build mode where Karta runs the extracted file
tree directly because no Dockerfile or buildpack is selected.
### entry point
An entry point is the `module:attribute` that exposes the Karta instance a
buildpack release imports at runtime.
### active release
The active release is the release currently selected for new sessions on an
agent endpoint.
### release activation
Release activation is the pointer flip that makes a built release live and
records the change.
## Memory and identity
### karta id
The karta id is the stable value that selects which durable agent instance,
workspace, and memory a session uses.
### memory boundary
A memory boundary is the line that decides which users or jobs share files,
history, and learned context. In Karta, the boundary is the karta id.
Aliases: privacy boundary, persistence boundary
### per-user karta
A per-user karta is one durable computer per verified end user and agent. It is
the usual choice when each signed-in user needs private memory.
### virtual employee karta
A virtual employee karta is a durable computer shared deliberately by a team
rather than owned by one end user.
### ephemeral karta
An ephemeral karta is a throwaway durable computer for a single session. Use it
when no memory should carry forward.
Aliases: throwaway karta, throwaway kartas
### end\_user\_id
`end_user_id` is the verified or trusted user identifier passed into a session.
For per-user memory, it usually determines the karta id.
### agent\_instance\_id
`agent_instance_id` is the technical schema key for a karta's durable workspace.
Public docs should normally say karta id unless discussing API metadata.
### workspace access
Workspace access is the read-only git clone path for inspecting a karta's
durable files. It is off by default and must be enabled by an admin.
### organization
An organization is the top-level account, billing, membership, key, budget, and
ownership boundary in Karta.
### multi-tenancy
Multi-tenancy is the set of authorization, session, runtime, and account-state
boundaries that keeps one organization's resources separate from another's in a
shared service.
## API and protocol
### session API
The session API is Karta's uniform protocol for creating sessions, sending
messages, resolving approvals, and streaming events from any deployed agent.
### session id
A session id is the stable identifier used to fetch, resume, message, or inspect
one Karta session.
### session metadata
Session metadata is caller-provided structured context attached to a session for
routing, labeling, or app-specific use.
### flat route family
The flat route family is the server-side API on `api.karta.sh`, addressed by
global `/v1/...` paths and authenticated with an API key.
### agent route family
The agent route family is the per-agent API on `agent.karta.sh/{org}/{agent}`,
used by specific deployed agents, adapters, widgets, and backends.
### consumer adapter
A consumer adapter is a compatibility surface that lets an existing OpenAI- or
Anthropic-shaped client talk to a Karta agent without adopting the native API.
### Managed Agents adapter
The Managed Agents adapter is the event-sourced Anthropic-shaped API surface for
posting user events, streaming agent events, and fetching session state.
Aliases: Anthropic Managed Agents adapter
### OpenAI Responses adapter
The OpenAI Responses adapter presents a Karta agent through the OpenAI Responses
API shape, including continuation with `previous_response_id`.
### OpenAI Chat Completions adapter
The OpenAI Chat Completions adapter presents a Karta agent through the classic
OpenAI messages-array shape.
### gateway
The gateway routes events between participants, including humans and AI actors
that may be reachable through another gateway.
### streaming event
A streaming event is a typed event emitted during a turn, such as text, tool
use, reasoning, approval request, error, or done.
Aliases: typed event, typed events
### SSE
SSE, or Server-Sent Events, is the wire format Karta uses for streaming typed
events over HTTP.
Aliases: Server-Sent Events
### input\_required
`input_required` is the streaming event that pauses a turn until a caller
approves or denies an action.
### pending input
Pending input is the unresolved approval request that pauses a session until a
caller responds.
### approval prompt
An approval prompt is emitted when an agent needs permission for a tool or
sensitive action before continuing.
### approval decision
An approval decision is the caller's response to a pending input, normally
approve once, approve for session, or deny.
### error event
An error event is a streaming event that reports a turn, provider, auth, or
harness failure after a stream has begun.
Aliases: stream error
### done event
A done event is the terminal streaming event carrying the completed message and
usage.
### API key
An API key is a secret `kt_live_...` bearer token scoped to an organization and
allowed actions. It belongs on servers, CLIs, and CI, never in browsers.
### session token
A session token is a short-lived, agent-scoped signed token that lets a browser drive a
specific deployed agent without holding an API key.
### embed key
An embed key is a publishable `pk_live_...` key used by the hosted chat widget.
Its safety comes from origin allowlists and spend caps, not secrecy.
### route family
A route family is a group of API paths with the same addressing and credential
rules, such as flat native routes, agent native routes, or adapter routes.
### OpenAPI spec
The OpenAPI spec is the machine-readable description of Karta's public HTTP API.
Use it for code generation, API exploration, and contract review.
Aliases: machine-readable spec; /openapi.json
### Retry-After
`Retry-After` is the HTTP response header telling a client when to retry a
rate-limited or unavailable request.
### idempotency key
An idempotency key is a caller-supplied key that makes safe retries of the same
operation resolve to one effect.
### API key operation scopes
API key operation scopes are fine-grained permissions such as `agents:read`,
`releases:write`, or `model_keys:write` that limit a key to named operations.
### token TTL
Token TTL is the expiry window on a session token that limits how long a leaked
browser credential can be used.
### verified subject
A verified subject is the `sub` value Karta binds into a session token after
verifying host-signed identity.
## Widget and frontend
### chat widget
The chat widget is Karta's hosted launcher and chat panel for embedding a
deployed agent in a website with a script tag.
### command API
The command API is the widget's `window.karta` interface for opening the widget,
identifying the user, sending messages, and subscribing to events.
### headless client
The headless client is the widget SDK mode for building a custom chat UI while
reusing Karta's session, token, and streaming logic.
### identity token
An identity token is a server-signed proof that your app vouches for a user id.
Karta verifies it before binding that user into a session token.
### HMAC identity token
An HMAC identity token is a server-generated HMAC proving the host app vouches
for a widget `userId`.
### identity-verification secret
An identity-verification secret is the per-embed-key server-only secret used to
sign verified identity tokens.
### verified identity
Verified identity means Karta verified a host-signed user id and bound that
subject into the session token. The identity token upgrades a soft user id; it
is not a standalone auth source.
### soft identity
Soft identity is advisory user metadata sent by the browser without a server
signature. It is useful for labels and analytics, not authorization.
### anonymous identity
Anonymous identity is the default widget mode where no trusted user id is
provided. The widget may keep browser continuity, but the server does not trust
who the user is.
### step-up
Step-up is a recent stronger authentication check, such as MFA, that your app
signs into the identity token before sensitive approvals.
### origin allowlist
An origin allowlist is the explicit set of website origins allowed to use an
embed key. Browser token minting fails when the origin is not listed.
### CSP
CSP, or Content Security Policy, is the browser policy that controls which
scripts, frames, and connections a host page allows.
### widget theme
A widget theme is the appearance and behavior configuration inherited by the
hosted page and embed keys.
### pre-chat consent
Pre-chat consent is an optional disclosure or acceptance step shown before a
visitor sends the first widget message.
### limit\_reached
`limit_reached` is the widget event or state shown when usage, spend, or rate
limits block more work.
## Models, spend, and operations
### BYOK
BYOK means bring your own key. You store a model-provider credential in Karta so
supported model traffic can run through your provider account instead of the
platform key.
Aliases: bring your own key
### model key
A model key is a stored provider credential or connector. Anthropic keys back
provider-account traffic today; other provider records may fall back to the
platform key until full provider routing is available.
Aliases: ModelKey; Anthropic API key; OpenAI API key; Bedrock provider key; Vertex provider key; OpenRouter provider key
### model selection
Model selection is the choice of provider connector and model id used by an
organization default or an agent override.
### provider key
A provider key is a model-provider credential stored for BYOK or
provider-specific model access.
### model provider
A model provider is an external model service such as Anthropic, OpenAI,
Bedrock, Vertex, or OpenRouter that may process agent prompts and outputs.
### managed model access
Managed model access is Karta-provided model access where model usage runs
through Karta's platform key and billing path.
Aliases: platform model access
### usage
Usage is the metered record of tokens and cost generated by agent turns,
attributed to the organization and, when available, key, user, and karta.
### token metering
Token metering is the recording of input, output, and total tokens for a turn so
usage and cost can be calculated.
### usage attribution
Usage attribution is the assignment of usage and cost to an organization, key,
user, karta, seat, or embed key when available.
### budget
A budget is a configured cap that stops new work before spend exceeds the
allowed token or cost limit.
### spend cap
A spend cap is a hard limit at a specific grain, such as organization, key,
user, karta, seat, or anonymous embed key.
Aliases: hard cap
### per-key sub-limit
A per-key sub-limit is a cap that prevents one API key or integration from
consuming the whole organization budget.
### budget alert
A budget alert is a threshold notification, usually via webhook, before or when
a budget cap is crossed.
Aliases: BudgetAlertNotification
### credit
A credit is prepaid value that managed-plan usage draws down. When credits are
exhausted, requests are refused before they run.
### rate card
The rate card lists model and platform prices used to calculate usage cost.
### webhook
A webhook is a signed outbound HTTP notification from Karta to your system for
events such as billing, budget, session, or turn activity.
Aliases: outbound webhook
### webhook endpoint
A webhook endpoint is the HTTPS URL a customer registers to receive selected
Karta event notifications.
### webhook signature
A webhook signature is the HMAC-SHA256 header a receiver verifies before
trusting a webhook payload.
Aliases: HMAC-SHA256 signature
### audit log
The audit log is the immutable record of material account changes, written so
entries cannot be edited or deleted.
### production readiness
Production readiness is the launch checklist covering releases, keys, identity,
budgets, BYOK, webhooks, audit, status, and support ownership before real users
arrive.
### security model
The security model is Karta's containment approach for agent risk: assume prompt
injection can happen, then bound credentials, tools, sessions, kartas, spend,
and account authority.
### prompt injection containment
Prompt injection containment is the security stance that hostile instructions
are expected and should be bounded by credentials, tools, sessions, kartas, and
spend.
### residual risk
Residual risk is the risk that remains after Karta boundaries, especially broad
customer tools, shared kartas, provider terms, and bearer-token exposure.
### bearer token
A bearer token is a credential accepted by possession, so any holder can use it
until expiry or revocation.
### operator access
Operator access is Karta personnel access to systems that run or support the
platform. Public docs describe the trust posture and audit expectations, not
internal procedures.
### status page
The status page reports platform health and incidents. Use it to distinguish a
Karta-side incident from an integration or agent issue.
### vulnerability disclosure
Vulnerability disclosure is the public process and safe-harbor terms for
reporting security issues to Karta.
Aliases: vulnerability disclosure policy; coordinated disclosure
## Additional public concept index
### workspace
A workspace is the file and process context where a harness runs. In Karta, a
workspace may be local during development or durable inside a karta.
### metering
Metering is the recording of token, usage, and cost data so Karta can enforce
budgets, attribute spend, and show usage history.
Aliases: usage metering
### spend controls
Spend controls are the budgets, caps, credits, and request-time checks that stop
new work before an allowed limit is exceeded.
### access surfaces
Access surfaces are the public ways a user, server, browser, SDK, CLI, or
adapter can reach a deployed agent.
### Claude Code harness
The Claude Code harness is the harness mode where Karta runs an agent project
defined with Claude Code files such as `CLAUDE.md` and `.claude/agents`.
### OpenCode harness
The OpenCode harness is the harness mode where Karta runs an agent project
defined with OpenCode configuration.
### DeepAgents harness
The DeepAgents harness is the harness mode where Karta runs an agent project
defined with DeepAgents configuration.
### Goose harness
The Goose harness is the harness mode where Karta runs an agent project defined
with Goose configuration.
### Codex CLI harness
The Codex CLI harness is the harness mode where Karta runs an agent project
defined with Codex CLI configuration.
### managed agent platform
A managed agent platform runs agent projects for users, teams, and jobs, with
durable workspaces, metering, governance, and access surfaces around the running
agent.
Aliases: Managed Agent Platform
### private workspace
A private workspace is a workspace whose files and state are scoped to one
owner boundary, such as one user, virtual employee, job, or account.
### virtual employee roster
A virtual employee roster is a group of virtual employee kartas that work with
the same team.
### backend job
A backend job is a server-side or scheduled workflow that calls an agent without
a live end-user chat session.
### fleet member
A fleet member is one repeated agent instance in a larger fleet, such as one
karta per account, classroom, customer, or scheduled workload.
### personal agent
A personal agent is a per-user karta configured to help one signed-in user with
private memory and repeated tasks.
Aliases: personal AI assistant
### Slack agent
A Slack agent is an agent integration where Slack is the user-facing channel and
Karta provides the durable agent runtime behind it.
### Jira agent
A Jira agent is an agent integration where Jira issues, projects, or workflows
are the user-facing work surface.
### classroom agent fleet
A classroom agent fleet is a group of kartas used across a class, cohort, or
learning environment, commonly one per student, team, or assignment.
### customer-facing agent product
A customer-facing agent product is an application where end users interact with
an agent inside the product experience.
### agent behavior
Agent behavior is the observable way an agent responds, uses tools, requests
approval, hands off, and persists work across turns and sessions.
### uniform session protocol
The uniform session protocol is Karta's consistent session, message, approval,
and streaming contract across harnesses and adapters.
### agent slug
An agent slug is the URL-safe identifier for a deployed agent inside an
organization.
### organization slug
An organization slug is the URL-safe identifier for an organization in
agent-scoped URLs.
### org/agent path
The org/agent path is the `{org}/{agent}` address segment used by per-agent API
routes and adapter URLs.
### consumer surface
A consumer surface is an API, SDK, widget, or adapter used by an application to
run an agent for users or backend work.
### management surface
A management surface is an API, SDK, CLI, or console area used to configure
account state such as releases, keys, budgets, billing, and webhooks.
### run surface
A run surface is any public interface used to start or continue agent work,
including the session API, widget, SDKs, and adapters.
### native session surface
The native session surface is Karta's direct session API, as distinct from
compatibility adapters shaped like another provider.
### consumer adapter surface
A consumer adapter surface is an adapter endpoint that lets an existing
OpenAI-shaped or Anthropic-shaped client run a Karta agent.
### account state
Account state is organization-owned configuration and history such as members,
roles, API keys, BYOK, budgets, billing, releases, webhooks, and audit entries.
### money-and-identity state
Money-and-identity state is account state that controls billing, spend,
credentials, membership, and user identity boundaries.
### .claude/agents
`.claude/agents` is the Claude Code folder where sub-agent definitions live
inside an agent project.
### .claude skills
`.claude` skills are harness-native reusable skill packages that Claude Code can
discover and invoke while running an agent.
### .claude settings
`.claude` settings are Claude Code configuration files for tools, permissions,
hooks, MCP, and other harness behavior.
### Markdown-with-frontmatter agent definition
A Markdown-with-frontmatter agent definition is a sub-agent file whose
YAML metadata and Markdown body define routing, tools, model, and instructions.
### agent description field
The agent description field is the frontmatter text a harness uses to decide
when a sub-agent is relevant.
### agent routing description
An agent routing description is the part of a sub-agent definition that tells
the harness when to route or hand off to that sub-agent.
### skill discovery
Skill discovery is the process where a harness finds reusable skills available
to an agent project.
### skill binding
Skill binding is the configuration that makes a reusable skill available to a
specific agent or runtime context.
### tool definition
A tool definition describes an action the harness or MCP server can call,
including its name, inputs, and expected behavior.
### policies
Policies are configuration rules that constrain runtime behavior, permissions,
approvals, visibility, or tool use.
### input-required policy
Input-required policy is configuration that decides when the runtime must pause
for caller approval instead of continuing autonomously.
### autonomous runtime
An autonomous runtime is a runtime mode where allowed work can continue without
interactive approval for every step.
### interactive runtime
An interactive runtime is a runtime mode where the agent pauses for user or
caller input when a policy, tool, or approval requires it.
### deploy manifest
A deploy manifest is the `karta.toml` file that tells Karta which agent project
to build and how it should be configured.
### agent name
An agent name is the human-readable name declared for an agent project and used
in deploy, console, and API surfaces.
### build-kind resolution
Build-kind resolution is Karta's choice of build mode, such as Dockerfile,
buildpack, or file-copy, from the agent project's files and configuration.
### multiple agents in one repo
Multiple agents in one repo is the project layout where one source repository
contains more than one deployable agent project.
### duplicate-name guard
A duplicate-name guard prevents two deployable agents in one build scope from
using the same agent name.
### environment variable declaration
An environment variable declaration is a manifest entry that says a runtime
configuration value exists and must be supplied locally or in production.
### \[env] table
The `[env]` table is the `karta.toml` section used to declare environment
variables for an agent project.
### env pull
Env pull is the workflow for copying production environment variable bindings
into local development configuration.
### env diff
Env diff is the comparison between declared, local, and production environment
variable bindings.
### agent template
An agent template is a starting project structure for a common agent use case.
### starter agent
A starter agent is a minimal agent template intended to get a new developer to a
working local or deployed agent quickly.
### FAQ agent template
An FAQ agent template is a starter pattern for answering product, support, or
documentation questions from a curated knowledge source.
### support bot template
A support bot template is a starter pattern for a customer-support chat agent
that can answer questions and route work.
### stable id
A stable id is an identifier that keeps selecting the same durable boundary
across requests and sessions.
### durable id
A durable id is an identifier used to resume persistent state instead of
creating a new throwaway runtime context.
### ephemeral id
An ephemeral id is a temporary identifier for a throwaway session or karta that
should not carry memory forward.
### per-browser anonymous visitor id
A per-browser anonymous visitor id is browser-local continuity for anonymous
widget sessions. It is not a verified user identity.
### verified user id
A verified user id is a host-signed user identifier that Karta has checked and
can bind into a session token.
### agent\_instance
`agent_instance` is the older or lower-level schema wording for a karta. Public
docs should prefer karta unless discussing metadata compatibility.
### per-karta workspace
A per-karta workspace is the durable file workspace owned by one karta.
### per-karta memory
Per-karta memory is the history, files, and learned context scoped to one karta.
### read-only workspace clone
A read-only workspace clone is the git clone view used to inspect a karta's
workspace without mutating it.
### git\_read token
A `git_read` token is a credential scoped to read-only workspace clone access.
### workspace\_inspectable gate
The `workspace_inspectable` gate is the admin-controlled setting that allows or
blocks read-only workspace inspection.
### org boundary
An org boundary is the ownership boundary around an organization's members,
agents, kartas, keys, budgets, billing, and audit state.
### cross-org default deny
Cross-org default deny is the rule that a caller should not learn whether
another organization's resource exists when it lacks access.
### session ownership
Session ownership is the account and identity relationship that decides who can
fetch, message, inspect, or continue a session.
### tenancy stack
The tenancy stack is the combined set of organization, agent, karta, session,
credential, budget, and runtime boundaries.
### Karta metadata
Karta metadata is platform-owned session or resource metadata such as ids,
release pins, participants, timestamps, and routing state.
### harness session storage
Harness session storage is the harness-owned conversation and runtime history
used to continue an agent session.
### transcript access policy
Transcript access policy is the rule set that decides who may read session
transcripts.
### session transcript
A session transcript is the message and event history for a session.
### durable files
Durable files are files written inside a karta workspace that persist across
sessions for that karta.
### workspace export
Workspace export is the workflow for copying or inspecting durable workspace
contents outside the live karta runtime.
### per-karta utility
Per-karta utility is the product value created by giving each user, role, job,
or account its own persistent agent context.
## Sessions, deployment, and CLI concept index
### session handle
A session handle is the identifier and API object a caller uses to continue or
inspect one multi-turn session.
### multi-turn conversation
A multi-turn conversation is an interaction where the agent and participants
exchange more than one message under the same session.
### session creation
Session creation is the API or SDK operation that opens a new session for a
deployed agent.
### session fetch
Session fetch is the API or SDK operation that retrieves session metadata,
state, or recent events.
### session resume
Session resume is continuing an existing session instead of starting a new one.
### session pinning
Session pinning is binding a session to a specific agent, release, karta, or
identity boundary so later turns continue in the intended context.
### release pinning
Release pinning is binding a session or request to a specific release instead
of whatever release is currently active.
### agent pinning
Agent pinning is binding a session or client to a specific deployed agent.
### participant attribution
Participant attribution is the metadata that records which human or AI actor
sent a message or event.
### human participant
A human participant is a person represented in a session, such as an end user,
operator, reviewer, or support agent.
### AI participant
An AI participant is an agent or model-backed actor represented in a session.
### multi-party session
A multi-party session is a session with more than one participant, such as a
human, a sub-agent, and another AI actor.
### recipient
A recipient is the participant or gateway target that should receive an event
or message.
### event delivery
Event delivery is the process of sending session events to the caller, widget,
adapter, webhook, or gateway that needs them.
### input\_required event
An `input_required` event is the streamed event form of pending input.
### approve\_once
`approve_once` is an approval decision that lets one pending action continue
without granting the same approval for the rest of the session.
### approve\_session
`approve_session` is an approval decision that permits the same class of action
for the rest of the session.
### deny
`deny` is an approval decision that rejects the pending action and lets the
agent continue or fail according to runtime behavior.
### tool confirmation
Tool confirmation is the user or caller approval step before an agent performs a
tool action that requires permission.
### custom tool result
A custom tool result is host-provided output returned to the agent after the
host application handles a tool call.
### user message
A user message is a session message authored by the end user or calling
application on the user's behalf.
### user interrupt
A user interrupt is a caller signal that stops or redirects an in-progress turn.
### system message
A system message is trusted runtime or host context sent to the agent outside
the normal user-message channel.
### agent message
An agent message is a message authored by the running agent or sub-agent.
### agent handoff
An agent handoff is a transition where one agent actor passes work to another
agent actor.
### sub-agent handoff
A sub-agent handoff is a transition from one sub-agent to another inside the
same agent project.
Aliases: specialist handoff; specialist handoffs
### SSE stream
An SSE stream is the HTTP response stream that carries Server-Sent Events during
an agent turn.
### text event
A text event is a streamed event containing user-visible agent text.
### tool\_use event
A `tool_use` event is a streamed event indicating that the agent is invoking a
tool.
### reasoning event
A reasoning event is a streamed event carrying model or harness reasoning
metadata when that visibility is enabled.
### step\_start event
A `step_start` event marks the beginning of a model, tool, approval, or runtime
step inside a turn.
### step\_finish event
A `step_finish` event marks the completion of a model, tool, approval, or
runtime step inside a turn.
### stream accumulation
Stream accumulation is the client-side process of combining streamed events
into the final visible message or state.
### unary response
A unary response is a non-streaming API response that returns one final result
instead of an event stream.
### stream-shaped command
A stream-shaped command is a command API or SDK call whose result is delivered
as incremental events.
### final response
A final response is the completed turn result after all streamed events have
been accumulated.
### session status
Session status is the current lifecycle state of a session, such as active,
idle, waiting for input, failed, or complete.
### idle status
Idle status means the session is not actively running a turn and is ready for
new input.
### stop reason
A stop reason explains why a turn ended, such as completion, interruption,
approval required, error, or a configured limit.
### requires action
Requires action is a state where a session cannot continue until a caller
provides input, approval, or a tool result.
### end turn
End turn is the point where the agent has finished responding and control
returns to the caller.
### ship, serve, consume loop
The ship, serve, consume loop is the production workflow of deploying an agent,
serving it at a stable endpoint, and calling it from a product surface.
### immutable release
An immutable release is a release whose built contents do not change after it is
created.
### versioned release
A versioned release is a release identified by a stable version or release id so
it can be audited, activated, or rolled back to.
### production release
A production release is the release selected to serve normal production traffic.
### atomic pointer flip
An atomic pointer flip is the release activation mechanism where Karta changes
which immutable release an endpoint serves without rebuilding.
### instant rollback
Instant rollback is rollback by pointer flip, returning traffic to an earlier
release without a new build.
### release archive
A release archive is the stored build output and metadata for an immutable
release.
### release status
Release status is the lifecycle state of a release, such as building, active,
failed, archived, or not materialized.
### release version
A release version is the user-facing or API-facing version identifier for a
release.
### current\_release
`current_release` is the pointer that records which release currently serves an
agent endpoint.
### build logs
Build logs are the logs emitted while Karta discovers, packages, installs, and
builds an agent release.
### release build
A release build is the build job that turns source files into an immutable
release.
### materialized release
A materialized release is a release whose runtime artifacts have been built and
are ready to serve sessions.
### release not materialized
Release not materialized is the state where a release record exists before its
runtime artifacts are ready to run.
### hosted source repo
A hosted source repo is Karta-managed git storage used for git-push deploys.
### SourceRepo
`SourceRepo` is the product/schema concept for a source repository connected to
agent release builds.
### deploy branch
A deploy branch is the git branch whose pushed contents are used to build a
release.
### git remote
A git remote is a named repository URL, such as the `karta` remote used for
git-push deploys.
### git push karta main
`git push karta main` is the hosted-git deploy command that pushes the main
branch to Karta's git remote.
### GitHub sync
GitHub sync is a source-control integration that pulls or mirrors source from a
GitHub repository for release builds.
### GitHub repository binding
A GitHub repository binding connects a Karta agent source configuration to a
specific GitHub repository.
### GitHub installation
A GitHub installation is the GitHub App installation that grants repository
access for sync or deploy workflows.
### GitHub-pull deploy
GitHub-pull deploy is a deploy path where Karta builds from source pulled from
GitHub rather than from a folder upload or hosted git push.
### source repo fan-out
Source repo fan-out is the process of discovering and building multiple
deployable agents from one connected source repository.
### discover agents
Discover agents is the scan step that finds deployable agent projects in a
folder, repository, or pushed source tree.
### build fan-out
Build fan-out is the process of starting separate release builds for multiple
discovered agents.
### self-provisioned hosted agent
A self-provisioned hosted agent is an agent whose hosted source repository and
deploy path are created by the CLI or setup flow.
### npm CLI install
NPM CLI install is installing the Karta CLI from npm, usually as
`@karta.sh/cli`.
### one-time code
A one-time code is the short code printed during device-flow login so the
browser approval can connect back to the CLI.
### named revocable CLI credential
A named revocable CLI credential is a local credential profile that can be
listed, rotated, or revoked without affecting every user or integration.
### git credential helper
A git credential helper stores and supplies git credentials for hosted git
deploys.
### KARTA\_API\_KEY
`KARTA_API_KEY` is the environment variable commonly used to pass a Karta API
key to CLIs, SDKs, and server-side integrations.
### KARTA\_PROJECT
`KARTA_PROJECT` is the environment variable the Karta CLI can use in CI to
select a specific agent when no local `karta.toml` context or `--agent` flag is
available.
### \~/.karta/config.toml
`~/.karta/config.toml` is the local CLI configuration file for profiles and
credential metadata.
### karta login
`karta login` starts the CLI login flow for a developer.
### karta login --with-token
`karta login --with-token` stores an existing token for CLI use instead of
starting browser approval.
### karta auth status
`karta auth status` shows whether the CLI has a usable credential.
### karta auth token
`karta auth token` prints or manages the current CLI token, depending on command
options.
### karta auth logout
`karta auth logout` removes the active CLI credential from local configuration.
### karta whoami
`karta whoami` shows the account or organization identity associated with the
active CLI credential.
### karta create
`karta create` creates or scaffolds a new agent project.
### karta setup
`karta setup` configures a folder or repository so Karta can discover and deploy
agents from it.
### karta setup --enable
`karta setup --enable` updates setup configuration and enables deploy behavior.
### karta dev
`karta dev` runs the local development server for an agent project.
### karta dev -m
`karta dev -m` selects the model or model mode for local development when that
option is supported.
### karta dev --user
`karta dev --user` runs local development with a specific user identity or user
simulation.
### karta dev --port
`karta dev --port` runs local development on a selected local port.
### karta dev --verbose
`karta dev --verbose` enables more detailed local development logs.
### karta dev --release
`karta dev --release` runs local development against release-like behavior when
that mode is supported.
### karta dev --env remote
`karta dev --env remote` runs local development with remote environment
bindings.
### karta deploy
`karta deploy` builds and deploys an agent project.
### karta status
`karta status` shows deploy, release, or agent status from the CLI.
### karta rollback
`karta rollback` activates an earlier release from the CLI.
### karta open
`karta open` opens the relevant Karta console or agent page from the CLI.
### karta open console
`karta open console` opens the Karta console in a browser.
### karta sessions
`karta sessions` lists sessions visible to the current CLI credential.
### karta sessions show
`karta sessions show` renders one session transcript.
Aliases: karta sessions view, karta session
### karta ps
`karta ps` lists running or recent agent processes or sessions when supported.
### karta send
`karta send` sends a message to a deployed or local agent from the CLI.
### karta run alias
`karta run` is older alias-style wording for sending a message or running a
turn from the CLI.
### karta send --session-id
`karta send --session-id` sends a message into an existing session.
### karta send --json
`karta send --json` returns machine-readable command output.
### karta logs
`karta logs` shows logs for a local or deployed agent context.
### karta keys
`karta keys` manages or lists Karta keys through the CLI.
### karta usage
`karta usage` shows usage and spend information through the CLI.
### karta update
`karta update` updates the installed CLI when supported by the installation
method.
### karta completion
`karta completion` prints shell completion configuration for the CLI.
### karta doctor
`karta doctor` checks local setup, credentials, runtime dependencies, and common
configuration problems.
### uv runtime bootstrap
UV runtime bootstrap is the local setup step that prepares Python runtime
dependencies with `uv`.
### PATH shadowing
PATH shadowing is when an older executable earlier in `PATH` hides the intended
Karta CLI or runtime binary.
### local Karta session API
The local Karta session API is the local development version of the production
session API served by `karta dev`.
### local chat REPL
A local chat REPL is an interactive command-line chat loop for testing an agent
during development.
### production parity flags
Production parity flags are local development options that make local behavior
match production request, release, or environment behavior more closely.
### stale Python CLI
A stale Python CLI is an older Python-based CLI installation that can shadow the
current npm-distributed Karta CLI.
## Widget and identity concept index
### hosted chat widget
The hosted chat widget is Karta's browser-hosted chat UI for embedding a
deployed agent on a website.
### widget loader
The widget loader is the browser script that bootstraps the Karta widget,
downloads runtime configuration, and mounts the launcher or chat panel.
### async script tag
An async script tag loads the widget JavaScript without blocking the host page's
initial rendering.
### CDN widget bundle
The CDN widget bundle is the hosted JavaScript asset that contains the widget
runtime.
### Shadow DOM isolation
Shadow DOM isolation is the browser boundary the widget uses to keep its styles
and DOM structure separate from the host page.
### launcher
The launcher is the button or entry point that opens the Karta chat panel.
### chat panel
The chat panel is the visible widget interface where the user reads and sends
messages.
### hosted chat page
A hosted chat page is a Karta-hosted standalone page for a deployed agent, used
when embedding a widget is not the right integration shape.
### publishable pk\_live key
A publishable `pk_live` key is an embed key safe to place in browser code when
origin allowlists and spend caps are configured.
### allowed origins
Allowed origins are the browser origins permitted to use an embed key.
### anonymous spend cap
An anonymous spend cap limits spend from anonymous widget traffic that is not
bound to a verified user.
### widget runtime config
Widget runtime config is the per-embed-key configuration the loader fetches,
including appearance, behavior, allowed origins, and token settings.
### embed config endpoint
The embed config endpoint returns widget runtime configuration for a publishable
embed key.
### widget command API
The widget command API is the browser command interface for controlling the
widget from host-page JavaScript.
### inline queue stub
An inline queue stub records widget commands issued before the widget bundle has
finished loading.
### karta(...) command
A `karta(...)` command is a host-page call into the widget command API.
### open command
The open command tells the widget to open its chat panel.
### close command
The close command tells the widget to close or collapse its chat panel.
### send command
The send command sends a message into the current widget session.
### identify command
The identify command attaches soft or verified identity information to the
current widget user.
### subscribe command
The subscribe command registers a host-page callback for widget events.
### widget events
Widget events are browser events emitted by the widget for lifecycle, session,
message, limit, and error states.
### theme preset
A theme preset is a named widget appearance preset that sets a coherent group of
colors and surface styles.
### Karta theme preset
The Karta theme preset is the default widget appearance aligned to Karta's brand
system.
### Moss theme preset
The Moss theme preset is a green-forward widget appearance preset.
### Cobalt theme preset
The Cobalt theme preset is a blue-forward widget appearance preset.
### theme accent
Theme accent is the primary accent color used by the widget for controls,
states, and highlights.
### theme greeting
Theme greeting is the first message or opening text shown by the widget.
### suggested prompts
Suggested prompts are starter messages shown to help users begin a chat.
### message visibility
Message visibility controls whether user and agent messages are shown in the
widget UI.
### thinking visibility
Thinking visibility controls whether reasoning or thinking-related events are
shown in the widget UI.
### tool visibility
Tool visibility controls whether tool-use events are shown in the widget UI.
### approval visibility
Approval visibility controls whether approval prompts and approval state are
shown in the widget UI.
### hidden approval timeout
Hidden approval timeout is the timeout applied when approval UI is hidden and a
turn cannot wait indefinitely for visible user input.
### popup mode
Popup mode displays the widget as a launcher plus floating chat panel.
### fullsize mode
Fullsize mode displays the widget as a larger embedded chat surface.
### widget behavior config
Widget behavior config controls runtime behavior such as visibility, consent,
suggested prompts, and interaction mode.
### consent markdown
Consent markdown is the configured Markdown content shown before a user accepts
a pre-chat disclosure.
### consent sanitizer
The consent sanitizer removes unsafe markup from consent markdown before it is
rendered in the browser.
### requireAccept
`requireAccept` is the widget setting that requires a user to accept the
pre-chat consent text before sending a message.
### localization
Localization is widget configuration for user-facing strings in the user's
language or locale.
### input placeholder
The input placeholder is the placeholder text shown in the widget message input.
### accessible send label
The accessible send label is the screen-reader label for the widget send
button.
### chat panel dialog label
The chat panel dialog label is the accessible label for the widget chat dialog.
### powered-by footer
The powered-by footer is the widget attribution area that identifies the agent
experience as powered by Karta.
### @karta/widget
`@karta/widget` is the package or bundle surface for the hosted widget runtime.
### @karta/react
`@karta/react` is the React integration package for using Karta widget and
headless-agent components in React applications.
### KartaAgentClient
`KartaAgentClient` is the headless client used to create sessions, send
messages, and stream events without using the hosted widget UI.
### KartaWidget React component
The `KartaWidget` React component embeds the Karta widget in a React
application.
### useKartaAgent hook
The `useKartaAgent` hook is the React hook for driving a Karta agent session
from custom UI.
### tokenEndpoint
`tokenEndpoint` is the backend endpoint a frontend calls to mint a session token
without exposing an API key.
### tokenFn
`tokenFn` is a frontend callback that supplies a session token to the headless
client or React integration.
### static token
A static token is a pre-supplied session token used by a frontend integration,
usually for testing or controlled server-rendered contexts.
### widget local dev caveat
The widget local dev caveat is that local browser testing still has to respect
origin, token, and CSP behavior that may differ from production.
### graceful limit\_reached state
A graceful `limit_reached` state is the user-facing widget behavior when spend
or usage limits block additional work.
### CSP directive
A CSP directive is one rule inside a Content Security Policy, such as
`script-src`, `connect-src`, or `frame-src`.
### frame source
A frame source is an origin or URL pattern allowed to be embedded by a page's
frame policy.
### data path disclosure
A data path disclosure explains what user messages, model calls, logs, and
provider traffic pass through during a widget interaction.
### kt\_live key
A `kt_live` key is a live Karta API key for server-side, CLI, CI, or management
use.
### kt\_test key
A `kt_test` key is a test-mode Karta API key for non-production development or
testing flows.
### fine-grained scope
A fine-grained scope grants an API key one named class of operations, such as
reading agents, activating releases, or managing model credentials.
### agent-scoped session token
An agent-scoped session token can drive one deployed agent without granting
organization-wide API access.
### token scope
Token scope is the resource and action boundary encoded into a token.
### sub claim
The `sub` claim is the verified subject value bound into a session token.
### ek claim
The `ek` claim identifies the embed key context associated with a session token.
### act claim
The `act` claim identifies actor or acting-party context inside a token.
### stepped\_up\_at claim
The `stepped_up_at` claim records when the host app completed a stronger
verification step for the user.
### aal claim
The `aal` claim records the authentication assurance label, such as `mfa`, that
the host app signed into a structured identity token.
### session-token mint endpoint
The session-token mint endpoint creates short-lived session tokens for browser
or frontend integrations.
### backend-minted session token
A backend-minted session token is created by your server with an API key and
then handed to the browser.
### embed-minted session token
An embed-minted session token is created from an embed key and browser origin
checks for widget use.
### structured identity token
A structured identity token is a signed token that can carry verified user id
and step-up claims in addition to a user id.
### host-attested step-up
Host-attested step-up means your application signs proof of a recent stronger
authentication step into the identity token.
### identity mismatch
Identity mismatch is the error state where the signed identity token does not
match the user id or session identity being requested.
### MFA
MFA, or multi-factor authentication, is a stronger authentication step using
more than one factor.
### TOTP
TOTP is a time-based one-time password used as an MFA factor.
### WebAuthn passkey
A WebAuthn passkey is a phishing-resistant credential backed by the WebAuthn
standard.
### recovery code
A recovery code is a backup code used to regain account access when normal MFA
is unavailable.
### step-up reauthentication
Step-up reauthentication is asking the user to complete a stronger auth check
before a sensitive action continues.
### account lockout
Account lockout is the state where login or sensitive account actions are
blocked after too many failed or risky attempts.
### email confirmation
Email confirmation is the process of proving control of an email address before
using it for account access.
### breached-password check
A breached-password check rejects or warns about passwords known to appear in
public breach corpuses.
### user
A user is a person represented in Karta for login, organization membership,
widget identity, or session attribution.
### organization membership
Organization membership is the relationship between a user and an organization,
including role and access level.
### owner role
The owner role is the highest organization role, with authority over billing,
members, keys, and critical settings.
### admin role
The admin role can manage most organization resources without necessarily being
the billing or ownership authority.
### developer role
The developer role can work with agents, releases, sessions, and technical
configuration according to organization policy.
### billing role
The billing role can view or manage billing, credits, invoices, and plan state.
### viewer role
The viewer role can inspect permitted resources without making changes.
### organization settings
Organization settings are account-level configuration for members, roles, keys,
security, billing, and integrations.
## Models, billing, and API concept index
### Anthropic subscription connector
An Anthropic subscription connector is a model connector that uses an Anthropic
subscription token instead of a provider API key. Use it only for the
subscriber's own coding work on Karta, not for serving end-user, virtual employee,
backend-job, or customer traffic.
Aliases: OAuth subscription token
### provider key rotation
Provider key rotation is replacing or revoking a stored model-provider
credential so future turns use the updated connector state.
### provider quota
Provider quota is the rate, usage, or account limit enforced by the selected
model provider.
### provider-key rejection
Provider-key rejection is a provider refusing a stored BYOK credential during a
turn. Karta surfaces this as `byok_key_rejected`.
### model call failure
A model call failure is a turn failure while calling the selected model provider
or managed model path.
### org default model
An org default model is the model-selection pair an organization uses when an
agent has not chosen its own model.
### agent model override
An agent model override is a per-agent model-selection setting that replaces the
organization default for that agent.
### model catalog
A model catalog is the list of model ids available from a selected model
connector.
Aliases: ProviderModel
### model\_source
`model_source` is the agent model-selection setting that decides whether the
agent inherits the org default, uses managed model access, or uses a selected
model key.
### model\_key\_id
`model_key_id` identifies the stored model key or connector selected for model
routing.
### default\_model\_id
`default_model_id` is the model id chosen as the organization default or an
agent-level override.
### Karta platform connector
The Karta platform connector is the model-selection option representing
Karta-managed model access rather than a customer-provided provider key.
### model pricing
Model pricing is the per-model rate information used to calculate managed usage
cost and populate the rate card.
### input tokens
Input tokens are the tokens sent into the model for a turn. Karta records them
so usage, cost, and budget checks can be calculated.
### output tokens
Output tokens are the tokens produced by the model for a turn. Karta records
them separately from input tokens for reporting and cost calculation.
### total tokens
Total tokens are the combined input and output tokens for a turn or reporting
period.
### token cost
Token cost is the cost calculated from metered tokens and the applicable model
pricing.
### cost cap
A cost cap is a budget limit expressed in money rather than tokens.
### token cap
A token cap is a budget limit expressed in input, output, or total tokens.
### org budget
An org budget is the organization-level budget that gates consumption before new
work runs.
Aliases: OrganizationBudget
### budget threshold
A budget threshold is a configured point near or at a cap where Karta can notify
you.
### 402 Payment Required
`402 Payment Required` is the HTTP status Karta returns when spend, credits,
subscription state, or a cap blocks new work before it runs.
Aliases: 402
### budget\_exhausted
`budget_exhausted` is the stable error code for a request blocked by an
organization budget or configured cap.
### credits\_exhausted
`credits_exhausted` is the reason code for a managed-plan organization whose
prepaid credit balance is empty.
### subscription\_past\_due
`subscription_past_due` is the reason code for a billing state that blocks
consumption.
### per-user spend cap
A per-user spend cap limits monthly spend for one verified user across the
kartas they use.
### per-karta spend cap
A per-karta spend cap limits spend for one durable karta, such as a virtual
employee, backend job, or fleet member.
### per-seat spend cap
A per-seat spend cap limits one verified user's spend inside a shared virtual
employee karta.
### api-key attribution
API-key attribution assigns usage and cost to the API key that authenticated the
work when that key is available.
### embed-key attribution
Embed-key attribution assigns usage and cost to the publishable widget key
involved in a browser session.
### end-user attribution
End-user attribution assigns usage and cost to the verified acting user when
Karta has a trusted subject.
### usage summary
A usage summary is the current-period rollup of usage, spend, and budget state
returned by the CLI, SDK, or dashboard.
### billing status
Billing status is the organization's current billing and subscription state.
### prepaid credit balance
A prepaid credit balance is the remaining credit value available for managed
plan usage.
### prepaid gate
The prepaid gate is the request-time check that prevents managed usage from
exceeding collected prepaid credits.
### managed plan
A managed plan is a plan where model usage runs through Karta-managed model
access and draws down prepaid credits.
### credit pack
A credit pack is a prepaid top-up purchased from the billing page.
### no-billing mode
No-billing mode is the configuration where payment wiring is absent but the app
remains usable on the free plan.
### plan
A plan is the billing tier family for an organization, such as free, pro, or
enterprise.
Aliases: Plan
### free tier
The free tier is the entry plan for starting without a card or provider key.
### pro tier
The pro tier is a paid self-serve plan for ongoing use.
### enterprise tier
The enterprise tier is the custom plan path for negotiated usage, support, or
commercial terms.
### price version
A price version is an immutable set of pricing terms pinned for an organization.
Aliases: PriceVersion
### pricing strategy
A pricing strategy is the versioned calculation Karta uses to turn usage into
credit drawdown or fee amounts.
### flat fee breakage
Flat fee breakage is the pricing behavior where included monthly value or
bucketed credits expire instead of rolling over.
### subscription
A subscription is the recurring plan relationship for an organization.
### usage event
A usage event is an immutable metered record for tokens, model, organization,
and available attribution fields.
Aliases: UsageEvent
### usage aggregate
A usage aggregate is a materialized rollup of usage events used for fast budget
and reporting reads.
Aliases: UsageAggregate
### usage instance aggregate
A usage instance aggregate is a rollup of usage at the karta and end-user grain.
Aliases: UsageInstanceAggregate
### credit ledger entry
A credit ledger entry is an append-only record of a prepaid credit purchase,
grant, expiry, refund, or adjustment.
Aliases: CreditLedgerEntry
### monthly included bucket
A monthly included bucket is included credit value granted for a billing period.
### credit burn
Credit burn is the recorded drawdown of prepaid credits from metered usage.
Aliases: CreditBurn
### auto-refill
Auto-refill is an optional billing setting that buys a selected credit pack when
the balance drops below a threshold.
Aliases: CreditAutoRefill
### livemode
`livemode` is the product flag that distinguishes live usage from test-mode
usage in billing and reporting data.
### test mode
Test mode is the non-live mode for trying API, widget, or console flows without
mixing the results into live usage views.
### HTTP API
The HTTP API is Karta's web API for creating sessions, sending messages,
streaming responses, resolving inputs, and using adapter shapes.
### API reference
The API reference is the public docs section that describes Karta's HTTP routes,
auth, request shapes, response shapes, errors, and adapters.
### versioned paths
Versioned paths are public API paths grouped under a version prefix.
Aliases: /v1
### JSON request
A JSON request is a request body sent with structured JSON to a Karta API
endpoint.
### JSON response
A JSON response is the accumulated non-streaming response body returned by Karta
APIs.
### Content-Type
`Content-Type` is the HTTP header that tells Karta how to parse a request body.
### event-sourced session
An event-sourced session is a session represented as an ordered, replayable log
of events.
Aliases: managed-agent session
### previous\_response\_id
`previous_response_id` is the OpenAI Responses adapter field used to continue
from a prior response.
### chat completions messages array
The chat completions messages array is the OpenAI Chat Completions request
format: ordered role/content message items where the last user message runs the
turn.
### adapter base URL
An adapter base URL is the `agent.karta.sh/{org}/{agent}/v1` URL you give an
existing OpenAI- or Anthropic-shaped client.
### API authentication
API authentication is how a request proves its caller to Karta, usually with a
server-side API key or a browser-safe session token.
### route family matrix
A route family matrix compares flat native routes, agent native routes, and
adapter routes by path shape, host, and accepted credentials.
### scope matrix
A scope matrix maps API operations to required key scopes.
### status code
A status code is the HTTP result code Karta returns before a response stream
starts.
### 200
`200` means a successful accumulated response or the start of a successful SSE
stream, depending on the endpoint and stream setting.
### 201
`201` means Karta created a resource, such as a release or Managed Agents
session.
### 202
`202` means Karta accepted work for asynchronous processing.
### 401
`401` means the request is missing a valid credential or the credential cannot
be authenticated.
### 403
`403` means the caller is authenticated but not allowed to perform the requested
action.
### 404
`404` means the resource is missing or intentionally hidden by default-deny
ownership checks.
### 409
`409` means the request conflicts with current resource state.
### 422
`422` means the request body is invalid or a BYOK key was rejected by the
provider.
### 429
`429` means a rate limit was reached.
### 503
`503` means Karta is temporarily unable to serve the request.
### request correlation context
Request correlation context is the timestamp, route, agent slug, session id, and
response headers a client preserves for support and debugging.
### not-found tenant oracle defense
Not-found tenant oracle defense is Karta's practice of returning the same `404`
shape for unknown, cross-tenant, and wrong-agent resources.
### capability registry
A capability registry is the server-side registry of public API operations,
including route, method, operation id, required scopes, audit action, idempotency
requirement, and execution modes.
### route capability
A route capability is one operation entry in the capability registry.
### public API surface
The public API surface is the set of documented bearer-authenticated routes
intended for SDKs, CLIs, and customer integrations.
### idempotent operation
An idempotent operation is a mutation designed so retries with the same
idempotency key produce one effect.
## SDK, observability, security, console, and policy concept index
### Python SDK
The Python SDK is `karta-runtime`, the in-process runtime for constructing a
Karta app, sending or streaming turns, opening sessions, registering hooks and
policies, and serving the same session API shape used in production.
Aliases: karta-runtime
### Karta Python object
The Karta Python object is the core `Karta` class in the Python SDK.
### Session Python object
The Session Python object is the handle returned by `app.session(...)` for one
multi-turn conversation.
### app.session
`app.session` opens a new Python SDK session handle, optionally with metadata
and harness arguments.
### app.send
`app.send` sends a message through the Python SDK and returns an accumulated
final response.
### app.stream
`app.stream` sends a message through the Python SDK and yields typed streaming
events as the turn runs.
### sync API
The sync API is the blocking SDK surface for ordinary synchronous code or
scripts.
### async API
The async API is the awaitable SDK surface for async applications, servers, or
event loops.
### hook registration
Hook registration is the SDK pattern for observing lifecycle events such as
session creation, message receipt, message completion, or agent handoff.
### policy registration
Policy registration is the SDK surface for setting deterministic guards before
a turn reaches the harness.
### HTTP serving
HTTP serving is running a Karta agent behind the local or deployed session API.
### TypeScript management SDK
The TypeScript management SDK is `@karta.sh/sdk`, a native-fetch client for
account operations such as API keys, BYOK provider keys, webhook endpoints,
usage, and billing.
Aliases: @karta.sh/sdk; Karta TypeScript client
### API key management SDK
The API key management SDK is the TypeScript management SDK resource for
listing, creating, and revoking Karta API keys.
### model key management SDK
The model key management SDK is the TypeScript management SDK resource for
creating, listing, and revoking BYOK model-provider credentials.
### webhook endpoint SDK
The webhook endpoint SDK is the TypeScript management SDK resource for creating,
listing, updating, re-enabling, and deleting outbound webhook endpoints.
### usage SDK
The usage SDK is the TypeScript management SDK resource for reading usage
summaries.
### billing SDK
The billing SDK is the TypeScript management SDK resource for reading billing
and subscription status.
### widget SDK
The widget SDK is the browser package and CDN loader for embedding a deployed
Karta agent in a site.
### headless widget SDK
The headless widget SDK is the `KartaAgentClient` surface from `@karta/widget`
for driving sessions and streaming without Karta's prebuilt UI.
### React widget bindings
React widget bindings are the `@karta/react` components and hooks over the
widget SDK.
### SDK management surface
The SDK management surface is the part of Karta's SDK/API surface used to
configure account state: keys, BYOK, webhooks, usage, billing, and related
controls.
### SDK run surface
The SDK run surface is the part of Karta's SDK/API surface used to start,
continue, or stream agent work.
### webhook event
A webhook event is a typed notification payload, such as a session, turn,
billing, budget, organization, or API-key event.
### webhook delivery
A webhook delivery is one attempt to POST a webhook event to a registered
endpoint.
### webhook signing secret
A webhook signing secret is the `whsec_...` secret shown once when an endpoint
is created.
### delivery retry
Delivery retry is Karta's retry path for failed webhook deliveries.
Aliases: delivery backoff
### auto-disable
Auto-disable is the safety behavior that turns off a webhook endpoint after a
sustained failure streak.
### SSRF protection
SSRF protection is the webhook destination guard that prevents outbound webhooks
from targeting internal or reserved network addresses.
### DNS re-resolution
DNS re-resolution is the webhook delivery-time check that resolves the endpoint
host again before connecting.
### blocked private IP
A blocked private IP is a resolved or literal address Karta refuses as a webhook
destination because it is private, loopback, link-local, internal, or reserved.
### budget webhook
A budget webhook is a webhook event for budget threshold or budget exhaustion
activity.
### billing webhook
A billing webhook is a webhook event for subscription or invoice activity.
### session webhook
A session webhook is a webhook event emitted when an agent session starts.
### turn webhook
A turn webhook is a webhook event emitted when an agent turn completes or fails.
### immutable audit event
An immutable audit event is an audit-log row that cannot be edited or deleted
after it is written.
### account-change audit
Account-change audit is the audit trail for material organization changes such
as key creation, budget changes, plan changes, release activation, or member
changes.
### operator access audit
Operator access audit is the customer-visible audit record for Karta personnel
access when support, security, abuse, legal, or service-operation needs require
it.
### AuditEvent
`AuditEvent` is the tenant-visible audit record for material account activity.
### AuditContext
`AuditContext` is the request context Karta threads into audit writes, such as
acting user, API key, IP address, and user agent.
### trust posture
Trust posture is Karta's current public security and compliance stance,
including encryption, identity controls, isolation, credential boundaries,
audit, operator access, subprocessors, and stated limitations.
### trust page
The trust page is Karta's public trust surface for security posture, policy, and
subprocessor details.
Aliases: security trust center
### safe harbor
Safe harbor is Karta's limited non-enforcement assurance for good-faith security
research that follows the vulnerability disclosure policy.
Aliases: safe harbor terms
### security.txt
`security.txt` is Karta's RFC 9116 disclosure file at
`/.well-known/security.txt`.
### encryption at rest
Encryption at rest is Karta's protection for stored data and secrets.
### encryption in transit
Encryption in transit is Karta's use of TLS/HTTPS to protect data while it
moves between systems.
### HTTPS
HTTPS is the encrypted HTTP transport Karta requires for production web surfaces
and outbound webhook endpoints.
### HSTS
HSTS is the browser policy that tells clients to use HTTPS for Karta hosts.
### strict CSP
Strict CSP is Karta's Content Security Policy posture for the public site and
console.
### frame-ancestors none
`frame-ancestors none` is the CSP directive that prevents Karta pages from being
embedded in another site's frame.
### no-wildcard script-src
No-wildcard `script-src` means Karta avoids broad script-source wildcards in its
CSP.
### operator access minimization
Operator access minimization is Karta's trust commitment that personnel access
should be limited, logged, and tied to a support, security, abuse, legal, or
service-operation need.
### tool permission boundary
A tool permission boundary is the line between what an agent may propose or
request and what it may actually execute.
### narrow tool scope
Narrow tool scope means giving an agent the smallest tool authority that can
accomplish the task.
### destructive tool approval
Destructive tool approval is the requirement that sensitive or irreversible tool
actions pause for a caller or first-party UI decision before proceeding.
### first-party handoff
First-party handoff is sending a sensitive account, billing, money, role, or
destructive action back to Karta's trusted UI instead of letting the agent
execute it directly.
### browser credential safety
Browser credential safety is the rule that browsers receive only narrow,
expiring credentials such as embed keys and session tokens.
### server credential authority
Server credential authority is the practice of keeping long-lived API keys,
identity secrets, BYOK secrets, and webhook signing secrets on trusted servers.
### network and data exposure
Network and data exposure is the residual risk created by the services, tools,
model providers, and logs an agent can reach.
### BYOK provider terms
BYOK provider terms are the customer's direct contractual and policy obligations
with the model provider whose key they supply.
### shared karta risk
Shared karta risk is the privacy and safety risk of intentionally sharing one
karta's memory and workspace across multiple people, roles, or workflows.
### bearer token risk
Bearer token risk is the risk that anyone holding a token can use it until
expiry or revocation.
### Karta console
The Karta console is the signed-in customer dashboard for building, deploying,
distributing, observing, and operating agents, kartas, keys, billing, limits,
webhooks, and audit state.
Aliases: dashboard; console; builder console; serving console
### agent overview
Agent overview is the per-agent console page summarizing serving status, current
release, integration state, configuration counts, recent activity, and useful
links.
### agent releases page
The agent releases page shows production and preview releases for one agent,
including the current production release and rollback path.
Aliases: agent releases tab
### agent environment page
The agent environment page manages environment variables referenced by
`karta.toml`.
Aliases: agent environment tab
### agent embed page
The agent embed page manages publishable embed keys and install snippets for
the chat widget.
Aliases: agent embed tab; Embed keys page
### recurring runs page
The recurring runs page manages cron-based, non-interactive runs of an agent.
Aliases: agent schedules tab
### Appearance customizer
The Appearance customizer is the per-agent console UI for configuring widget
theme, colors, type, icons, transcript visibility, tool-call display, approval
display, and embed behavior.
### Test/Live topbar toggle
The Test/Live topbar toggle switches console views between test-mode and
live-mode resources where that split is available.
### logs explorer
The logs explorer is the console page for scanning turns and sessions across
agents.
### sessions index
The sessions index is the console list of active and recent sessions visible to
the organization.
### session inspector
The session inspector is the console view for one session's message trace.
Aliases: sessions show, sessions view, karta session
### Users directory
The Users directory shows verified end users served by the organization's agents
during the current period.
Aliases: End-users directory
### Kartas page
The Kartas page lists active durable kartas for the organization or agent.
### Limits page
The Limits page is the console surface for monthly budgets and hard spend caps.
### Usage events page
The Usage events page is the operational metering ledger for the current billing
period.
Aliases: Usage page
### API keys page
The API keys page manages scoped, revocable `kt_live_...` credentials for
server, CLI, CI, and API access.
### Model connectors page
The Model connectors page manages sources of models for an organization,
including Karta platform access and customer-provided BYOK provider credentials.
Aliases: BYOK settings
### billing portal
The billing portal is the hosted customer portal Karta links to for payment
method and billing management.
### audit log page
The audit log page is the console view for immutable administrative and
security-relevant account events.
### Report a problem
Report a problem is the signed-in support form for bugs, billing or usage
problems, account issues, and other platform support requests.
### support report
A support report is the stored product-support record created from Report a
problem.
### abuse report
An abuse report is the public intake for spam, leaked API keys, content
concerns, and other platform-abuse issues.
### waitlist signup
A waitlist signup is a public request for access during invite-gated
availability.
### closed beta invitation
A closed beta invitation is a signup gate pass that lets one invited person
create a Karta account while public registration is invite-only.
### organization invitation
An organization invitation is an email-bound invite to join an existing Karta
organization with a specified role.
### invite-only signup gate
The invite-only signup gate is the registration control that limits account
creation to closed beta invitations or organization invitation codes.
### onboarding checklist
An onboarding checklist is a guided set of first tasks that helps a new
organization configure agents, keys, budgets, and integrations.
### first-run checklist
A first-run checklist is a shorter guided set of tasks for getting a first agent
running.
### AgentTemplate registry
The AgentTemplate registry is the source-controlled set of built-in new-agent
templates.
### ConsoleCopilot proposal
A ConsoleCopilot proposal is a pending account action suggested by Karta's
console agent but not executed by the agent.
### proposal approval
Proposal approval is the first-party action that executes a live ConsoleCopilot
proposal after re-checking authorization, liveness, parameters, and any step-up
requirements.
### proposal cancel
Proposal cancel is the first-party action that dismisses a pending
ConsoleCopilot proposal without executing it.
### action claim
An action claim is the session-token claim that allows the console or home-page
Karta agent to read capabilities and propose account actions.
### tier-1 action
A tier-1 action is a ConsoleCopilot action that can execute after ordinary
proposal approval.
### tier-2 action
A tier-2 action is a higher-risk ConsoleCopilot action that requires a fresh
step-up before approval can execute.
Aliases: step-up-gated action
### Terms of Service
The Terms of Service are the master agreement governing access to and use of
Karta's platform, dashboard, runtime, APIs, CLI, widget, hosted chat,
documentation, and related services.
### Privacy Policy
The Privacy Policy explains how Karta handles personal information when Karta
acts as a controller.
### Data Processing Addendum
The Data Processing Addendum is the processor agreement for Customer Personal
Data and End-User Data Karta processes on behalf of a customer.
### Acceptable Use Policy
The Acceptable Use Policy defines prohibited uses of Karta by customers,
authorized users, end users, agents, integrations, accounts, keys, embeds, and
releases.
### Trust and Safety Policy
The Trust and Safety Policy describes how Karta receives reports, investigates
suspected abuse, enforces the Acceptable Use Policy, and allocates
responsibility between Karta and customers.
### Support Policy
The Support Policy describes the support channels, covered topics, and
exclusions for Karta platform support.
### Refund and Billing Policy
The Refund and Billing Policy governs subscriptions, prepaid credits,
Karta-managed usage, BYOK billing allocation, auto-refill, refunds, chargebacks,
taxes, and failed payments.
### Cookie Notice
The Cookie Notice explains Karta's use of cookies, local storage, pixels, and
similar technologies on Karta-controlled sites and surfaces.
### DMCA policy
The DMCA policy is Karta's copyright notice and takedown page.
### SLA
An SLA is a service-level agreement for availability, response targets, service
credits, or similar remedies.
### Sub-processor List
The Sub-processor List identifies third parties Karta uses to process Customer
Data or End-User Data in providing the service.
### AI model use and data handling policy
The AI model use and data handling policy explains how Karta handles model
access, inputs, outputs, agent actions, BYOK, model-provider terms, AI-specific
risk, and data associated with AI processing.
### US state privacy notice
The US state privacy notice supplements the Privacy Policy for residents of
states with comprehensive privacy laws.
### abuse reporting
Abuse reporting is the path for suspected platform abuse, leaked keys, harmful
content, spam, fraud, or policy violations.
### privacy data request
A privacy data request is a request to access, correct, delete, port, restrict,
object to, or otherwise exercise rights over personal information for which
Karta is the controller.