Run your own agent on Etude

Open a supported agent in one click

Etude sets these agents up for you and opens them in Terminal, already running on Etude’s model:

• OpenCode by Anomaly, “the open source coding agent”.
• Hermes Agent by Nous Research, for research and everyday tasks.
• pi by Mario Zechner, an agent toolkit with a coding agent.

If the agent isn’t installed, Etude installs it first.

Where

Settings › External Agents › Open in Terminal ↗ beside the agent

Needs

Etude in your Applications folder, and a model running. The first time, macOS may ask for your password to install the etude command.

Connect any other agent

For an agent Etude doesn’t list, Etude gives you a setup prompt. Copy it from Manual setup / API, paste it into the agent, and the agent sets itself up: it asks which agent you installed, shows you each file before changing it, then sends a test message. The prompt names the file that holds Etude’s key, never the key itself.

I just installed an AI agent on this Mac and want it to use Etude, a model server on this Mac.
1. Ask me which agent I installed, and how, if that changes where its settings live.
2. Set it up with: base URL http://127.0.0.1:11435/v1 (OpenAI-compatible), model <model name>, API key in <key file> (read it; don't print it).
3. Tell me each file before you change it, change only that agent's settings, then send one short test message and show me the reply.

Where

Settings › External Agents › Manual setup / API, with the model name and key file filled in

Connection details

To set an app up by hand, copy these from Connect any app (API). They’re the same for every agent and app.

Base URL

http://127.0.0.1:11435/v1. The port is 11435 unless you change it under Port.

API key

Shown (and replaceable) in the pane; also saved in ~/Library/Application Support/Etude/api-key. Send it as Authorization: Bearer <key>.

Model

The Model name in the pane: the model Etude is running now.

API

OpenAI Chat Completions (/v1/chat/completions) and Anthropic Messages (/v1/messages), with streaming and tool calling; /v1/models lists the model.

curl http://127.0.0.1:11435/v1/chat/completions \
  -H "Authorization: Bearer <key>" \
  -d '{"model":"<model name>","messages":[{"role":"user","content":"Hello"}]}'

Good to know

• Only agents on this Mac can connect. Etude listens on 127.0.0.1, not on your network.
• Etude has to be open with a model running. The address works as long as the model does.
• Agents use the model Etude is running. If you switch models, update the model name in agents you set up by hand; agents opened from External Agents pick up the new one the next time.
• An external agent follows its own rules. Etude Agent’s sandbox and approvals don’t apply to it, so check that agent’s own settings for what it may do on your Mac and online.

Rather use the agent built into Etude? See what Etude Agent can do.