PiloTY
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@PiloTY run 'npm run build' and show me the output"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
PiloTY
PiloTY (PTY for your AI Copilot) is an MCP server that gives an agent a persistent, interactive terminal.
If you have used Claude Code / Codex to run shell commands, you have probably hit the same wall: tool calls tend to be stateless. Each call starts "fresh", so environment variables disappear, interactive programs cannot be driven reliably, and long-running processes get cut off or orphaned while the agent is thinking.
PiloTY exists to make the agent's terminal behave more like a human's: start something in a real terminal, come back later, and keep going.
Warning: PiloTY exposes unrestricted terminal access. Treat it like giving the agent your keyboard.
What it enables
Long-running commands: builds, installs, migrations, test suites. Start once, check output later.
Log monitoring:
tail -f,journalctl -f,kubectl logs -f, CI logs, service restarts."Vibe debugging": keep a REPL/debugger open while the agent reads code and tries ideas (
python,ipython,pdb).Privileged operations: handle interactive password prompts (
sudo, SSH passwords, key passphrases).SSH-based devops: keep a remote login session alive across tool calls; run remote commands in the same shell.
Terminal UIs:
less,man,top,vimcan work, but cursor-heavy programs often require screen snapshots instead of plain text output.
Related MCP server: can-see
Quickstart
PiloTY is meant to be launched by an MCP client over stdio.
Add it to Codex CLI as an MCP server:
codex mcp add piloty -- uvx --from git+https://github.com/yiwenlu66/PiloTY.git pilotyIf you prefer SSH-based Git fetch:
codex mcp add piloty -- uvx --from git+ssh://git@github.com/yiwenlu66/PiloTY.git pilotyIf you already have a local clone:
codex mcp add piloty -- uv --directory /path/to/PiloTY run pilotyRun the server command directly (without adding it to an MCP client):
uvx --from git+https://github.com/yiwenlu66/PiloTY.git pilotyMental model
One session is one real interactive terminal that stays alive across tool calls.
State persists: cwd, environment variables, foreground process, remote SSH connection, REPL/debugger state.
PiloTY tracks both the raw output stream and a rendered screen/scrollback view.
PiloTY keeps two representations:
output: incremental text stream (optionally ANSI-stripped)Rendered screen/scrollback: what a human would see in a terminal
Public MCP results separate call outcome from terminal interpretation:
outcome:success,deadline_exceeded,eof,error,invalid_session, orterminatedterminal_state: best-effort rendered-state classification after the call (running,ready,password,confirm,repl,editor,pager,unknown)
Sessions are addressed by a session_id string. Reusing the same id is what keeps state.
Integration notes (for MCP integrators)
MCP does not expose a standard "client cwd" field, so the first step is always to create a session with an explicit working directory, then reuse the same session_id for subsequent calls.
Typical agent workflow:
Create a session (explicit cwd) and reuse the same
session_id.Use
send_lineto submit a newline-terminated command,send_textfor raw bytes, andsend_control/send_signalfor interrupts.Use
wait_for_outputfor temporal PTY output waiting,wait_for_regexfor content-based waits, andwait_for_shell_promptaftersshor similar login flows.Use
snapshot_screen/snapshot_scrollbackwhen layout matters. Snapshot tools are passive and do not ingest fresh PTY bytes.If prompt detection is wrong, configure a custom shell-prompt regex.
Use
send_passwordfor secret entry; terminate the session when done.
For exact tool names, arguments, and return fields, use your MCP client's tool schema or read piloty/mcp_server.py.
Limitations
deadline_sis a wall-clock budget. On send/wait tools, it is not "process completion time".Drain-based tools (
send_line,send_text,send_control,send_password,send_signal,wait_for_output) stop after the server quiescence policy (PILOTY_QUIESCENCE_MS, default1000) or whendeadline_sexpires.wait_for_outputcan return partial output withoutcome=deadline_exceededif output started but the PTY never went quiet before the deadline.wait_for_regexfirst checks already-rendered scrollback, then waits on new PTY bytes.wait_for_shell_promptconsumes PTY output while it waits and returns the consumed bytes inoutput.Terminal-state detection is best-effort and can be wrong (especially for custom prompts and cursor-heavy TUIs).
Plain text output can be misleading for full-screen programs; use screen snapshots when layout matters.
send_password()suppresses transcript logging and terminal echo for that send. It does not prevent other prompts/programs from echoing secrets later.Quiescence-based output collection can be confused by programs that print periodic noise. Tune with
PILOTY_QUIESCENCE_MS(default1000).
Logs
Each server instance writes session logs under ~/.piloty/:
~/.piloty/servers/<server-instance-id>/sessions/<session-id>/transcript.log: raw PTY bytes (combined stdout/stderr)~/.piloty/servers/<server-instance-id>/sessions/<session-id>/commands.log: inputs sent (best-effort)~/.piloty/servers/<server-instance-id>/sessions/<session-id>/interaction.log: inputs plus captured output (best-effort)~/.piloty/servers/<server-instance-id>/sessions/<session-id>/session.json: metadata snapshot~/.piloty/active/<server-instance-id>/<session-id>: symlink to the current session directory (when symlinks are supported)
Server logs default to /tmp/piloty.log.
tools/session_viewer.py can inspect sessions:
python tools/session_viewer.py list
python tools/session_viewer.py info <server-instance-id>/<session-id>
python tools/session_viewer.py tail -f <server-instance-id>/<session-id>Development
Repository layout:
piloty/
core.py # PTY + terminal renderer + session logs
mcp_server.py # MCP tools + state inference
tests/
tools/
pty_playground.py
session_viewer.pyRun tests:
python -m pytest -qLicense: Apache License 2.0, see LICENSE.
Available Tools
17 toolsclear_scrollbackB
Clear rendered scrollback history while preserving current screen.
Requires an existing session created via create_session(session_id, cwd).
Inputs: session_id (required).
configure_sessionA
Update session metadata and shell prompt detection.
description is free-form metadata for humans and does not affect execution.
shell_prompt_regex is used by heuristic readiness detection to decide
whether the terminal is idle at a shell prompt. It is matched against the
last non-empty line of the rendered screen.
This can be called before a session exists; values are stored by session_id
and applied when the session is created.
Inputs: session_id (required), description, shell_prompt_regex.
create_sessionA
Create a PTY session with an explicit working directory.
MCP does not provide a standard field for the client's current working
directory. The caller must provide cwd explicitly.
Args: session_id: Stable identifier for this PTY session. cwd: Working directory for the session's shell. description: Free-form description of what this session is doing (for humans).
Inputs: cwd (required), session_id (required), description.
get_metadataB
Get metadata for an existing PTY session.
Requires an existing session created via create_session(session_id, cwd).
Inputs: session_id (required).
list_sessionsD
Inputs: no named parameters.
send_controlA
Send a control character to the terminal.
Requires an existing session created via create_session(session_id, cwd).
Keys:
csends Ctrl+C, commonly used to interrupt.dsends Ctrl+D (EOF in many programs).zsends Ctrl+Z (job control suspend).lsends Ctrl+L (clear screen in many shells).[orescapesends ESC.
After sending the control character, this drains newly produced PTY bytes
until the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until
deadline_s expires.
deadline_s must be at most 300 seconds.
Inputs: key (required), session_id (required), deadline_s.
send_lineA
Send one newline-terminated line to a stateful PTY session.
Requires an existing session created via create_session(session_id, cwd).
After sending line + "\n", this drains newly produced PTY bytes until the
PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until
deadline_s expires.
deadline_s must be at most 300 seconds.
Common SSH pattern:
create_session(session_id, cwd)
send_line(session_id, "ssh host", deadline_s=2)
wait_for_shell_prompt(session_id, deadline_s=30)
Inputs: line (required), session_id (required), deadline_s.
send_passwordA
Send a password plus newline.
Requires an existing session created via create_session(session_id, cwd).
Security model:
Forces terminal echo off for this send operation (
echo=False).Disables transcript logging for this send operation (
log=False).Returns the PTY bytes consumed during this call with best-effort password redaction, prefixed by
[password sent].
After sending password + "\n", this drains newly produced PTY bytes until
the PTY is silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until
deadline_s expires.
deadline_s must be at most 300 seconds.
Inputs: password (required), session_id (required), deadline_s.
send_signalB
Send an OS signal to the foreground process in a session.
Requires an existing session created via create_session(session_id, cwd).
Inputs: signal (required), session_id (required), deadline_s.
send_textA
Send raw text to a stateful PTY session without adding a newline.
Requires an existing session created via create_session(session_id, cwd).
After sending text, this drains newly produced PTY bytes until the PTY is
silent for PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s
expires.
deadline_s must be at most 300 seconds.
Inputs: text (required), session_id (required), deadline_s.
snapshot_screenA
Get the current VT100-rendered terminal screen snapshot.
Requires an existing session created via create_session(session_id, cwd).
This is a passive snapshot. It does not ingest new PTY bytes.
Inputs: session_id (required).
snapshot_scrollbackA
Get rendered terminal scrollback.
Requires an existing session created via create_session(session_id, cwd).
This is a passive snapshot. It does not ingest new PTY bytes.
Inputs: session_id (required), lines.
terminateB
Terminate a PTY session. Future calls using the same session_id are rejected.
Inputs: session_id (required).
transcriptC
Get the transcript file path for this session.
Inputs: session_id (required).
wait_for_outputA
Wait for newly arriving PTY output without sending input.
Requires an existing session created via create_session(session_id, cwd).
This waits for new PTY bytes to arrive. After the first new output is
observed, it continues draining until the PTY is silent for
PILOTY_QUIESCENCE_MS (default 1000ms) or until deadline_s expires.
deadline_s must be at most 300 seconds. If the deadline expires after some
output has already been captured, partial output is returned with
outcome="deadline_exceeded".
If you need to wait specifically for a shell prompt, use
wait_for_shell_prompt().
Inputs: session_id (required), deadline_s.
wait_for_regexA
Wait for a regex match in rendered text and/or newly arriving PTY bytes.
Requires an existing session created via create_session(session_id, cwd).
This first checks already rendered scrollback, then waits on new PTY output.
deadline_s must be at most 300 seconds.
Inputs: pattern (required), session_id (required), deadline_s.
wait_for_shell_promptA
Wait until a shell prompt is detected.
Requires an existing session created via create_session(session_id, cwd).
This repeatedly ingests new PTY output and re-runs prompt detection until a
shell prompt is visible or until deadline_s expires. Any output consumed
during that wait is returned in output.
If the remote shell uses a customized prompt that the default heuristics
misclassify, set shell_prompt_regex via configure_session(...).
deadline_s must be at most 300 seconds.
Inputs: session_id (required), deadline_s.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool has a clearly distinct purpose: session lifecycle, input methods (line, text, control, password, signal), output retrieval (snapshots, transcript), and waiting mechanisms (output, regex, prompt). No overlap or ambiguity.
All tools use a consistent verb_noun snake_case pattern (e.g., create_session, send_line, wait_for_shell_prompt). No mixing of conventions.
17 tools are well-scoped for a PTY management server, covering all necessary interactions without bloat. Each tool serves a distinct, necessary function.
The tool set covers session lifecycle, multiple input modes, output retrieval, and waiting for various states. It includes password handling and signal sending, appearing complete for typical terminal interaction use cases.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
Orbit is an MCP server that gives your AI agents a 4000+ tools, a shared memory brain and a live dashboard OS. Every agent reads active decisions, logs outputs to a searchable vault, and reports status in real time. 2-minute setup via MCP; works across Claude, ChatGPT, Codex, Cursor, Gemini, and Manus. Finally Agents work, agents that grow your business and bring you customers. https://orbitagents.xyz
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceDockaShell is an MCP server that provides AI agents with isolated Docker containers for persistent shell access, file operations, and full audit trails, enabling autonomous development and self-evolving workflows.11 npm30Apache 2.0
- AlicenseNot gradedqualityCmaintenanceMCP server that lets AI agents see and interact with terminal/CLI applications through virtual terminals and PNG screenshots.77 npmMIT
- AlicenseAqualityCmaintenanceMCP server giving AI agents full SSH access with persistent sessions, structured command output, SFTP file transfer, and port forwarding.1862 PyPI12MIT
- AlicenseAqualityDmaintenanceMCP server that gives AI agents real interactive terminal sessions for running REPLs, SSH, database clients, and any interactive CLI with clean text output and smart completion detection.791 npm20MIT