Things to know

Things to know

Practical notes and frequently asked questions about malac.

Before you rely on it

malac is young software. macOS is the primary platform, Linux works, and Windows is not supported yet. It is opinionated and changes with its author's workflow, so expect defaults and keys to move now and then.

Autopilot means autopilot. With -y, the agent runs commands and edits files without asking. Deny rules still apply, but they are pattern matches, not a sandbox. Use it in repositories you can restore. See Permissions and autopilot.

Project config is restricted. A repository's .malac/config.toml cannot set the mode, providers, MCP servers, control service, permissions, memory, web UI, remote access, update settings or profiles unless you set trust_project_config = true. Cloning a repository is never enough to make malac run its commands. See Security model.

Your data stays local. Transcripts are JSONL files in ~/.malac/sessions and memories are Markdown files, both readable and deletable. Anything you paste into a prompt, including an API key, ends up in that session's transcript. Prefer api_key_env or malac provider add --api-key-stdin.

Desktop control needs macOS permissions. macOS grants Screen Recording and Accessibility to the app that started malac-control, usually your terminal. Grant both to the terminal you use, or run malac-control serve in one that has them; malac connects to it automatically.

Browsers run in their own profiles. Each malac browser profile is a separate Chrome data directory under ~/.malac/browser. Chrome does not allow remote control of your everyday profile, so log in once inside the malac profile, or use clone_from to copy an existing profile.

The daemon is local unless you say otherwise. Its master token works only on its own machine. With remote access on (web.remote = true or malac daemon start --remote), other devices pair for tokens of their own and connect over plain HTTP unless a tunnel or proxy adds TLS; use SSH, Tailscale or a TLS proxy outside trusted networks. A paired device can do everything you can, so revoke lost ones. See Remote access.

Plugins are code. Hooks and MCP servers from plugins run on your machine with your permissions once you approve them. Read what malac plugin show lists before approving, as you would before running a script from the internet. See Plugins and marketplaces.

Updating is safe while agents run. Binaries are replaced with an atomic rename. Running sessions and the daemon keep their version until you restart them (malac daemon restart).

The daemon keeps running. Agents started from the terminal UI, the line mode, the web UI or VS Code continue after you close them, until they finish; the daemon itself exits after two idle hours (daemon.idle_minutes). It keeps the environment it was started with, so restart it after changing API key variables.

Models without vision get screenshots described by vision_model when you mark them vision = false.

Inside tmux or byobu, mouse clicks reach the terminal UI only with set -g mouse on, and copying needs set -g set-clipboard on. Everything also works from the keyboard.

Alt shortcuts on macOS need the Option key to send Meta (a setting in Terminal.app and iTerm2), and the function keys may need Fn. See Terminal notes.

Questions

Can the agents run on a server while I use my laptop?

Yes. Run malac on the server, pair the laptop with malac remote pair there and malac remote add here, then malac -C <name>. Close the laptop and the agents keep working on the server. The tutorial walks through it over SSH.

My laptop slept and the agent stopped.

The daemon keeps the machine awake while agents or jobs run, but closing a MacBook's lid still puts it to sleep, unless it runs in clamshell mode. Leave the lid open, or run the agents on a machine that stays on. See Keeping the machine awake.

Does malac read my CLAUDE.md or Cursor rules?

Yes, along with AGENTS.md, GEMINI.md, Copilot's, Windsurf's and Cline's files; a CLAUDE.md that only repeats AGENTS.md is read once. /context shows what was loaded. See Project context.

How do I stop everything?

malac daemon stop stops the daemon, unless agents or jobs are running; malac daemon stop --force stops them too. Workspaces and transcripts stay saved, and malac starts the daemon again next time.

The terminal says the daemon runs an older version.

You updated malac while the daemon was running. It keeps its version until it restarts: run malac daemon restart when nothing is running, or click the status line note in the terminal UI.

Which models work best?

Any model with reliable tool calling. malac sends the same tools to every model, so stronger models make better decisions about when to read, edit, test and delegate. Use a cheaper small_model for compaction summaries, and cheaper models for mechanical subagent work.

Does malac work without an internet connection?

Yes, with a local model and local embeddings. Update checks fail quietly when offline; turn them off with update.check = false.

Why does it say no model configured?

No provider has a usable model. Set ANTHROPIC_API_KEY or OPENAI_API_KEY, or run malac provider add … --set-default. See Configure a provider.

My prompt starts with "web" (or "memory", "config", …) and malac ran a subcommand.

A prompt is only taken as a subcommand when it parses as one. malac web scraper for the docs is a prompt, but malac web --open is the web UI. To be sure, write malac -- <prompt>.

Calls are denied and nobody asked me.

malac had no terminal to ask: stdin was not a terminal (a pipe, CI, an IDE task) and no web UI was attached. Use -y with deny rules, or allow rules for exactly what the job needs. See Running malac unattended.

A command was allowed in the past, why does it ask again?

"Always" lasts for one session. Make it permanent with an allow rule in ~/.malac/config.toml, or ask malac: "allow cargo commands without asking".

Where are my settings?

malac config path    # where the files are
malac config show    # the merged result, defaults included

Why did malac ignore a key in my project's .malac/config.toml?

The key is one a project may not set (mode, providers, mcp, control, permissions, memory, web, update). Move it to ~/.malac/config.toml. The warning names the key and the file.

How do I see what a subagent did?

In the terminal UI, F3 (or /agents) opens the agents view, and every subagent card opens its transcript; in the line mode, /agents prints the tree; in the web UI, click it in the agent tree; afterwards, malac sessions show <id> prints a session with all of its subagents.

The conversation got long. Do I need to start over?

No. malac compacts automatically at 80% of the model's context window, and /compact does it on demand. Set context_window for your model if it is not 200,000 tokens.

How do I uninstall malac?

Delete the two binaries (malac and malac-control, in ~/.local/bin by default, or brew uninstall malac), and ~/.malac if you want to remove configuration, sessions, memories and browser profiles too. Project files live in each repository's .malac/ directory.