# Local shell

Enable agents to run commands in a local shell.

Local shell is a tool that allows agents to run shell commands locally on a
machine you or the user provides. It's designed to work with Codex CLI and
[codex-mini-latest](https://platform.openai.com/docs/models/codex-mini-latest).
Commands are executed inside your own runtime, **you are fully in control of
which commands actually run** âthe API only returns the instructions, but does
not execute them on OpenAI infrastructure.

Local shell is available through the
[Responses API](https://platform.openai.com/docs/guides/responses-vs-chat-completions)
for use with
[codex-mini-latest](https://platform.openai.com/docs/models/codex-mini-latest).
It is not available on other models, or via the Chat Completions API.

Running arbitrary shell commands can be dangerous. Always sandbox execution or
add strict allow- / deny-lists before forwarding a command to the system shell.

See Codex CLI for reference implementation.

## How it works

The local shell tool enables agents to run in a continuous loop with access to a
terminal.

It sends shell commands, which your code executes on a local machine and then
returns the output back to the model. This loop allows the model to complete the
build-test-run loop without additional intervention by a user.

As part of your code, you'll need to implement a loop that listens for
`local_shell_call` output items and executes the commands they contain. We
strongly recommend sandboxing the execution of these commands to prevent any
unexpected commands from being executed.

## Integrating the local shell tool

These are the high-level steps you need to follow to integrate the computer use
tool in your application:

1.  **Send a request to the model**: Include the `local_shell` tool as part of
    the available tools.
2.  **Receive a response from the model**: Check if the response has any
    `local_shell_call` items. This tool call contains an action like `exec` with
    a command to execute.
3.  **Execute the requested action**: Execute through code the corresponding
    action in the computer or container environment.
4.  **Return the action output**: After executing the action, return the command
    output and metadata like status code to the model.
5.  **Repeat**: Send a new request with the updated state as a
    `local_shell_call_output`, and repeat this loop until the model stops
    requesting actions or you decide to stop.

## Example workflow

Below is a minimal (Python) example showing the request/response loop. For
brevity, error handling and security checks are omittedâ**do not execute
untrusted commands in production without additional safeguards**.

```python
import subprocess, os
from openai import OpenAI

client = OpenAI()