Terminal sessions

opencompanion terminal starts your own coding CLI, in your own terminal, already wired to an app you paired:

opencompanion terminal --url https://your-app.example/api

The CLI that opens is the one you already use, signed in with the subscription you already pay for. What OpenCompanion adds is the app:

• The app's tools are served to the CLI over a loopback MCP server the daemon runs, so the model can act in the app (list your data, create a record, run a job) from the terminal.
• The app's instructions are composed by the app and injected as the session's context, so the model knows what product it is working in.
• The folder is the app's own work folder, unless you point the session at a folder you granted.

Everything a session needs is composed at open time, so there is nothing to configure in the app and no key to paste anywhere.

Open a session

opencompanion terminal                                  # the app you paired (asks when there are several)
opencompanion terminal --url https://your-app.example/api
opencompanion terminal acme --url https://your-app.example/api --cli codex
opencompanion terminal --url https://your-app.example/api --cwd ~/code/my-project

The CLI owns your terminal from there: Ctrl+C, its own slash commands, and its own approval prompts all behave exactly as they do when you run it yourself. When it exits, the session's loopback MCP goes with it.

Every session is written to the audit log before the CLI starts, with the CLI, the folder, and the local MCP servers it was given - so a session can never run unlogged.

Running OpenCompanion in local mode? An app on the same machine opens these sessions for you with terminal --local; the composition is identical, just scoped to local instead of a paired backend.

What the app can and cannot do

The app composes the session; it never reaches your machine through it.

• It never sees where you are. No session reports a path to any app, and the session an app composes cannot carry one, so an app can neither choose your folder nor learn it.
• It cannot add an MCP server. Any MCP server an app tries to push into a session is dropped. The only local ones are the ones you added yourself (below).
• It cannot hand the CLI a permission rule. An app tool's name is checked before the session opens; a name that could be read as a CLI permission rule (a comma, a space) refuses the session outright rather than pre-approving something on your machine.
• The app's access token never reaches the CLI. It stays in the daemon, which makes the app's tool calls on the CLI's behalf. A prompt-injected model reading its own environment finds only the keys you typed yourself.

Your own MCP servers

A session gets the app's tools automatically. To give it your tools as well - your issue tracker, your database, your notes - add MCP servers to the daemon, per app:

opencompanion mcp add linear --url https://your-app.example/api --http https://mcp.linear.app/mcp
opencompanion mcp add notes --url https://your-app.example/api --command npx --arg -y --arg @acme/notes-mcp --env NOTES_TOKEN=nt_live_...
opencompanion mcp list
opencompanion mcp remove linear --url https://your-app.example/api

• --http <url> for a remote server, or --command <bin> with repeated --arg for a local one. Exactly one of the two.
• --env KEY=VALUE (repeatable) for a local server's credentials.

They are wired into every terminal session for that app, alongside the app's own tools. They are local: an app can never add, read, or list one.

Your own folders

A session opens in the app's work folder by default. To work on your own project, grant the folder once, then point a session at it:

opencompanion policy grant-folder add ~/code/my-project --url https://your-app.example/api
opencompanion terminal --url https://your-app.example/api --cwd ~/code/my-project

A --cwd anywhere else is refused. Grants are yours alone - an app can never add, name, or widen one - and every grant and revoke is audited. See Granted folders for the rules, and for what a folder does and does not mean once a CLI is running in it.

If the app cannot open one

An app has to ship the route a session is composed from. If it has not, the daemon says so plainly and names who fixes it - the app's maintainer, not you. Dispatched runs, schedules, and chat keep working meanwhile.