agend-sh

A real computer for your AI agent.

Persistent Linux workspaces. Interactive terminals. Shareable previews.

Bring your favorite MCP agent. Let it get to work.

Quick start · Interactive terminals · Connect your agent · MCP tools · agend.sh

agend gives your agent a persistent, isolated Linux environment it can drive through MCP. It can run code, edit files, use Python REPLs and Vim, start services, and expose a preview URL. You can open a shell yourself or watch the agent's interactive terminal as it works.

Quick start

1. Install

Linux / macOS

curl -fsSL https://agend.sh/i | sh

Windows · PowerShell

irm https://agend.sh/i.ps1 | iex

Homebrew · Linux / macOS

brew install agend-sh/tap/agend

The script installers verify the release signature and archive SHA-256 checksum. The Unix installer writes to /usr/local/bin and may ask for sudo. The Windows installer writes to %LOCALAPPDATA%\agend\bin and adds it to your user PATH. Releases support amd64 and arm64 on all three platforms.

agend version

2. Sign in

agend login

Complete authentication in the browser. Creating an account with email and a password instead:

agend signup --email you@example.com

signup prompts for a password and signs you in on success. You do not need to run login again.

3. Create your workspace

agend env create --name my-workspace

agend ping agend exec 'python3 --version'

Creation selects the new environment for CLI commands. Its size follows your account's default profile. Use agend profiles to see available sizes, quotas, and sleep policies; pass a returned profile ID with agend env create --profile to choose another size.

4. Connect your agent

agend config claude-code

Or configure a different client:

agend config codex cursor gemini

Restart or reload your client's MCP integration, then try this prompt:

Use agend's list_environments to find my-workspace. Start an interactive Python REPL there, calculate 6 × 7, then exit the REPL.

Your agent discovers the environment and drives it with MCP tools. An Agend account and available environment quota are required; the CLI alone does not provision a free local machine.

agend-sh is listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.agend-sh%2Fagend-sh/versions/latest) as io.github.agend-sh/agend-sh. For Docker-based installation, see the container package and connection guide. Also available on Smithery. For clients that support MCPB extensions, see the bundle guide.

Interactive terminals

The terminal can report that it entered an input wait. That gives the agent process feedback while it drives a REPL or terminal app.

For example, call `shell_exec` with:

{

"environment": "my-workspace", "command": "python3 -q", "interactive": true }

A response can look like this:

status: awaiting_input

>>

prompt_type: interactive input_wait: true

Continue through `shell_send_raw`:

{

"environment": "my-workspace", "input": "print('hello from agend')\n" }

status: awaiting_input

print('hello from agend') hello from agend

>>

input_wait: true

Then send exit()\n through shell_send_raw to close Python.

Reading the response

The input-wait signal is an event, not a persistent state query or a guarantee that an application or service is ready. It depends on support in the environment's guest stack.

For REPLs and TUIs, set interactive: true and use shell_send_raw for subsequent input. Include \n when you want Enter. Use shell_resize when the viewport changes. Quit through the app's own command, or use shell_interrupt to close the session. One interactive session can be active per environment; finish it before starting another shell_exec.

An interactive process stays alive between tool calls and is not killed when its response collection times out. After a completed tool response, disconnecting the MCP client does not itself stop the process: reconnect to the same environment to continue. Environment sleep, a crash, or a cold reset can affect its lifetime.

Watch your agent work

agend watch

Watch mirrors the selected environment's interactive session, replays retained output, and follows new updates. It sends no input to the remote process. Press q or Ctrl+C to stop watching; the agent's session continues.

For a screen recording:

agend watch --typing-delay 40ms

Match your terminal's size to the remote session for an accurate display. Watch follows output collected by the agent's tool calls; it does not poll the guest for output between those calls. It shows interactive sessions, not ordinary command output or background-task logs.

Want to work in the environment yourself?

agend connect

This opens a live terminal with keyboard input and terminal resizing. Run exit to close the shell. It requires a terminal on stdin and uses the same single interactive-session slot as MCP, so close the agent's interactive app first.

Share a browser preview

Have your agent start a service using `shell_exec`:

{

"environment": "my-workspace", "command": "python3 -m http.server 8080 --bind 0.0.0.0 --directory /home/agend-user/readme-demo", "run_in_background": true }

Create /home/agend-user/readme-demo and put your demo files there first. Bind the service to 0.0.0.0 so the tunnel can reach it.

Then call `port_expose`:

{

"environment": "my-workspace", "port": 8080 }

The response contains a public HTTPS URL. Allow time for the tunnel and DNS to become reachable. port_list shows active exposures; port_unexpose removes one. Exposing a port makes that service reachable from the internet.

For your own Cloudflare-managed domain, register its zone with agend domain add example.com, then pass domain: "app.example.com" to port_expose. Registration prompts for a Cloudflare API token with Zone:DNS:Edit, Zone:Zone:Read, and Account:Cloudflare Tunnel:Edit permissions; scripts can supply it through AGEND_CF_TOKEN. agend domain list returns the domain IDs used by agend domain remove .

Connect your agent

agend config detects supported clients installed on your machine. Preview its choices before writing:

agend config --dry-run

agend config

You can also select clients explicitly:

Configuration registers agend mcp as a local stdio server. The client must be able to find the installed binary; on Windows, the config writer uses its absolute path. Client-specific config paths and formats are handled by agend config.

Configure another MCP client manually

For clients that use the mcpServers JSON format:

{

"mcpServers": { "agend": { "command": "agend", "args": ["mcp"] } } }

Use the absolute binary path if the client does not inherit your shell's PATH. This is a generic example; some clients use a different schema. agend mcp reads JSON-RPC from stdin and writes protocol responses to stdout; logs go to stderr. Tool results are MCP text content, including fields such as status and input_wait.

MCP tools

The CLI exposes 23 tools. Call list_environments to discover IDs and names. Environment-specific tools require an environment argument and accept either an ID or a name. env_create, list_environments, profiles_list, and reload_config do not need one.

| | reload_config | Reload credentials after changes in another ter