Terminal overview

The bundled terminal plugin lets Chetty run shell commands and manage background processes, and it adds a Processes section to the chat rail.

The four tools

Commands on a paired computer

On a Your computer target, commands run on that computer rather than on the server. Chetty reads the computer's output, error output, input and working directory directly from it, without launching a shell on the server.

• The working directory of a successful foreground command is remembered separately for each computer.
• A running process stays tied to the connection it started on, so a new connection cannot take over an old process.
• A lost connection is reported as LOCAL_EXECUTION_LOST. A command sent with no final result has an unknown outcome, so check the computer's state before you repeat it.

Read Connect your computer to pair one.

Grant the plugin to an account

The plugin is enabled on fresh installations, and Settings → Plugins shows it. It is grantable, so to let a non-administrator use it:

1. Open Users and select the account.
2. Under Granted plugins, choose Manage.
3. Select terminal and select Save changes.

Administrators need the same grant as any other account; it is not automatic. The grant makes the plugin available, but account tool permissions can still restrict individual tools.

The plugin itself does not ask for confirmation before it runs a command, though an account permission rule can set a command to ask first. A command you approve that way is never moved to the background on its own. See Users and access overview.

Where commands run

Chetty resolves command access through the Sandbox plugin for each launch. In a Project conversation, commands follow that Project's access policy and start in the Project root; inside a managed Project environment they run in that environment, and a conversation pointed at another directory such as a Git worktree runs there.

If Sandbox is unavailable, managed-Project execution is refused. Only the instance owner can use explicit direct-host mode, and a blocking restart of Chetty's own daemon or a request to bypass Sandbox is refused. Read Run a shell command for the working directory, timeouts and cwd.

Foreground commands

A foreground Bash call waits up to its timeout, measured in milliseconds: 120,000 by default and at least 1, with a usual maximum of 600,000. When the deadline is reached in a person's own interactive conversation, the command normally keeps running in the background and you get its process ID.

Read Run a shell command for the cases that are stopped instead, for Ctrl+B, and for the deployment settings behind the timeout.

Background processes

Ask Chetty to run a command with run_in_background: true. It returns a process ID and notifies you when the process finishes; use ListProcesses, ProcessOutput or KillProcess to manage it, and backgroundMode: "service" for a long-running server or watcher.

The Processes rail section shows running background processes and lets you inspect output or stop one. A daemon restart ends them. Read Manage background processes for limits, output rules and plan-mode restrictions.

Output and settings

Inline output is limited to 60,000 bytes by default. A long foreground result keeps its beginning and end, reports how much was omitted and saves the captured output separately, which you can inspect with Read. The saved capture is limited to 8 MB, and a partial capture reports how much was dropped.

Configuration is instance-wide, with no per-account settings, in the plugin detail view under Settings → Plugins. Enabling the plugin requires consent to publish events, which keeps interactive terminal status synchronized across your tabs. Saving these settings restarts Chetty, and changes to the Sandbox configuration affect the next command launch.

Interactive terminals

Select the terminal icon on a Project card to open an interactive shell that you type into yourself. It follows the same Sandbox decision as a command, and it keeps running in the dock while you work elsewhere.

Deleting a Project stops its background processes and closes its interactive terminals, even if the conversation has since selected another Project. Read Open an interactive Project terminal for the steps and Interactive terminal access and limits for who can open one, where it runs and what ends it.

Related guides

Run a shell command, Manage background processes, Open an interactive Project terminal, Run a command in the background, Environments overview.