> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/ai-and-automation/using-ai-agents-to-manage-servers.md).

# Use AI Agents in Tempest

Use AI agents inside Tempest: chat next to your terminal, ask it to work on your server, and watch the results as they happen.

Work in Tempest and talk to an AI agent in the panel next to your terminal. Choose Claude Agent, Codex, OpenCode, Cursor, Qwen Code, or a custom ACP-compatible agent. Ask it to investigate a problem, run commands, or help with a change. You can watch the terminal output in real time and take over when needed.

Already working in an AI client such as Claude Code, Codex, or Cursor and want to give it access to your servers? See [Use Tempest in AI Agents](/ai-and-automation/install-tempest-mcp-server-in-ai-clients.md).

See [External Agents vs LLM Providers](/ai-and-automation/external-agents-vs-llm-providers.md) for a capability comparison.

## Choose an ACP agent

ACP (Agent Client Protocol) lets Tempest host an agent's conversation in its AI panel. These are the presets available under **Settings → AI → External Agents**:

| Agent preset     | Command                 | Arguments                                  | What to install first                                     |
| ---------------- | ----------------------- | ------------------------------------------ | --------------------------------------------------------- |
| **Claude Agent** | `npx`                   | `-y @agentclientprotocol/claude-agent-acp` | Node.js with `npx`; the adapter is fetched when launched. |
| **Codex**        | `npx`                   | `-y @agentclientprotocol/codex-acp`        | Node.js with `npx`; the adapter is fetched when launched. |
| **OpenCode**     | `opencode`              | `acp`                                      | OpenCode CLI, available as `opencode`.                    |
| **Cursor**       | `agent`                 | `acp`                                      | Cursor Agent CLI, available as `agent`.                   |
| **Qwen Code**    | `qwen`                  | `--acp`                                    | Qwen Code CLI, available as `qwen`.                       |
| **Custom**       | Your agent's executable | Its ACP launch arguments                   | Any ACP-compatible agent and its required runtime.        |

Install these on the machine running Tempest. Each agent uses its own account or provider configuration; complete its authentication steps when prompted.

## Set up your agent

1. Open **Settings → AI → External Agents** in Tempest Desktop.
2. Click **Add Agent** and choose **Claude Agent**, **Codex**, **OpenCode**, **Cursor**, or **Qwen Code**. Tempest fills in the command and arguments from the table above.
3. Keep the preset values, then save. If Tempest cannot find the executable, replace **Command** with its absolute path.
4. Open a terminal session, open the AI panel, and select the agent you just saved.
5. Complete that agent's sign-in or provider setup if prompted, then send a request.

The steps are the same for every preset. For example, choose **OpenCode** to use `opencode acp`, or **Claude Agent** to use its `npx` adapter; then select that agent in the AI panel.

For an agent without a preset, choose **Custom**, enter a name, command, and the ACP arguments provided by that agent, then save and select it in the AI panel. Use the agent's ACP entry point so Tempest can host the conversation.

If your agent needs an API key, provider endpoint, or proxy environment variable, enter the values in its **Environment** field (`NAME: value`, one per line). This is useful when Tempest is launched from the Dock and does not inherit your shell's environment.

Tempest connects the agent to its terminal tools for you. You do not need to register Tempest MCP separately in your AI client for this workflow.

## Try it

Start with a simple check in your open terminal:

> Run uptime in this terminal and explain the load averages.

Then try a task that needs investigation:

> Find what's using disk space under /var. Show me the largest directories before making any changes.

Or work through a service problem together:

> Check why nginx failed to start. Read the recent logs and suggest a fix.

The agent reads terminal output and can interact with full-screen programs such as `htop`. You see the same live terminal, so you can inspect the results and continue manually. If you take over, tell the agent to pause before typing into the same session.

## Other ways to use AI

* **Use a model directly:** the [Storm AI](/ai-and-automation/tempest-ai-assistant.md) supports hosted providers, your own model endpoint, and Apple Intelligence.
* **Stay in your AI client:** [Use Tempest in AI Agents](/ai-and-automation/install-tempest-mcp-server-in-ai-clients.md) gives your external AI client Tempest's tools through MCP. Choose Desktop for shared live sessions, or CLI for sessions managed entirely by the AI.
* **Run an agent on a remote server:** the **Use AI Agents** preset in an SSH connection's **Startup Command** launches a coding agent on that server. This opens the agent's own terminal interface; it is separate from the AI panel described above.

For details about tool access and approvals, see [Storm AI Security Model](/ai-and-automation/tempest-ai-security-model.md).