Configuration

karta.jsonc is an optional file that tunes Karta’s behavior without touching your agent definitions. It is JSONC (JSON with comments and trailing commas). Every key is optional, and the file lives at ./karta.jsonc in the agent project folder.

Choose the right config file

File	Owns	Read by
`karta.jsonc`	CLI rendering, local participant profile, Claude harness runtime knobs, and deployment approval mode.	`karta dev`, the Python SDK runtime, and the Claude harness.
`karta.toml`	Agent identity, deploy gate, buildpack, entry point, and declared env vars.	`karta setup`, `karta status`, `karta deploy`, and the release builder.
`.opencode/opencode.jsonc`	OpenCode’s own harness behavior.	OpenCode.

Full example

karta.jsonc

{
  // How the CLI renders and gates a turn
  "cli": {
    "hidden_event_types": ["system", "step_start"],
    "input_required_policy": "prompt",
    "input_required_hidden_policy": "deny"
  },

  // Harness-specific settings
  "harness": {
    "claude": {
      "idle_timeout_seconds": 600,
      "thinking_budget_tokens": 10000,
      "permission_intercept": false,
      "agent_command": false
    }
  },

  // Deployment runtime behavior
  "runtime": {
    "permission_mode": "interactive"
  },

  // CLI user profile
  "profile": {
    "name": "alice",
    "display_name": "Alice Chen"
  }
}

Behavior summary

Key	Default when missing or invalid	Allowed values	Use when
`cli.hidden_event_types`	`["system"]`; an empty list hides nothing.	Non-empty strings.	Quiet local `karta dev` output without changing what the runtime emits.
`cli.input_required_policy`	`prompt`	`prompt`, `deny`, `approve_once`, `approve_session`, `error`	Decide how the CLI responds when a visible turn pauses for approval.
`cli.input_required_hidden_policy`	No override.	`deny`, `approve_once`, `approve_session`, `error`	Decide hidden approval prompts without asking the user.
`harness.claude.idle_timeout_seconds`	`600`	Positive integer.	Keep a Claude harness process warm longer or shorter between turns.
`harness.claude.thinking_budget_tokens`	Unset.	Positive integer.	Set the extended-thinking budget for Claude turns that request reasoning.
`harness.claude.permission_intercept`	`false`	Boolean.	Let Karta handle Claude approval prompts instead of leaving them to Claude.
`harness.claude.agent_command`	`false`	Boolean.	Enable the Claude agent command surface.
`runtime.permission_mode`	`interactive` behavior.	`interactive`, `autonomous`, `approve_session`	Make deployed/headless sessions auto-approve for the session.
`profile.name`	OS username.	Non-empty string.	Set the default human participant id for local CLI sessions.
`profile.display_name`	Same as `profile.name`.	String.	Set the display label shown for the local participant.

`cli`

cli.hidden_event_types

string[]

Event types the CLI should not render - e.g. ["system", "step_start"]. Useful to quiet noisy harness internals.

cli.input_required_policy

string

default:"prompt"

How the CLI handles input_required approval prompts: prompt, deny, approve_once, approve_session, or error.

cli.input_required_hidden_policy

string

default:"deny"

The auto-decision applied to approval prompts that are hidden (so the user is not asked for events they cannot see).

`harness.claude`

harness.claude.idle_timeout_seconds

integer

default:"600"

How long the harness may stay idle before it is shut down.

harness.claude.thinking_budget_tokens

integer

Optional extended-thinking budget for turns that request reasoning.

harness.claude.permission_intercept

boolean

default:"false"

Whether Karta intercepts the harness’s approval prompts (vs. letting the harness handle them).

harness.claude.agent_command

boolean

default:"false"

Enables the agent command surface.

`runtime`

runtime.permission_mode

string

default:"interactive"

How a deployed agent treats approvals for tools that are not on the .claude/settings.json allowlist. interactive pauses each off-allowlist tool as a tool-permission prompt the end user answers over the API (approve_once, approve_session, deny); autonomous auto-approves for the session (maps to approve_session). Set autonomous for unattended/headless deployments that should never pause - it bypasses the approval prompt entirely, so reserve it for trusted agents.

`profile`

profile.name

string

The default human participant name for CLI sessions.

profile.display_name

string

A friendly display name for that participant. Falls back to your OS user if unset.

karta.jsonc governs run-time behavior; karta.toml governs publish/build. OpenCode’s own harness config lives separately in .opencode/opencode.jsonc.

Verify the file is being read

Run a one-shot local turn with an explicit config path:

karta dev --config karta.jsonc -m "hello"

To check the deployed approval mode from Python, create a session and inspect its permission_mode:

from app import app

session = app.session()
print(session.permission_mode)  # approve_session when runtime.permission_mode is autonomous

If a value has the wrong type or is outside the allowed set, Karta ignores that value and uses the default shown above.

Get started

Concepts

Agent project

The CLI

Deploy

Platform

Security

Enterprise

Tutorials

Configuration

Choose the right config file

Full example

Behavior summary

`cli`

`harness.claude`

`runtime`

`profile`

Verify the file is being read

​Choose the right config file

​Full example

​Behavior summary

​cli

​harness.claude

​runtime

​profile

​Verify the file is being read

Choose the right config file

Full example

Behavior summary

`cli`

`harness.claude`

`runtime`

`profile`

Verify the file is being read