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, every terminal paste with a line break asks for confirmation, programs cannot put text on the clipboard with OSC 52, the previous session is not reopened at startup, the output of terminal panes is not saved for it, 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. This holds for [rule.ai-memory] too: an unknown key there is logged and ignored, so check the log after you change that table.

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, split panes (to a new connection or the same server), 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.

Open Group in Quick Connect skips every connection of the group whose server or jump server is blocked and names them all in one policy message; the other connections of the group still open. Connect in the Connection Manager, a tab's Duplicate and Reopen Closed Tab check the policy before they ask for a password, a temporary SSH key or the master password, and an open tab checks it again on every connect and reconnect attempt, because editing a saved connection also changes the tabs already opened from it. If such an edit points a tab at a blocked server or jump server, its terminal shows the policy message and korTTY stops trying, including automatic reconnects.

Local shells and serial connections have no server and are not checked against [rule.servers]; serial ports are governed by serial-connections under [rule.features] instead.

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]¶

Stored script text of analyses¶

A Full code analysis stores the script text it worked on — the analysed script, the text an apply started from, the proposed result and the accepted text — so the code preview, View changes, the script export, the report appendix, Restore intermediate state and resuming after a restart keep working. Users choose the size themselves under Settings → Snippet Editor → Stored script size per analysis (default 1 MB, maximum 5 MB, or Off); analysis-max-stored-content-bytes in [rule.snippets] is an upper bound on top of that choice:

[[rule]]
name = "Keep script text small"
  [rule.snippets]
  analysis-max-stored-content-bytes = 524_288      # at most 512 KB per stored text

[[rule]]
name = "Compliance team: no script text in analyses"
groups = ["compliance"]
  [rule.snippets]
  analysis-max-stored-content-bytes = 0            # findings and reports only

• Effective limit — The smaller of the user's own value (default 1 MB), the fixed 5 MB maximum and this key. A value above 5 MB therefore changes nothing, and a user's lower value stays in force. Any positive value is accepted, also one below the 256 KB minimum users can pick.
• 0 — No script text is stored at all: the analysis keeps its findings, summary, diagram and reports, but not the script, so View changes, the older entries' code preview, the script export, the report appendix, Restore intermediate state and resuming after a restart are unavailable, and the panel says the organization does not allow storing script text. The analysis itself, applying findings and the immediate change review in the editor work as before. Text stored earlier is dropped from the stored analyses the next time they are written.
• Settings dialog — The dropdown only offers sizes up to the cap, shows the cap beneath it and is locked (with the "Managed by your organization" hint) when the value is 0. The user's own choice is not overwritten by the cap: it applies again when the policy is lifted.
• Tiers — Like every setting the most specific tier that sets the key wins (user, then group, then all); rules of the same tier take the smaller value, so 0 beats every positive cap. The key is not a 0-means-unlimited value.
• Invalid values — A negative number or a non-integer (for example "5 MB") is a policy error like any other malformed value, so the whole file is rejected and the lockdown fallback applies; the fallback forbids storing script text too. Write bytes, optionally with TOML digit separators (5_242_880).

[rule.ai-memory]¶

The [rule.ai-memory] table sets how the korTTY memory may be used. Every key is optional; a key the policy does not set keeps the user's own choice. A value outside the listed ones rejects the whole file. An unknown key is a warning in the log and is ignored, like in every other table. As with the other keys, the most specific tier that sets a key wins (user, then group, then all); inside one tier the strictest value applies: disabled over read-only over editable, propose under off, never over always over auto, the smaller token cap, and false over true for the switches.

Organisation memory¶

[[organization-memory]] blocks hold rules for the AI that users cannot change. Each block has a title and a content text. korTTY sends the blocks in full, ahead of the user's own memory, with every AI request of every user, and does not cut them to the token budget. A block whose title or content is longer than 8000 characters, or that the secret guard refuses, is dropped with a warning that names the field and the line, never the value. The file holds at most 20 blocks and 16000 characters in all; a block that would exceed either limit is dropped with a warning, and the blocks after it are still checked.

Organisation memory is sent only while the policy allows the AI features and does not deny ai-memory. The user's own Use memory switch and the user-memory key do not stop it.

[rule.ai-runtime]¶

[rule.updates]¶

[rule.backup]¶

Sets and locks the automatic backup in Settings → Backup. Each key forces the matching setting; the user sees it with the "managed by your organization" hint. The backup itself keeps the user's encryption mode and credential or GPG key, and it is never written unencrypted.

[[rule]]
  [rule.backup]
  auto-interval = "daily"
  auto-directory = "~/Backups/korTTY"

[rule.terminal]¶

[[rule]]
  [rule.features]
  multi-exec = "deny"

  [rule.security]
  allow-osc52-clipboard-write = false
  allow-osc5522-clipboard-read = false

  [rule.terminal]
  paste-warning = "always"
  session-restore = "ask"
  session-restore-output = false

[rule.sftp]¶

[[rule]]
  [rule.features]
  file-transfer = "allow"
  sftp-sudo-edit = "deny"

  [rule.sftp]
  max-parallel-transfers = 2
  conflict-default = "ask"

A malformed policy file falls back to lockdown, which denies file-transfer and sftp-sudo-edit like every other feature.

Archives created on the server by the SFTP manager never carry a password, whatever the policy says: zip and 7z take a password only on their command line or from a terminal, and on the command line every other user of the server can read it in the process list. Password-protected archives on the server are likewise refused by Extract Here.... Archives created on the user's own computer can still have a password, so no policy key is needed to keep server passwords out of process lists.

[rule.isolation]¶

[[rule]]
  [rule.features]
  incognito-sessions = "deny"

  [rule.isolation]
  minimum = "sandbox"

[rule.job-scheduler]¶

The check runs right before every send, the Send test button included. A webhook to a host outside the list is not sent, and the job journal records notification blocked by policy with the job, the target's name and the host, never the URL. While job-webhooks is denied, the Notifications section of a job that has webhook targets ticked says that they receive nothing.

[[rule]]
  [rule.features]
  job-webhooks = "allow"

  [rule.job-scheduler]
  webhook-host-allowlist = ["hooks.slack.com", "logic.azure.com", "api.powerplatform.com"]

A malformed policy file falls back to lockdown, which denies job-webhooks like every other feature.

[rule.logging]¶

The terminal-* keys below apply to terminal output logs. Unset values leave the connection preference in effect. They resolve per field using the existing rule tiers; at the same tier false wins for username, while directory choices resolve in the order none, relative, full. The logger applies them at startup as well as locking the connection editor controls. Unknown working directories remain empty. These keys do not enable logging on their own.

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.

korTTY applies the same rules to a terminal selection, and to a file attached to it, before they are sent to an AI profile other than an integrated model or a trusted local endpoint; see Masking secrets before sending.

[[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, text dropped onto it from another application, which is refused, and text that a program in the terminal copies with OSC 52 or OSC 5522 where Settings → Terminal allows it, which lands in the internal clipboard only; a program that reads with OSC 5522 gets the internal clipboard), 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¶