Skip to main content

Configuration & environment

lmctl resolves its local state from a SQLite database, normally through the active workspace. The variables below control which database or workspace it uses and, optionally, how to reach a remote daemon.

Database and workspace resolution​

The verified global selectors are:

  • --db PATH to point one command at a specific SQLite database.
  • --workspace NAME to run against an isolated workspace.
  • lmctl workspace use <name> to select the active workspace for later commands.

Profiles are legacy. Use lmctl workspace migrate when you need to migrate old profile state into workspaces.

Use workspaces when you want separate local environments. In a non-interactive shell, provide the basedir and provider slots explicitly:

lmctl workspace init --name test-workspace \
  --basedir /tmp/lmctl-workspaces \
  --provider1 claude \
  --provider2 codex \
  --provider3 gemini
lmctl workspace use test-workspace
lmctl --workspace test-workspace status

Daemon URL and token​

The default daemon URL is:

http://127.0.0.1:8787

Set these variables when API auth is enabled or when the daemon runs on a non-default URL:

export LMCTL_API_URL=http://127.0.0.1:8787
export LMCTL_API_TOKEN=<token>

Serve port​

lmctl serve listens on port 8787 by default. If you run it on another port, keep the API URL in sync:

lmctl serve --port 8788 > lmctl.log 2>&1 &
export LMCTL_API_URL=http://127.0.0.1:8788

Provider authentication​

Provider CLIs authenticate themselves. Install and authenticate at least one of:

claude
codex
gemini
copilot
opencode
qwen
agy

agy is the Antigravity CLI. It is distinct from Gemini even though its session state lives under ~/.gemini/antigravity-cli.

Then seed a team member with that provider:

lmctl team add-member my-team --alias QA --provider claude
lmctl team seed my-team

For .lmctl teamfiles, use the top-level seed command:

lmctl lint ./my-team.lmctl
lmctl seed ./my-team.lmctl

lmctl lint validates teamfile structure, warns on stale or placeholder session ids, and checks configured models against the tested provider catalog. Use per-member --model values when you want cost-aware routing by role:

lmctl team add-member my-team --alias Architect --provider claude --model <model>
lmctl team add-member my-team --alias Coder --provider codex --model <model>