Project

cotty

A terminal shared by a person and an AI coding agent. You and the agent work in one real terminal session at the same time. You see everything it types, you can type at any moment, and you can take the keyboard back.

Testing. The current build is 0.1.0~git20261104225151.6ef77470a88d, in the opt-in testing channels on obpkg.org.

cotty is early and not yet reviewed by anyone outside the project, so do not rely on it to protect anything that matters yet. Interfaces, file locations and the protocol may change without notice before the first release. Linux only.

Status and install.

A cotty session named demo. An agent ran uname, ls and echo in the shell. The status line shows the agent's last command, one agent connected and the assurance level weak.
Your view of a shared session after an agent ran three commands in it. The status line at the bottom is drawn by cotty.

What it does

One terminal, two at the keyboard.

The agent reads the screen and types through MCP, so any agent CLI that speaks MCP works. Setup notes exist for Claude Code, Codex CLI, Gemini CLI, Cursor CLI and opencode.

  • You see and steer every step

    The agent types into the same shell you are looking at. You can type at any moment, take the keyboard, and, with the confirm policy, approve or reject each command line the agent wants to run.

    docs/broker.md

  • Password prompts stay with you

    cotty detects secret prompts from the terminal's own settings, as with sudo, su, passwd, ssh and read -s. While one is active, a lock shows in your status line and the agent's input is refused. What you type at a password prompt never reaches the agent.

    docs/security.md

  • Secrets masked in what the agent reads

    Values you put on a masking list are hidden in everything the agent reads. cotty secrets add NAME adds a value by reference, and the value is never printed. Private mode, which only you can turn on or off, freezes the agent's view, and rows written meanwhile stay hidden from it.

    docs/PLAN.md

  • The agent runs confined

    cotty agent starts the agent CLI in its own namespaces with Landlock, seccomp and its own cgroup, without root. Your keys, sockets, other terminals and other processes are out of its view, so it cannot go around cotty to read what cotty hides.

    docs/confinement.md

  • An optional guard in the kernel

    cotty-guard needs root and the BPF LSM. It enforces the agent rules in the kernel and protects the session's terminal device from every other process.

    docs/guard.md

  • An honest assurance level

    Each agent connection gets a level, and the status line shows the weakest one: strong with the guard and cotty agent, confined with cotty agent alone, weak without confinement evidence. cotty doctor tells you what your system offers.

    How it works

Status

Testing, and early.

Where it stands

  • Test build 0.1.0~git20261104225151.6ef77470a88d, from commit 6ef7747 of the public repository.
  • Packages cotty and the optional cotty-guard, signed with the OpenBasalt release key, in the opt-in testing channels on obpkg.org: basalt-testing for Fedora 44 and Basalt OS (x86_64), and the APT testing suite for Debian 13, Ubuntu 24.04 and 26.04 (amd64 and arm64).
  • Four internal review rounds found weaknesses that were fixed. What is still open is listed under Known limits in docs/security.md.
  • Sessions, confinement and the guard are tested in throwaway lab virtual machines.

What cotty is not

  • Not a sandbox for the commands the agent types into the shared session. Those run with your rights, in your shell: that is the purpose of the tool.
  • Not a guard for secrets typed with echo on, unless you turned on private mode first or the value is on the masking list.
  • Not a defence against a malicious kernel or root.
  • Not a network filter. A confined agent can reach any TCP or UDP service you can, including services on localhost.
  • Masking is not a boundary. It hides values the list knows from what the agent reads; it does not stop an agent from obtaining them another way.

The lock does not light for a password prompt inside a program that relays the terminal in raw mode, such as sudo -i, ssh, tmux or screen: turn private mode on before typing a secret there.

Install

Test packages for Basalt OS, Fedora, Debian and Ubuntu.

cotty needs Linux with user namespaces and Landlock; kernel 6.12 or later is recommended. Packages are signed with the OpenBasalt release key. Before you trust the key, check that its fingerprint is 3601 7348 42BD 4E48 2D19 DE4A E4EE D5EC A395 B302, and stop if it differs.

Basalt OS

The basalt-testing repository is configured and turned off. Install from it without turning it on:

sudo dnf --enablerepo=basalt-testing install cotty

Fedora 44

Download the package and the key, check both, then install the file:

curl -fsSLO 'https://obpkg.org/basalt-testing/44/x86_64/cotty-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm'
curl -fsSLo openbasalt-release-key.asc https://obpkg.org/keys/openbasalt-release-key.asc
gpg --show-keys --with-fingerprint openbasalt-release-key.asc
sudo rpm --import openbasalt-release-key.asc
rpm -K cotty-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm
sudo dnf install ./cotty-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm

rpm -K must report digests signatures OK. To follow new test builds instead, add the basalt-testing repository as described in the README and on obpkg.org.

Debian 13 and Ubuntu (APT)

Debian 13, Ubuntu 24.04 and 26.04, amd64 and arm64, from the testing suite:

curl -fsSLo /tmp/openbasalt-release-key.asc https://obpkg.org/keys/openbasalt-release-key.asc
gpg --show-keys --with-fingerprint /tmp/openbasalt-release-key.asc
sudo install -d -m 0755 /etc/apt/keyrings
sudo gpg --dearmor -o /etc/apt/keyrings/openbasalt-testing.gpg /tmp/openbasalt-release-key.asc
printf 'Types: deb\nURIs: https://obpkg.org/apt\nSuites: testing\nComponents: main\nSigned-By: /etc/apt/keyrings/openbasalt-testing.gpg\n' |
  sudo tee /etc/apt/sources.list.d/openbasalt-testing.sources
sudo apt update
sudo apt install cotty

On Ubuntu 24.04 and later the package brings the AppArmor profile that lets cotty create user namespaces.

The guard (optional)

The guard needs root, the BPF LSM active (bpf listed in /sys/kernel/security/lsm) and BTF. cotty doctor says whether your kernel can run it. On Fedora 44:

curl -fsSLO 'https://obpkg.org/basalt-testing/44/x86_64/cotty-guard-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm'
rpm -K cotty-guard-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm
sudo dnf install ./cotty-guard-0.1.0~git20261104225151.6ef77470a88d-1.fc44.x86_64.rpm
sudo systemctl enable --now cotty-guard
cotty guard status

On Basalt OS, Debian and Ubuntu, install the cotty-guard package the same way as cotty. Stopping the guard keeps every rule in force, and while it is installed but stopped, cotty attach and cotty new refuse to run. To remove it: sudo systemctl disable --now cotty-guard, then sudo cotty-guard uninstall. docs/guard.md explains how to enable the BPF LSM where it is off.

First session

cotty doctor                        # what this system offers, and what is missing
cotty new --ai --name work          # a shared session, you are attached
cotty agent -- claude               # in another terminal: the agent, confined

Inside the agent, the cotty MCP tools (term_read, term_run, term_type, term_wait and others) act on the shared session. Setup for each agent CLI is in docs/agents.

Press Ctrl-] then one of these keys in the session:

  • k take the keyboard (agents are refused) or give it back
  • p private mode on or off
  • y or n accept or reject the agent line waiting for confirmation
  • a or x allow or deny a pending person attach
  • s share the session with agents, or hide it
  • c show the reattach code
  • d detach, which prints the reattach code
  • ? help

cotty attach work reattaches and asks for the reattach code. Do not type a code into a session: the real code prompt is the attach client's, in a terminal of its own.

Source and documentation

One repository.

The source, the threat model and the design notes live together. Start with the README, then the threat model in docs/PLAN.md, section 2.

License

Apache License 2.0.

cotty is licensed under the Apache License, Version 2.0. The BPF programs are dual licensed Apache-2.0 OR GPL-2.0-only, because the kernel requires a GPL compatible license for BPF LSM programs.

Please report security problems privately, through GitHub's private vulnerability reporting on the repository. See its SECURITY.md.