Shell

Tools for running commands, keeping a shell session open, running Python and Node code, and using Docker. Commands run in your operating system's sandbox.

Execute commands

Tool	Parameters	Description
`run_command`	`command`, `cwd?`, `timeout?`	Run a shell command in a one-shot process and return its output. `cwd` is relative to the project folder. The timeout is in seconds (30 by default).
`ssh_exec`	`host`, `command`, `user?`, `port?`, `key_path?`, `timeout?`	Run a command on a remote host over SSH. Needs `ssh` installed and the host reachable, with a key file or a key loaded in `ssh-agent`.

Where commands run

Commands the agent runs go through the sandbox your operating system already has: bubblewrap (bwrap) on Linux and sandbox-exec on macOS. There is no virtual machine, so commands run at full speed with the tools you have installed. This covers run_command, shell sessions, run_python and run_node, and the tools that run tests, builds, linters and package managers.

Commands can change only the project folder, temporary folders and package caches.
Sign-ins, keys, browser profiles and Asyncat's own data, such as ~/.ssh and ~/.aws, look empty to them, unless you allow one back.
API keys you saved in Asyncat are never passed to them.
Their network can be open, limited to package registries, or off.

Windows has no command sandbox yet. Set it all up in Settings → Privacy & safety → Commands the agent runs. See The command sandbox.

When commands ask

Running a command is a risky step, so it asks first, with one exception: a command runs straight away when a parser proves it read-only. Every program in it must be on an allow-list, and its options are checked against what that program can do.

Command	Asks first?
`ls -la`, `git status`, `git log --oneline \| head`	No: proven read-only
`find . -delete`, `git branch -D old`, `rm -rf build`	Yes
Anything with redirects, `$(…)` or a second command after `;`	Yes: the parser can't prove it

In Plan mode, only proven read-only commands run. Everything else is refused until you switch to Action.
While the sandbox is on but can't start, every command asks, every time, even in Yolo mode and in Cats. See When the sandbox can't start.

Shell sessions

A shell session keeps its state between commands: the working folder, exported variables and running processes carry over.

Tool	Parameters	Description
`shell_session_start`	`name?`, `cwd?`	Start a named session (`default` if no name is given), in a folder inside the project.
`shell_session_run`	`command`, `name?`, `timeout?`	Run a command in a session. The timeout is in seconds (120 by default).
`shell_session_close`	`name?`	Close a session and free what it used.

Sessions suit work in several steps: start a dev server or a REPL, use it over a few calls, then close it.

Language runtimes

Tool	Parameters	Description
`run_python`	`code`, `timeout?`	Write the code to a temporary file and run it with `python3`. Useful for data processing, calculations and scripts.
`run_node`	`code`, `timeout?`	Write the code to a temporary file and run it with `node`.

Both run in the command sandbox, with a 30-second timeout by default.

Docker

These tools need Docker on your computer.

Tool	Parameters	Description
`docker_run`	`image`, `command`, `cwd?`, `volumes?`, `env_vars?`, `timeout?`, `remove?`	Run a command in a container. Host folders in `volumes` must be inside the project. The container is removed afterwards by default.
`docker_build`	`tag`, `path?`, `no_cache?`, `timeout?`	Build an image from a Dockerfile and tag it.
`docker_ps`	`all?`, `format?`	List running containers, or all of them, as a table or JSON.
`docker_stop`	`container`, `timeout?`	Stop a running container by name or ID.
`sandbox_exec`	`command`, `image?`, `timeout?`	Run untrusted code in a locked-down container: no network, read-only, with limited memory and CPU.