Source: https://docs.aivax.net/docs/tools/shell.html

# Shell

AIVAX offers a virtual shell environment that can be used by agent assistants to execute terminal commands during inference. This feature is especially useful for tasks such as data manipulation, API calls, script execution, and workflows that are easier to express as command-line operations.

The shell environment allows moving selected model tools to the shell side, turning them into CLI commands. This is useful when you have many tools and do not want to expose all of them directly to the model, or when a tool is easier to use through command-line arguments and pipes.

When enabled in an AI Gateway, the model sees a `shell` tool with one argument: `command`. Commands run in a sandboxed shell with network modules, filesystem defaults, and a workspace mounted at `/home/workspace`. Each command is limited to 60 seconds and returns up to 4,096 characters of output to the model.

## Design for the limits

The 60-second timeout and 4,096-character output cap shape how shell tools should behave. Keep commands fast and their output narrow: filter server-side with `grep`, `awk`, or query flags before printing, and prefer tools that return CSV or line-delimited rows the model can slice with pipes. When a result legitimately exceeds the cap, split the work — one command to list or count, follow-ups to fetch slices — or write the full output to a workspace file and read the relevant part back through the Shell file API below.

Long-running operations do not belong in an inference command. Move exports, bulk transforms, and polling loops to [Batch](https://docs.aivax.net/docs/features/batch.md) or an external job, and let the shell handle the interactive slices.

## Adapting tools for shell

In the virtual shell interface, standard command-line utilities and registered shell modules are available. This way, you can adapt your tools to return raw or long outputs, and the model can use the shell's text manipulation tools to extract the relevant information, for example:

```bash
get-users --filter active --format csv | grep "John Doe" | awk -F, '{print $1, $2}'
```

In the line above, `get-users` is a custom tool that returns a list of users in CSV format. The `grep` command filters the results to find "John Doe", and `awk` extracts and formats the desired columns. This tool may have been defined by [MCP](https://docs.aivax.net/docs/tools/mcp.md), [built-in tools](https://docs.aivax.net/docs/tools/builtin-tools.md) or be a [protocol tool](https://docs.aivax.net/docs/tools/protocol-functions.md).

Tools moved into the shell are no longer exposed as direct model functions, except reserved tools such as `shell` and `read_skill`. Configure the shell tool list as either:

- `WhiteList`: only listed tools are exposed as shell commands.
- `BlackList`: listed tools remain direct model tools, and the other non-reserved tools are exposed as shell commands.

Use the runtime function name when listing tools, such as `web_search`, `open_url`, `request`, or a protocol/MCP function name. Each shell command generated from a tool supports `--help` and maps JSON Schema properties to command-line options.

Prefer the whitelist when the model needs a small, predictable command set — every new tool otherwise leaks into the shell automatically. Prefer the blacklist when most tools are shell-friendly and only a few must stay as direct functions for latency or reliability reasons.

## Data persistence

It is possible to define data persistence for the shell environment. When `allowDataPersistence` is enabled and the inference context has a user external ID, AIVAX mounts a persistent workspace scoped to the account and user. This allows the agent to keep files across conversations and sessions for that identified user.

If persistence is disabled, or the inference context has no user external ID, the shell uses an in-memory filesystem and the workspace is discarded after the inference iteration.

Enable persistence only for data the user expects to survive — working documents, generated reports, configuration they manage. Keep secrets, credentials, and other users' data out of the persistent workspace: anything written there endures beyond the session that created it.

## Shell file API

AIVAX also exposes Shell I/O endpoints under `/api/v1/shell/io` for authenticated accounts. These endpoints use the required `X-Shell-User-Id` header to scope the filesystem sandbox and support listing directories, downloading files, inspecting file metadata, creating temporary public file addresses, uploading files, creating directories, and deleting files or directories. Uploads are documented with a 100 MB maximum request body.

Reference:

[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=List%20Directory)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Download%20File)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20File%20Details)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Get%20File%20Public%20Address)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Upload%20File)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Create%20Directory)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Delete%20File)
[API endpoint reference](https://inference.aivax.net/apidocs?embed=iframe&embed-endpoint=Delete%20Directory)