> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/stackai-tools/browser-and-computer/terminal-stackai-computer.md).

# Terminal (StackAI Computer)

Run commands in a separate StackAI computing environment. Use Terminal to process files, run scripts, or prepare an artifact for another step.

## Before you start

StackAI Computer must be available in your environment. Commands run in its sandbox, not on your own computer.

## Run a command

1. Select **Terminal** from **StackAI Computer**. Enter **Command** and a short **Description** of its purpose.
2. Leave **Terminal Sandbox ID** empty for a new environment, or pass the ID returned by an earlier Terminal call to reuse its files and installed packages.
3. Run the command and check **Exit Code** and **Success**. Read **Standard Output** for results and **Standard Error** for diagnostic messages.
4. Use **New Files Created** to pass generated files onward. Keep **Enable New Files** enabled when downstream steps need those files.

**Result:** Exit code `0` indicates successful command execution. Returned file entries include download links for generated files.

## Behavior and troubleshooting

A command can change files before it fails. Check existing files before retrying a command with side effects. Reuse the terminal sandbox ID for related operations; a browser sandbox ID identifies a different environment. If a file is rewritten, use its latest returned download link.

## Use Terminal with interface uploads

For a file assistant, connect a **Files** input to the AI Agent, insert its **File URLs** reference in the Prompt, and enable **File Access**. The builder may offer a shortcut that also adds Terminal. Configure the interface to pass that Files input.

Use **AI auto-fill** for Command when the agent should decide how to inspect or process each request. Tell the agent to read the actual upload before answering and to return real file links. Workflow files are available under `/home/user/`; save generated files there and keep **Enable New Files** on for downloads. Commands run in the separate StackAI environment.

Follow [Let an agent work with uploaded files](/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files.md) for the illustrated setup and use [Troubleshoot uploaded files and downloads](/guides-and-quickstarts/interfaces-and-end-user-experiences/let-an-agent-work-with-uploaded-files/troubleshoot-uploaded-files-and-downloads.md) for practical checks.

## Inputs

| Field               | Parameter             | Description                                                |
| ------------------- | --------------------- | ---------------------------------------------------------- |
| Description         | `description`         | Short description of what this command does.               |
| Command (required)  | `command`             | The terminal command to execute.                           |
| Terminal Sandbox ID | `terminal_sandbox_id` | Optional terminal sandbox ID to reuse an existing sandbox. |

## Configuration

| Field            | Parameter        | Description                                                                              |
| ---------------- | ---------------- | ---------------------------------------------------------------------------------------- |
| Enable New Files | `download_files` | Download files created in the sandbox so downstream nodes can use them. Default: `true`. |

## Outputs

| Field               | Parameter             | Description                                                    |
| ------------------- | --------------------- | -------------------------------------------------------------- |
| Standard Output     | `stdout`              | The standard output from the command.                          |
| Standard Error      | `stderr`              | The standard error output from the command.                    |
| Exit Code           | `exit_code`           | The exit code of the command.                                  |
| Success             | `success`             | Whether the command executed successfully (exit code 0).       |
| Terminal Sandbox ID | `terminal_sandbox_id` | The ID of the terminal sandbox used for this operation.        |
| New Files Created   | `new_files`           | List of new files created during command execution.            |
| Image Data          | `image_data`          | Base64-encoded image data from files created during execution. |

## Related guidance

[Tool Results, Errors, and Agent Continuation](/technical-reference/models-agents-and-skills/tool-results-errors-and-agent-continuation.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/stackai-tools/browser-and-computer/terminal-stackai-computer.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.