Policy configuration¶

In managed environments an administrator can restrict or preconfigure korTTY through a single TOML file, kortty-policy.toml, placed in the installation directory. Users cannot change or bypass it: the file is only read from the admin-writable installation folder, locked settings appear grayed out with a "Managed by your organization" hint, and hand-editing global-settings.xml is undone on the next load. This chapter explains where the file lives, how rules target users, groups and servers, and documents every available parameter with examples.

File location and security model¶

korTTY loads the policy exclusively from the policy/ folder of its installation directory — the folder that also holds the application jar — and never from ~/.kortty/ or any other user-writable location. A ready-to-copy template ships as policy/kortty-policy.toml.example; copy it to kortty-policy.toml in the same folder and restart korTTY (there is no hot reload).

The enforcement model relies on the operating system's file permissions: the installation directory must be writable only by administrators, which is the default for the locations above. korTTY additionally logs a warning when the active policy file is writable by the current user. During development (never in a packaged installation) a policy can be tested with -Dkortty.policy.file=/path/to/policy.toml.

If the file exists but cannot be parsed or contains an invalid value, korTTY starts in a fail-safe lockdown: every policy-controllable feature is denied, no server connection is allowed, and a startup dialog names the file and the exact error position. A typo can therefore never silently disable enforcement. One invalid rule rejects the entire file; unknown keys only produce log warnings, so a policy written for a newer korTTY does not lock out users of an older version.

Users, groups and rule precedence¶

Rules target the current OS login name (matched lowercase). Group membership comes from two sources at once: groups defined in the policy's [groups] table, and the user's OS-level group memberships. On domain-joined Windows machines the OS groups include Active Directory groups, so rules can target AD groups directly — both fully qualified (ACME\Operations) and as the bare name (operations) — without any directory server configuration.

Each [[rule]] block optionally names users and/or groups; a rule naming neither applies to every user. Per setting, the most specific tier that sets it wins: user beats group beats everyone. That is the familiar group-policy pattern — lock everything down in a baseline rule for everyone, then relax individual settings for a trusted group. When several rules of the same tier set the same key, the most restrictive value applies (deny over read-only over confirm over allow); for server rules, a connection must pass every applicable restriction of the winning tier. The order of rules in the file has no significance.

[meta]
schema-version = 1
organization = "ACME Corp"

[groups]
devs = ["alice", "bob"]

[[rule]]                              # applies to ALL users
name = "company-baseline"
  [rule.features]
  ai-agent = "deny"

[[rule]]                              # group tier: relaxes the baseline for ops
name = "ops-exception"
groups = ["ops", "ACME\\Operations"]  # policy group OR OS/AD group
  [rule.features]
  ai-agent = "allow"
  ai-agent-execution = "confirm"

[[rule]]                              # user tier: beats eve's group
users = ["eve"]
  [rule.features]
  ai-agent = "deny"

Server access control¶

The [rule.servers] table restricts which servers a user may connect to — as an allow-list (mode = "allow": only listed servers are reachable) or a deny-list (mode = "deny": listed servers are blocked). The restriction is enforced centrally for every connection path: saved connections, QuickConnect, session restore, SFTP, teamwork-shared connections, AI swarm targets and scheduled jobs, including the jump host of a connection. Blocked connections stay visible in the connection manager but are grayed out with a lock marker, and any connect attempt shows a clear policy message.

Patterns match the host string exactly as configured in the connection — korTTY never resolves DNS for policy checks, so host names and IP addresses are separate namespaces: if a server is reachable both ways, list both.

[[rule]]
  [rule.servers]
  mode  = "deny"
  hosts = ["*.prod.acme.com", "vault.acme.com:22", "192.168.10.42", "10.99.0.0/16", "10.20.0.100-10.20.0.199"]

Parameter reference¶

[meta]¶

[groups]¶

[[rule]] scope¶

[rule.servers]¶

[rule.features]¶

[rule.security]¶

[rule.teamwork], [rule.snippets], [rule.ai-profiles]¶

[rule.ai-runtime]¶

[rule.updates]¶

[rule.terminal]¶

[rule.logging]¶

korTTY rotates its log daily (kortty.YYYY-MM-DD.log); this table controls where the files go, how long they live, how they are formatted and how rotation is capped. Directory and retention are forced into the corresponding (then locked) user settings; format, compression and the rotation caps have no user setting and act directly. The configuration is applied before the very first log line of a start, so even startup logging follows the admin's scheme.

[[rule]]
  [rule.logging]
  directory = "/var/log/kortty"
  retention-days = 30
  compress = true
  format = "json"
  rotation-max-files = 14
  rotation-total-size-mb = 512

[rule.session-journal]¶

Mandates for the session journal. Forced values lock the corresponding controls in the journal options, the settings dialog and the connection editor with a "managed by your organization" hint.

[[rule]]
  [rule.features]
  session-journal = "allow"
  [rule.session-journal]
  enforced = true
  log-format = "json"
  storage-path = "/srv/audit/kortty-journals"
  allow-delete = false
  name-template = "{connection} {date} {time} ({user})"

[[rule.session-journal.replace]]¶

Automatic search-and-replace in every journal — the way to keep a whole category of secret out of the transcript, instead of relying on the user to notice it. Each entry is one rule, and a rule may use a regular expression.

[[rule]]
  [rule.session-journal]
  enforced = true

    [[rule.session-journal.replace]]
    pattern = "AKIA[0-9A-Z]{16}"
    replacement = "***AWS-ACCESS-KEY***"
    regex = true
    label = "AWS access keys"

    [[rule.session-journal.replace]]
    pattern = "(?i)bearer\\s+[A-Za-z0-9._-]{20,}"
    replacement = "Bearer ***"
    regex = true
    label = "Bearer tokens"

    [[rule.session-journal.replace]]
    pattern = "vpn.internal.acme.corp"
    replacement = "<internal-host>"
    ignore-case = true

The rules run on the capture thread, before a line is written, so a matching text never reaches the log file at all, and they are applied to AI summaries and user notes as well. Unlike the other keys, replacement rules are merged across every matching rule and every tier rather than the highest tier winning: more redaction is the more restrictive outcome, so a user- or group-specific rule can only add patterns, never switch the organization-wide ones off. Duplicate entries are collapsed.

Admin-provided objects¶

These top-level tables define objects that appear read-only for every user, marked "Provided by your organization". They are rebuilt from the policy on every start and are never written into the user's configuration files — removing them from the policy removes them from korTTY.

Internal clipboard mode¶

With clipboard-mode = "internal" korTTY detaches from the operating system clipboard entirely and uses its own in-memory clipboard instead: text copied in another application cannot be pasted anywhere in korTTY, and text copied in korTTY never reaches the OS clipboard — while copy, cut and paste within korTTY keep working everywhere, because terminals, SFTP views, the snippet editor and all dialogs share the same internal buffer. Because this is pure application logic and no OS clipboard isolation API is involved, it behaves identically on macOS, Windows and Linux, including the X11 primary selection (middle-click paste): pasting middle-click content from other applications is blocked, middle-click paste of korTTY-internal copies keeps working.

The mode covers the terminal (shortcuts, context menu, middle-click), the code editor, all copy buttons, the ${clipboard} snippet variable, and the copy/cut/paste shortcuts of plain input fields. Copying images (AI-generated pictures, diagram exports) is unavailable in internal mode, since an image can only be shared via the OS clipboard.

Encrypted API keys¶

An AI profile's API key never appears in plain text in the policy. The administrator encrypts it once from a terminal — the command prints a kortty-enc:v1: value for the api-key-encrypted key:

korTTY --encrypt-policy-value

Users see only "API key provided by your organization" in the profile; the key is decrypted in memory at the moment a request is made.

Troubleshooting¶