Engine Setup

Set up local Vibe engines in the Mac app or through the Klipeo bridge, choose models, use the klipeo commands, and connect an MCP client.

The setup reference behind Engines & Models.

Models the cloud engine uses

anything, and it's the one that tracks token usage and cost (see Save on AI cost).

The cloud engine has no model to pick. Its row in the agent menu shows the model it runs: every turn runs on Gemini 4 Argon, Google's newest model, with medium thinking effort, the same model and effort for a one-line trim and for a multi-step edit. When Vibe hands separate shots to helper agents that work side by side, those helpers run on Gemini 3.8 Flash with high thinking effort, which costs less per step.

Generation picks its own model for each job. Pictures come from GPT Image 2.5 Flare and video shots from Gemini Omni. With your own fal key saved in Model keys, Vibe also moves to Seedance 2.5 for a single take longer than 10 seconds and uses Kling O3 to swap a person in a clip, and uses GPT Image 2.5 only when you ask for GPT. Name a model in your message and Vibe uses that one.

When Vibe changes a clip on your timeline, such as adding an object or swapping a person, it sends only the part the clip shows, not the whole file. Gemini Omni takes up to 10 seconds of it and Seedance 2.5 up to 30, so trim a long recording to the moment you want changed. A clip longer than every model takes is refused before any credits are spent, with the limit in the reply.

The other four are local engines. They drive a coding CLI you already have set up, and Klipeo talks to it through editing tools, so the AI still makes real changes to your timeline. The work happens on your hardware with your own account, so Klipeo isn't billing you for the tokens.

Local engines in the Mac app

The Klipeo Mac app runs the four local engines itself. You don't install the bridge or Node.js, and you don't keep a terminal open. The app finds each CLI the way your terminal does, by reading your login shell's PATH, checks its version and whether you're signed in, and runs it for each Vibe turn you start in the app.

When a local engine needs a creative choice, it can show a question in Klipeo's composer and pause for your answer. It uses the same saved run as the edit, so answering continues that run. Reconnecting restores the unanswered question without automatically submitting a previous answer again.

Set up the CLI

Install Claude Code, Codex, Gemini CLI, or OpenCode and sign in to it once in Terminal, the same way you would to use it on its own. Codex needs version 0.144.1 or newer. Gemini CLI needs a paid Gemini API key in GEMINI_API_KEY, or a Gemini Code Assist Standard or Enterprise sign-in: since June 18, 2026 Google no longer serves Gemini CLI to Google AI Pro, Ultra, or free Code Assist accounts.

Check Settings > This Mac > Agents

Open Settings (⌘,) and choose Agents under This Mac. The agents on this Mac are listed on the left, each with its version, plan (for example ChatGPT Pro 5x or Claude Max), and a switch that turns it off on this Mac. An arrow next to the version means a newer release is out. Choose an agent to see its settings on the right:

The top shows its maker, version, and status. When a newer version is out, Update to v… runs the agent's own updater. Gemini CLI has no updater, so it shows the Homebrew or npm command to copy instead. Cursor and Devin don't publish their newest version, so they offer Check for updates.
When it can't run yet, the next row says what to do, Install, Sign in, or Update, with the exact command and a Copy button. Gemini CLI with a Google sign-in and no API key shows a warning, because the app can't tell from the sign-in alone whether Google still serves that account. It still runs, and if Google refuses the turn, the error says what to change.
Model lists the models your account can use, read from the CLI. Default leaves the choice to the CLI's own setting, except Gemini CLI, where it runs Gemini 3.8 Flash (see Choose a model). Claude Code models add an Effort row (low, medium, high, xhigh, or max), Codex models that offer reasoning levels add a Reasoning row, and OpenCode models with variants add a Variant row.
Models in the menu has a switch for each model. Turn off the ones you don't use and the agent menu in the composer leaves them out. Hide all and Show all change every model at once. This is saved on this device, and the model a run already uses always stays in the menu.
Program location is where the program lives. Leave it empty to find it the way Terminal does. Type a bare name or a full path that starts with / (not ~), then press Return or leave the field to save it; Escape puts it back. If nothing runs at that path, the row says so.
Environment variables are passed to the agent on every run, such as an API key or a base URL. Enter a name and a value, then choose Add variable. Values stay in the Mac app; the page only shows names. Names Klipeo sets itself to keep runs isolated, such as HOME, PATH, CODEX_HOME, and anything starting with KLIPEO_ or OPENCODE_, can't be used.

Add agent, at the bottom of the list, shows the agents that aren't installed yet with the command that installs each one.

Choose Check again after you fix something in Terminal.

Pick it in Vibe

Open the agent chip under the message box. Local engines are listed under On this Mac: a ready engine shows the model it will use, and one that can't run shows why, such as Not signed in or Not installed. Point at an engine (or press the right arrow key) to see its models, read straight from the CLI. A model with effort or reasoning levels opens them beside it, with the model's default marked. Pick one to switch to that engine. An engine that can't run offers Set up instead, with the fix.

The first time you switch to a local engine in a project, the Use card confirms it and shows what the next turn runs with: the account and plan, version, the model and effort on one line (with the model's context size when the CLI reports it), and what the agent may touch. Below that, Usage shows your plan limits as the CLI reports them right now: for Claude Code the 5-hour session and weekly limits (and a weekly limit for one model, such as Fable, when your plan has one) with when each resets, and how this week's usage splits between Claude Code and other apps; for Codex its weekly and session limits and any free limit reset, which Use reset spends right from the card; for OpenCode the tokens and cost of the last day and week. Cursor, Grok, Devin, and Gemini CLI don't share their usage with other apps, so the card says so. If you send a message before confirming, the card opens for you.

Vibe remembers the model and reasoning level you picked for each engine on this device. The Model row in Settings shows the same choice, so changing it in one place changes it in the other.

The app keeps the same boundaries as the bridge:

Each turn runs in a private folder under ~/Library/Application Support/Klipeo/LocalAgents that only your macOS user can read, and the folder is deleted when the turn ends.
Claude Code keeps one session per chat. Your next message goes to the same running Claude Code, so it starts faster and remembers its own earlier steps. The session's folder stays until the chat is unused for a week, and Claude Code saves the conversation in ~/.claude/projects so it can pick up again after the app restarts. An idle session stops after 10 minutes, and all of them stop when you quit the app. Stopping a turn interrupts it without ending the session.
The CLI edits only through Klipeo's tools. To let Claude Code also read files, run shell commands, and search the web on your Mac once you have confirmed the engine for the project, choose Project access under Permissions in Settings > This Mac > Agents. It is the same choice as klipeo start --host-access, so keep Klipeo tools only on a Mac you don't control. Cursor, Grok, and Devin stay on Klipeo's tools either way.
Project folder on the same page lets a confirmed turn that shares project context include a read-only Git summary of that folder.
Claude Code runs without your ANTHROPIC_API_KEY, so it uses your Claude sign-in and subscription.

The app only runs turns you start inside it. A browser tab and a running klipeo start bridge keep working the way they do below.

How a local engine edits

Every local turn gets the same video-editing playbook from Klipeo, in the Mac app and through the bridge. It is written to the turn's private folder as AGENTS.md, which Codex and OpenCode read on their own. Claude Code gets it as an added system prompt and Gemini CLI as its context file. The playbook has the CLI:

read the timeline first with the editor-control__readComposition tool, which lists tracks, clips, captions, and media with their times in seconds,
look at the rendered preview with editor-control__inspectPreviewFrames before and after a visual change,
make one change per tool call, so each change is one undo step in the editor, and
finish with a short summary of what it changed and how it checked.

The preview stills come from the composition open in your editor, so keep it open while a local engine works. Without it, the CLI says its result is unverified.

Each tool tells the CLI whether it only reads, makes an edit you can undo, or deletes, so Codex runs reads and ordinary edits without stopping for a prompt it can't show you. You confirm the engine's access for each project before its first turn, and publishing always asks you first. A CLI waits up to five minutes for one tool call. Text that comes from transcripts, captions, on-screen text, or the web is marked as data in tool results, so the CLI doesn't follow instructions hidden in your media. OpenCode doesn't load your personal ~/.claude/CLAUDE.md or Claude skills into a Klipeo turn.

What is the Klipeo bridge?

Klipeo runs in your browser, but the local CLIs (Claude Code, Codex, and so on) run on your computer. Those two can't talk to each other directly. The bridge is the small program that sits between them.

Here's the whole idea in one line:

Klipeo (browser)  ⇄  Klipeo bridge (your machine)  ⇄  your CLI (Claude Code, etc.)

When you ask Vibe to do something on a local engine, Klipeo sends the request to the bridge running on your machine. The bridge hands it to your CLI, the CLI does the work using your own account and model, and the results flow back the same way. So the AI tokens are on you, not on Klipeo, and your footage and edits stay on your machine.

The bridge is part of Klipeo Pro. Klipeo checks the account behind the bridge on every request, so a free account can't connect it, even with a copied command or token. On a free account, the bridge's setup card shows Included with Pro beside the command. Choose it to see what Pro includes and an Upgrade to Pro button.

You install the bridge once. It's published on npm as @bytehumi/klipeo-bridge, and installing it gives you a klipeo command in your terminal.

Connect the bridge

Before you start

You'll need Node.js 22.12 or newer, and the CLI you want to drive (for example Claude Code or the Gemini CLI) already set up and working on its own. The bridge doesn't install those for you, it just connects them to Klipeo.

Install the bridge

Install it globally so the klipeo command is available anywhere:

npm i -g @bytehumi/klipeo-bridge

Link the bridge to your Klipeo account. This opens your browser to authorize the machine, then drops you back at the terminal.

klipeo login

Start it

Run the daemon. It stays alive in the foreground, keeps the connection to Klipeo open, and detects which CLIs you have installed.

klipeo start

Leave this running while you work. If you close it, local engines go offline until you start it again.

Pick your engine in Klipeo

Back in the editor, open the agent chip under the Vibe message box and choose Claude Code, Codex, Gemini CLI, or OpenCode from the Your own CLI group. A Connect card opens with the command to run and a live status pill. Choose Check connection to let the browser reach the bridge. If your browser asks about local network access, choose Allow. Continue selects the engine only after Klipeo verifies the bridge's server connection and finds the selected CLI. The card also shows whether the bridge has access to your computer's files and shell. Your project permission still applies to that one CLI in that one project.

On a Mac, the card's Download for Mac link offers the desktop app, which runs your installed local agents without a separate bridge terminal.

Until the bridge answers, each local engine in the menu reads Bridge off. If it goes offline later, Vibe says so instead of silently failing, and points you back here.

Pro plan means the bridge reached Klipeo, but your account has no active paid plan. The bridge prints The bridge is part of Klipeo Pro. Upgrade at https://klipeo.com/pricing. once and stops trying to connect. Upgrade, then run klipeo start again.

Bridge unavailable means the bridge is running but cannot reach Klipeo. Check your internet connection and leave the bridge running to retry. Sign in again means the bridge could not authenticate. Stop it, run klipeo login, then start it again. An unavailable CLI shows its reported reason, such as an update it needs, instead of letting you start an unusable turn. After installing or updating a CLI, choose Check connection to refresh detection immediately.

Choose a model

Once an engine is connected, its row in the agent menu lists its models. Leave it on Default to use whatever that CLI is already configured for, or pick a specific model, and a reasoning level when the model offers them. Klipeo reads the list straight from your running bridge, so it only shows models you actually have access to. Gemini CLI is the exception: its Default runs Gemini 3.8 Flash, because the CLI's own default can pick a Pro model a new API key can't use. Gemini CLI 0.65 doesn't list Gemini 4 Argon yet.

The rest of the `klipeo` commands

Command	What it does
`klipeo login`	Browser sign-in. Add `--token <token>` to skip the browser entirely.
`klipeo start`	Runs the daemon on `localhost:7777`.
`klipeo start --host-access`	Same, but also lets the CLI use its own file and shell tools on the machine running the bridge. It applies only after you confirm the engine for the project, and the CLI can then read files, write files, and run commands there. Leave it off unless you want that.
`klipeo status`	Shows bridge status and which CLIs it found.
`klipeo detect`	Lists the supported coding CLIs on this machine.
`klipeo logout`	Clears the saved credentials.

A few details that save you a head-scratch: only one bridge can run at a time, so klipeo start refuses to launch a second one while the first is alive. The browser login gives up after five minutes if you never finish it. And a bridge sign-in lasts 90 days, refreshing itself quietly, with a week of grace after expiry before you have to run klipeo login again.

Bridge offline?

If Vibe says the bridge isn't running, check that klipeo start is still going in a terminal and that you're on the same machine. Check the browser too: your browser has to be allowed to reach localhost:7777. Choose Check connection in the connection card to request that access. First-time sign-in is included in klipeo start. If the model list is empty or stale, update the bridge with npm i -g @bytehumi/klipeo-bridge@latest and restart it. You can always switch back to the Klipeo cloud engine, which needs none of this.

Cloud needs no setup

If all of that sounds like a lot, ignore it. The default Klipeo engine works in the browser with nothing installed. Reach for a local engine when you want to run on your own model or keep your AI cost off your Klipeo plan.

Drive Klipeo from an MCP client

The bridge points a CLI at Klipeo. This does the opposite: it lets an MCP client you already use call Klipeo's editing tools on your own timeline. For the setup commands, see Use Klipeo from your agent.

The server is at /api/vibe/mcp on your Klipeo origin. It speaks JSON-RPC over HTTP on POST. A plain GET on the same path returns a discovery document: the server name, the protocol versions it supports, where to authorize, and the tools it exposes.

It supports initialize, tools/list, tools/call, and ping. It has no resources and no prompts, so those lists come back empty.

Authorizing a client

Every tool call needs a bearer token, and the token is what decides whose compositions get edited. Two kinds work:

OAuth

The normal path for an MCP client. Klipeo publishes protected-resource metadata at /.well-known/oauth-protected-resource/api/vibe/mcp, pointing at the authorization server at /api/auth. A client that follows the challenge gets sent through Klipeo's consent screen.

API key

For a script rather than an interactive client. Use a Klipeo API key that has the write scope.

Two scopes govern an OAuth token: klipeo:timeline:read and klipeo:timeline:write. Calling a tool needs the write scope. A token without it is refused with an insufficient_scope error rather than quietly reading only. An unauthorized request comes back with a WWW-Authenticate challenge that names the metadata URL, so a well-behaved client can start the flow on its own.

Your Vibe session id in the editor is not a credential and cannot be used here.

What a connected client can do

It gets the same official Skill tools Vibe itself runs, minus any skill you've turned off under Settings then Skills. Calls land on one composition: the one named in an x-klipeo-composition-id header, or your most recent composition if the header is absent.

The edits are not off to one side. They land on the real timeline and stream into the editor as a Vibe session, so if you have that composition open you watch them arrive.

Every listed tool carries MCP annotations: readOnlyHint for tools that only read, and destructiveHint and openWorldHint for the rest, so a client can decide which calls need your approval. An edit's result is a short list of what changed, with track, clip, and time references, rather than the full edit payload. The full patches are in the result's _meta.patches.

Treat the token like a password

A write-scoped token lets whatever holds it edit your compositions as you. Give one only to a client you trust, and revoke it when you're done.

OAuth

API key

On this page