Teamwork (shared connections)¶

Share SSH connections with your team by syncing them from a Git repository or shared file. Teamwork sources are loaded into the Connection Manager alongside your local connections, kept in sync automatically, and safely stripped of inline passwords so credentials come only from your local encrypted storage. Sync is one way: korTTY reads from a source and never writes back to it.

Overview¶

Teamwork lets teams maintain a centralized library of connection configurations:

• Git repositories — Clone and keep in sync with a Git repo containing a kortty-teamwork-connections.xml file (or legacy connections.xml).
• Shared files — Load connections from a local or network path. korTTY only reads the file.
• Automatic sync — Background syncing at a configurable interval checks for updates.
• Credential security — Shared connections do NOT carry inline passwords; only credential IDs and SSH key references.
• Local overrides — Your local credentials and SSH keys are merged with shared connection definitions.
• One-way sync — korTTY never pushes to a repository or writes to a shared file. Shared connections are changed in the source itself and arrive with the next sync.

Setting up teamwork sources¶

Open Teamwork → Teamwork Settings… to configure sources.

Add a source¶

1. Click Add to create a new source.
2. Choose the source Type:
3. Git — Clone from an HTTPS, SSH, or git:// URL.
4. Shared File — Read from a local or network path (e.g., file:///mnt/share/connections.xml or //host/share/connections.xml).
5. Enter the Location:
6. For Git: the clone URL.
7. For Shared File: a local/network file path (can be a file:// URI or a UNC path).
8. Set the Check Interval (1–1440 minutes; default: 15).
9. Click OK to save.

Manage sources¶

The Teamwork Settings dialog lists all sources with their type, location, and sync interval:

Use the buttons to: - Add — Create a new source. - Edit — Modify the selected source. - Delete — Remove the selected source. - Enable/Disable — Toggle the enabled state for the selected sources.

At the bottom, set the Default Check Interval (applies to new sources that don't specify one).

How synchronization works¶

Background sync¶

korTTY syncs teamwork sources in the background:

1. When korTTY starts, it starts a background sync thread and syncs right away.
2. Every N minutes (the shortest check interval among the sources enabled when korTTY started), it:
3. Pulls/clones each source (Git) or reads the file (Shared File).
4. Loads the connections XML.
5. Replaces the cached copy of each source it fetched and refreshes the Connection Manager.
6. If a source update fails, the previous cached version is kept.

Saving the Teamwork Settings syncs once right away. A changed check interval takes effect the next time korTTY starts.

Manual sync¶

Use Teamwork → Teamwork Settings… and click OK to trigger a sync immediately.

Version tracking¶

Each sync records a version token: - Git — The current commit hash. - Shared File — The file's last-modified timestamp.

If a shared connection's version token changes between syncs, a new version was fetched. On every successful sync korTTY replaces its cached copy of the source with the version it just fetched; nothing is merged with local changes. For a Git source, korTTY resets its own clone to the remote branch, so anything changed inside that clone is discarded. Local overrides cover only credentials and SSH keys (see Local overrides).

Shared connection file format¶

Create a kortty-teamwork-connections.xml file (or connections.xml for backward compatibility) in the root of your Git repo or shared file:

<?xml version="1.0" encoding="UTF-8"?>
<connections>
  <connection id="prod-web-1">
    <name>Prod Web Server 1</name>
    <host>web1.example.com</host>
    <port>22</port>
    <username>deploy</username>
    <group>Production/Web</group>
    <authMethod>PUBLIC_KEY</authMethod>
    <sshKeyId>key-prod-deploy</sshKeyId>
    <credentialId>cred-prod-user</credentialId>
  </connection>
</connections>

If inline secrets are found in the shared file, KorTTY strips them automatically (they are not loaded).

Using teamwork connections¶

Once a source is synced:

1. Open Manage Connections… (or press Ctrl+M).
2. Choose Teamwork connections in the library on the left.
3. Double-click a teamwork connection to connect.
4. Read-only — Teamwork connections are read-only, and korTTY never writes changes back to a source: Edit is unavailable for them, a connection cannot be dragged into another folder, and right-clicking a folder or an empty area opens no menu, so there is no way to add, rename or delete folders or to relax their host-key verification. To change a shared connection, edit it in the repository or shared file; the change arrives with the next sync.

Teamwork connections also appear in the Connection Manager's general lists (All connections, Favorites, Recently used, Open now and the tags), marked with a small people symbol and just as read-only; see Library.

The command palette lists the teamwork connections as well, marked Shared (Teamwork), so you can also connect by typing @ and part of a name.

A shared connection can also carry the terminal settings the file gives it, such as its tab color and paste protection. Its own session isolation can only make its sessions stricter than your folder or Settings, as described under Choosing a level.

Deleting a teamwork connection only hides it on this computer, also in the command palette; the source is not changed. In the Teamwork group of the Connection Manager's toolbar, Restore deleted brings hidden connections back and Refresh reloads the list from the last sync without fetching the source again.

Local overrides¶

• The credential and SSH key references (credentialId, sshKeyId) of a shared connection are resolved from your local storage.
• For shared connections that name neither, choose Authentication for all team connections above the list while Teamwork connections is chosen in the library: a stored credential, an SSH key or Temporary SSH key. A stored credential that has a username uses it; for an SSH key or a temporary key, an optional Default username (SSH key) replaces the username from the source.
• If a credential or key is not found locally, you are prompted to provide it when connecting.
• Only authentication, including the username, can be overridden locally. Host, port, group and the other connection settings always come from the source.

Distinguish sources¶

Connections from every enabled source appear together under Teamwork connections, arranged by the groups defined in the shared files. The list does not show which source a connection came from, only the inspector names it for the selected connection; give each source its own group names if your team needs to tell them apart.

Git repository setup¶

To share connections via Git:

1. Create a repository (e.g., ssh-connections).
2. Add a kortty-teamwork-connections.xml file to the root with your connection definitions.
3. Commit and push.
4. Share the repository URL (HTTPS or SSH) with team members.
5. Team members add the URL in Teamwork → Teamwork Settings… → Add.

SSH vs. HTTPS¶

• HTTPS — Works without SSH key setup; may require a GitHub Personal Access Token or username/password (store the token securely).
• SSH — Requires git and a local SSH key in ~/.ssh/id_rsa (or configured in ssh-add).

Example repository layout¶

ssh-connections/
├── kortty-teamwork-connections.xml
├── .gitignore
└── README.md

Version token¶

korTTY uses the commit hash of the tracked branch as the version token automatically. To see which version your team is on, run:

git log -1 --pretty=%H

Shared file setup¶

To share connections via a file:

1. Export your connections to a file: Connections → Export… → select connections → save as .xml.
2. Place the file on a shared network path (e.g., //server/share/connections.xml).
3. Give team members read access to the file. korTTY only reads it, so only whoever maintains the file needs write access.
4. Team members add the file path in Teamwork → Teamwork Settings… → Add.

Example paths¶

Security considerations¶

Troubleshooting¶

Source is not syncing¶

1. Open Teamwork → Teamwork Settings….
2. Verify the source is Enabled.
3. Check that the Location is correct and accessible:
4. Git — Run git clone <url> manually to test.
5. Shared File — Verify the file exists and is readable from your machine.
6. Click OK to trigger a manual sync.
7. Check the application log (~/.kortty/kortty.log) for errors.

Connections appear but credentials are missing¶

1. Open Security → Credentials… and Security → SSH-Keys….
2. Verify that the credential IDs or SSH key IDs in the shared connections exist locally.
3. If missing, add them manually or ask your team administrator to provide the IDs.

File path is not recognized (Windows/UNC)¶

Use forward slashes or the file:// URI format:

• //server/share/connections.xml ✓
• \\server\share\connections.xml ✗ (backslashes may not parse correctly)
• file:////server/share/connections.xml ✓ (UNC notation)