Environments overview

The bundled Environments plugin confines commands for accounts without operator authority and gives every managed Project its own persistent machine.

Paired computers and publishing

On a Project that runs on a paired computer, Chetty is told after each of your messages which computer runs its tools, that computer's operating system and the shell its Bash tool uses: /bin/sh on macOS and Linux, PowerShell 7 or Windows PowerShell 5.1 on Windows.

The computer's name appears as you named it, and that line is not displayed in the conversation.

Sites can publish an application from a paired computer Project through the same publication control as a managed Project.

• The publishing account must stay a member of that computer.
• An offline computer makes the publication unavailable until it reconnects. HTTP and WebSocket connections use the same transport.
• If publishing reports LOCAL_CLIENT_OUTDATED, update the CLI.
• Removing the publishing member closes that member's live publications.

Read Publish an application.

Where to manage environments

The plugin adds no slash command.

What Chetty can manage for you

Chetty manages a managed Project's environment through its Project tool, with the same rules as the Environments panel.

• Read state, limits and snapshots with get.
• Change the lifecycle with start, stop, restart or recreate.
• Change resources and networking with resources or network.
• Take, restore or delete a snapshot with snapshot, restore or delete_snapshot.
• Read the lifecycle log with logs, the last 100 lines unless more are requested.
• Manage shared worktrees with worktrees, worktree_create or worktree_remove.
• Follow a pending operation with operation.

Deleting a Project, restoring or deleting a snapshot, and a resource change that shrinks the disk ask for confirmation. A requested operation may still be pending when the tool returns. The Desktop tool is the only tool this plugin provides.

Plan mode works inside managed Projects:

• Chetty can search files and run non-destructive commands, and writes only the conversation's own plan file.
• Read-only sub-agents can run the same investigation commands but cannot edit a plan.
• Environment lifecycle changes and desktop actions are unavailable while planning.

A managed plan stays in its Project's environment and is removed when the conversation is cleared or deleted; cleanup waits for a stopped environment to become available. The same conversation keeps its plan when its execution target changes.

Turn the plugin on and set defaults

The plugin is bundled and enabled by default. It is not user-grantable, and managing an environment also needs access to the managed Project.

Saving plugin settings, or enabling or disabling a plugin, saves the change and requests a Chetty restart; the screen reports that the change is saved and Chetty is restarting.

Defaults for newly provisioned environments cover confinement, processors, memory, swap, the process and thread limit, disk speed, network speed and the network mode. They apply when an environment is first provisioned, and an existing environment keeps its own limits. Read Set environment limits and networking for the table and for changing one Project.

Accounts, HOME and confined commands

Each linked account has a private HOME for Git, npm and tool configuration, separate from Projects. Commands from accounts without operator authority run in a restricted bubblewrap environment by default: they reach their available Project directories and that HOME, and they keep network access. If the live containment check fails, the command is refused.

An administrator can turn Confine non-operator commands off, which allows those accounts to run commands directly on the host. Read Set up an account development environment for the HOME, the check and the Git author.

Project environments

Each managed Project has one persistent environment that keeps its files and installed packages when it is stopped. It reports one of these states: Not provisioned, Starting, Running, Stopped, Failed, Deleting or Deleted.

The host must be prepared before a new environment can be created, and the Host panel reports what is missing. Start, stop, snapshot and restore are durable requests: each returns an operation that may still be running, so check its status before you assume it finished.

Shared Project desktop

New Project environments use the current image, project-base@19: GNOME on Wayland with Ubuntu 26.04 and the GitHub CLI (gh). Each Project container has exactly one shared desktop. It starts when Chetty uses the Desktop tool and keeps running until a Project member stops it or the environment stops, including across daemon restarts.

Every current Project member can watch the shared screen, so application logins and documents are shared. Read Use the shared Project desktop.

Access and limits

Project access is checked when an environment operation runs. Only administrators can manage host readiness, account HOME settings and a Project's resource limits.

• Alerts in the bell warn when disk usage reaches 80% of a Project's ceiling, report when usage passes it, and clear once usage falls below 75%.
• A start refused because the disk is over its ceiling raises its own alert. If automatic recovery fails, an alert gives the number of attempts and asks for manual action, and it stays until you acknowledge it.
• Inbound forwarding supports TCP or UDP, with host and environment ports from 1 to 65,535. Only instance administrators may change the network policy, including ports below 1,024 such as UDP 500 for IKEv2. Every environment start refuses ports already used by a host listener for that protocol; if availability cannot be checked, it does not start. Free the port or choose another one. Saving a stopped environment does not reserve the port against host services.
• The Project tool's environment actions do not manage Sites, and a host Project has no environment.

Snapshots are crash-consistent, not database-consistent, so export application databases separately when consistency matters.

Related guides

Continue with Prepare a host for managed environments, Start, stop and snapshot an environment, Set environment limits and networking, Use the shared Project desktop or Projects overview. For plugin administration, see Plugins.