Skip to content

Using Merlin

Prerequisites

Check the agent, machine, workspace and access needed before connecting Merlin.

Merlin is designed for teams whose engineers already use Claude Code or Codex in their day-to-day work. It does not replace those agents or host another model. Its purpose is to give those teams a new collaboration model: eligible people can delegate work to the agents engineers already run, follow progress in the open, add context and steer the next step.

That means Merlin starts where standalone agent setup ends. At least one person needs an agent that can already complete a task locally. Merlin adds workspace identity, automations, shared access, collaborative follow-ups and delivery back to Slack, Linear or GitHub around that working local environment.

Quick readiness check

Use this table before installing Merlin. If any required check fails, fix the local environment or workspace access first.

CheckReady when
AgentClaude Code or Codex can complete a real task from the intended project directory.
Connected machineA supported macOS, Windows or Linux machine can stay awake, online and running Merlin.
Local environmentThe machine has the repositories, credentials, tools, skills and MCP servers the work needs.
Workspace setupAn owner or admin can create or configure the workspace and connect the intended surfaces.
Slack installationIf the team uses Slack, you can install the Merlin Slack app or get help from a Slack admin.
Runtime-sharing decisionThe owner has decided whether the runtime stays private or becomes available to teammates.
BillingThe runtime owner's provider plan and the workspace's Merlin plan are understood separately.

Supported agents

Merlin currently supports:

  • Claude Code.
  • Codex.

You need at least one of them, not both. Each installed provider becomes a separate runtime after the machine connects to Merlin. Additional runtime providers are not supported today.

Prepare a working provider

Before connecting a machine, its owner needs:

  • Claude Code or Codex installed on that machine.
  • A local provider account that is signed in and able to run a task.
  • Available usage under that provider's account or plan.
  • A successful local test from a project directory the agent may use.

Merlin uses the provider login already available to that operating-system user. The desktop app can start the provider's own sign-in for you. The Linux daemon cannot.

Prepare a machine for team work

Use a macOS or Windows machine with the Merlin desktop app, or a Linux machine with the CLI daemon. The runtime owner must be able to sign in to Merlin and approve that machine for the intended workspace.

The machine must stay awake, online and running the Merlin client while it accepts work. The client opens an outbound connection to Merlin, so you do not need to expose an inbound port on the device.

Prepare the local work environment

Merlin can use only what the local agent and operating-system user can already reach. Before sharing work from this machine, confirm that it has:

  • The repositories and files required for the task.
  • Git credentials and repository permissions for any clone, branch, push or pull request work. For GitHub, install the GitHub CLI and run gh auth login so the agent can open pull requests and read check logs with your credentials.
  • The language runtimes, package managers and command-line tools the work requires.
  • Any local skills or MCP servers the agent should use, already installed and authenticated.

Merlin does not create these capabilities or grant the agent broader local access. A task that depends on a missing file, credential, tool or permission fails at that boundary.

Prepare the Merlin workspace

The runtime owner needs a Merlin account and membership in the correct workspace before approving the machine. Merlin sign-in uses Google or an email code.

For the team's first setup, you also need:

  • If the team uses Slack, permission to install its apps, or help from a Slack admin.
  • An owner or admin who can configure the workspace and the channels where Merlin may respond.
  • Owner or admin authority for any Linear organization or GitHub account the team chooses to connect.

Linear and GitHub are optional. Connect only the surfaces the team plans to use. Each connected surface must cover the relevant channel, organization or repository. Registered members should also link their personal identities so Merlin can recognize them there. See Set up Merlin for the complete owner and admin flow.

Decide who can use the runtime

New runtimes begin private. A private runtime accepts only its owner's requests. If teammates should be able to delegate work to it, the runtime owner must deliberately make it public after reviewing which files, credentials, skills and MCP tools the local agent can use.

Not every workspace member needs to install an agent. The workspace still needs at least one connected, enabled and available runtime that the requester is eligible to use. See Devices and runtimes and Security before sharing one.

Keep provider and Merlin billing separate

A Merlin workspace subscription does not include a Claude Code or Codex subscription. Model usage remains on the runtime owner's provider account and is subject to that provider's plan and usage limits.

Merlin does not ask for a provider API key during installation. If the local agent needs authentication, complete the provider's own sign-in flow on the same machine. See Billing and plans for the separate Merlin workspace subscription.

Check the local agent

Before installing Merlin, open a terminal on the machine and confirm that the agent you intend to use is available:

claude --version
codex --version

Only the command for the provider you use needs to succeed. If neither is installed, install the Claude or ChatGPT desktop app (Merlin finds the agent those apps carry, though the Claude app counts on macOS only) or the provider's command-line installer. If it is installed but signed out, choose Sign in on that agent in the Merlin desktop app's Connection view, or use the provider's own login flow (claude login or codex login).

After Merlin is installed, the device should report at least one available runtime. A runtime marked Needs sign-in, Offline or Unavailable cannot accept work until its local provider is repaired. See Devices and runtimes for those states.

Next step

Continue to Installation to install the desktop app or Linux daemon, approve the machine for a workspace and confirm that its runtime is available.