Agend Sh

What agend-sh does

The agend-sh MCP server connects an MCP-compatible agent to a persistent, isolated Linux environment. The workspace can hold project files, run commands, host background processes, and provide an interactive terminal session. This makes it suitable for agents that need more than one-off local command execution.

Agents can run code, use Python REPLs or terminal applications, start services, and transfer files. A service listening on a workspace port can be exposed through a public HTTPS URL. The command-line client also lets a user open the environment directly with a shell or watch the agent’s interactive session.

How it works

Agend communicates with clients over MCP using stdio. After an environment is created and selected, MCP tools identify the environment and operate within it. shell_exec runs foreground commands or starts background tasks. For interactive programs, the agent can request an interactive process, send subsequent input with shell_send_raw, resize the terminal with shell_resize, and interrupt the session with shell_interrupt.

An interactive process remains available between tool calls. A response may report that input-wait activity was observed, but that signal is event-based rather than a persistent readiness check. Only one interactive session can be active in an environment at a time. A client disconnect does not automatically stop a completed interactive process, although sleep, crashes, or a cold reset can affect its lifetime.

The port_expose tool creates an HTTPS endpoint for a service, while port_list reports active exposures and port_unexpose removes one. Exposed services are reachable from the internet, so agents should treat the resulting URL accordingly.

Setup and configuration

Install the CLI on Linux or macOS with the provided shell installer or Homebrew, or use the PowerShell installer on Windows. Releases support amd64 and arm64 on Linux, macOS, and Windows. The installer verifies the release signature and archive checksum.

Authenticate with agend login, or create an account and sign in with agend signup --email. Create a workspace with agend env create --name <name>. Workspace size, quotas, and sleep policies are shown by agend profiles; a profile ID can be supplied during creation.

Run agend config to configure supported MCP clients, or preview changes with agend config --dry-run. Client names can also be passed explicitly. The agend-sh MCP server requires an Agend account and available environment quota; the CLI does not create a free local machine.

Tools and capabilities

The documented capabilities include:

• Finding environments with list_environments.
• Running commands and background tasks with shell_exec.
• Sending raw input to interactive processes with shell_send_raw.
• Resizing or interrupting interactive terminal sessions.
• Creating, listing, and removing HTTPS port exposures.
• Watching retained and new interactive-session output with agend watch.
• Opening a direct terminal connection with agend connect.

The agend-sh MCP server is intended for interactive work as well as ordinary command execution, including REPLs and terminal user interfaces.

Limitations and notes

Environment quota and account access are prerequisites. Interactive sessions share one slot between MCP and a direct agend connect shell. Watch mode mirrors agent-collected output and does not send input or poll the guest between tool calls. Port exposure makes the selected service internet-accessible, and custom Cloudflare-managed domains require the documented Cloudflare permissions and token configuration.