Pair a runner and add profiles

A runner is the minga service on a machine you own. It connects out to Minga, takes work for your workspace and runs it in the Claude Code and Codex CLIs with your own setup. This guide installs one, pairs it, keeps it running and sets up its profiles. The runner works on macOS and Linux; Windows is not supported yet.

Install and pair

Install the binary:
```
curl -fsSL https://app.minga.run/install.sh | sh
```
It goes to ~/.local/bin (set MINGA_INSTALL_DIR for another place). No sudo; the script never edits your shell profile and prints the PATH line to add if needed.
Pair this machine with your workspace:
```
minga runner login
```
The runner prints a link and a code and waits. Open the link in a browser where you are signed in to Minga (on macOS it opens by itself; over SSH, open it on your laptop or phone), check the code, pick the workspace under Add it to, and approve. The request expires after 10 minutes.

The runner shows in the app under its host name. To choose another name:
```
minga runner login --name vps-1
```
Use --no-open to keep the browser closed.
Keep it running as a user service:
```
minga runner install
```
- macOS: a LaunchAgent, ~/Library/LaunchAgents/run.minga.runner.plist, loaded into your login session (so the CLIs see your Keychain logins). It starts at login and restarts if it stops.
- Linux: a systemd --user unit, ~/.config/systemd/user/minga-runner.service, enabled and started. To keep it running while you are logged out (on a VPS, say), run the command it prints: sudo loginctl enable-linger $USER.
The service gets the PATH of the shell you ran install from, so it finds claude, codex, git and gh. If you install a CLI later in a new place, run minga runner install again.
Check it:
```
minga status
```
It shows the connection, the server, the workspace, the profiles and the repos. In the app the runner appears under Settings › Runners as online.

One machine is paired with one workspace. To move it to another workspace, run minga runner logout first.

Profiles: your CLI setups

A profile is one CLI setup on the machine: the CLI and its home directory, where its login and settings live. On its first start the runner adds profiles for the homes it finds:

Profile	CLI	Home
`claude-personal`	Claude Code	`~/.claude`
`codex-personal`	Codex	`~/.codex`

Check them

minga profile check

For each profile it shows whether the CLI is signed in, which models it offers and its usage. It never reads the contents of your credentials and never runs a model turn. Add a profile id to check one, or --json for the full report.

Add a second setup

Use separate profiles for separate logins: a personal and a work Codex account, or a Claude Code setup with a different API key. Each one needs its own home directory, set up with that CLI first.

minga profile add codex --id codex-work --home ~/.codex-work
minga profile add claude --id claude-team --home ~/.claude-team

If the home does not exist yet, the runner prints the command to sign in there first. For Codex that is CODEX_HOME=~/.codex-work codex login.

Options:

--default makes it the default profile for its CLI (the one a run uses when it names none);
--workspaces <id,id> lets it serve only those workspaces;
--cli-path <path> uses a specific CLI binary instead of the one on PATH.

List, limit and tune

minga profile list                             # every profile with its access mode
minga profile scope codex-work <workspaceId>   # serve only this workspace
minga profile scope codex-work --all           # serve every workspace again
minga profile set codex-work access ask        # see Access modes

A workspace’s id is the part after /w/ in the app’s address. minga profile set also takes mcp, mcp-approval, network, model and effort. See Access modes and the CLI reference.

You can change a profile’s access mode, model and effort in the app too, under Settings › Runners, if you own the runner.

Update

The runner installs new signed releases on its own when it is idle. To update now:

minga update            # install the latest release
minga update --check    # only check

A running runner restarts into the new version as soon as its active runs end, and takes no new runs meanwhile.

Remove

minga runner uninstall   # remove the service
minga runner logout      # remove this machine's pairing and credentials

The runner stays listed in the app until you remove it there (Settings › Runners).

Claude Code is a trademark of Anthropic; Codex of OpenAI. Minga is not affiliated.

Privacy Imprint Terms