Skip to main content

Run your first local session

In this tutorial, you will start mecatui in a local project and ask Mecatl to inspect it. mecatui runs a private embedded server, so you do not need to start a separate service.

Prerequisites​

You need:

  • macOS or Linux with Homebrew;
  • an API key for Anthropic, OpenAI, or OpenRouter; and
  • a local project directory that you trust.

The project is your workspace. Mecatl limits its file tools and commands to this directory.

Install Mecatl​

Homebrew installs the mecatui client and the mecated server:

brew install stacklok/tap/mecatl
mecatui --version

The version command should print a release tag. For signed archives and source builds, see Install Mecatl.

Configure a provider and start mecatui​

On Linux, you can explicitly launch the local, line-oriented provider setup:

mecatui llm setup

It can save a supported API key, choose a default model, and then start embedded mecatui after separate confirmations. It is not an automatic first-run wizard. Before using it, read Set up a local embedded provider for credential custody, environment precedence, passive status, and platform limits.

Alternatively, Mecatl detects a provider from its environment variable. This path also works on macOS, where local setup writes are unsupported. Set one of ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENROUTER_API_KEY in the shell where you will run mecatui:

cd <PROJECT_DIRECTORY>
export <PROVIDER_API_KEY>="<API_KEY>"
mecatui --workspace "$PWD"

Replace <PROVIDER_API_KEY> with the variable for your provider. If setup already started mecatui, change to your project directory before running setup so that it uses the intended workspace.

The welcome screen shows your workspace and active model. To use a different model, enter /models, select one, and press enter. A small, low-cost model is enough for this tutorial.

The header also shows mode default, identifying the active permission mode. With the default permission policy, read-only tools can run without approval and actions that change the workspace ask first.

Inspect the project​

Enter this request:

Inspect the top-level files and explain what this project does. Cite the files you used.

You should see tool cards as Mecatl reads the workspace, followed by an answer based on your project. Press ctrl+t on a tool card to inspect its full input and result.

You now have a local session: the conversation, selected model, workspace, and tool history that Mecatl keeps together. Exit with ctrl+c twice or /quit. To continue the newest stored session, run:

mecatui --workspace "$PWD" --resume-latest

Add tools from local MCP servers (optional)​

MCP servers give agents tools for working with external services and data. ToolHive is Stacklok's open source runtime for running MCP servers locally.

If ToolHive has MCP servers running in its default group, the embedded server discovers them at startup. Enter /mcp to inspect the available MCP sources and tools. Mecatl connects to those servers but does not start them.

Next steps​