Available Tools
Mibyan ships with a broad built-in tool registry covering web search, browser automation, terminal execution, file editing, memory, delegation, scheduled tasks, Home Assistant, and more.Honcho cross-session memory is available as a memory provider plugin (
plugins/memory/honcho/), not as a built-in toolset. See Plugins for installation.
For the authoritative code-derived registry, see Built-in Tools Reference and Toolsets Reference.
Using Toolsets
web, search, terminal, file, browser, vision, image_gen, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, homeassistant, messaging, spotify, discord, discord_admin, debugging, and safe.
See Toolsets Reference for the full set, including platform presets such as mibyan-cli, mibyan-telegram, and dynamic MCP toolsets like mcp-<server>.
Tool result annotations
A few tool behaviors are worth knowing when you read agent transcripts:- Signal deaths are explained. When a terminal command is killed by a signal, the result carries a human-readable note instead of a bare numeric code — e.g. exit
-9/137becomes “terminated by signal 9: SIGKILL — often the kernel OOM killer on memory exhaustion, or an explicit kill -9”, and segfaults, aborts, SIGTERM, broken pipes, and CPU/file-size limits are labeled the same way. Negative codes (subprocess semantics) are stated definitively; the shell’s128+signumconvention is hedged with “usually” since an application can legitimately exit with those codes. - UTF-16 text files are transcoded, not refused.
read_filedetects UTF-16 (BOM or byte-pattern heuristic, either endianness — common for Windows Notepad files and PowerShell>redirects) and transcodes it to UTF-8 for display instead of flagging the file as binary. The result includes a hint disclosing the conversion; edits viapatch/write_filere-encode as UTF-8. Files over 10 MB and genuinely binary files still get the binary-file refusal.
Terminal Backends
The terminal tool can execute commands in different environments:Configuration
Shell startup files and non-interactive commands
Agent terminal calls run your shell non-interactively — there is no TTY and no human at the prompt. Heavy or interactive shell initialisation that you never notice in a normal terminal can break or badly slow every command the agent runs:- Slow init (
nvm, version managers, network-touching prompts): the classicnvm.shsourcing adds noticeable latency to every shell start, and the agent starts many shells. Multi-second rc files turn a quickgit statusinto a timeout risk. - TTY-expecting blocks: anything in
.bashrc/.zshrcthat prompts, runstmux/screenattach, callsread, or prints a menu will hang a non-interactive shell — the command appears to run forever and then times out. - Unconditional output: rc files that
echobanners pollute every command’s output the agent has to parse.
.bashrc — return early when the shell is non-interactive, and keep anything heavy or interactive below it:
.zprofile and interactive-only setup in .zshrc; keep .zshenv minimal, since it runs for every shell including non-interactive ones. If the agent genuinely needs a tool that only your rc file puts on PATH, export the PATH change above the guard (path exports are cheap) or symlink the binary into ~/.local/bin.
If agent terminal commands hang or time out immediately after working in your own terminal, your shell init is the first suspect.
Docker Backend
docker run -d ... sleep infinity) and routes every terminal, file, and execute_code call through docker exec into that same container. Working-directory changes, installed packages, environment tweaks, and files written to /workspace all carry over from one tool call to the next, across /new, /reset, and delegate_task subagents, for the lifetime of the Mibyan process. The container is stopped and removed on shutdown.
This means the Docker backend behaves like a persistent sandbox VM, not a fresh container per command. If you pip install foo once, it’s there for the rest of the session. If you cd /workspace/project, subsequent ls calls see that directory. See Configuration → Docker Backend for the full lifecycle details and the container_persistent flag that controls whether /workspace and /root survive across Mibyan restarts.
SSH Backend
Recommended for security — agent can’t modify its own code:Singularity/Apptainer
Modal (Serverless Cloud)
Vercel Sandbox
VERCEL_TOKEN, VERCEL_PROJECT_ID, and VERCEL_TEAM_ID. This access-token setup is the supported path for deployments and normal long-running Mibyan processes on Render, Railway, Docker, and similar hosts. Fresh sandboxes start from terminal.vercel_image (default vercel/sandbox/universal:latest; the legacy vercel_runtime presets are deprecated by Vercel); Mibyan defaults to /vercel/sandbox as the remote workspace root.
For one-off local development, Mibyan also accepts short-lived Vercel OIDC tokens:
container_persistent: true, Mibyan uses Vercel snapshots to preserve filesystem state across sandbox recreation for the same task. This can include Mibyan-synced credentials, skills, and cache files inside the sandbox. Snapshots do not preserve live processes, PID space, or the same live sandbox identity.
Background terminal commands use Mibyan’ generic non-local process flow: spawn, poll, wait, log, and kill work through the normal process tool while the sandbox is alive, but Mibyan does not provide native Vercel detached-process recovery after cleanup or restart.
Leave container_disk unset or at the shared default 51200; custom disk sizing is unsupported for Vercel Sandbox and will fail diagnostics/backend creation.
Container Resources
Configure CPU, memory, disk, and persistence for all container backends:container_persistent: true, installed packages, files, and config survive across sessions.
Container Security
All container backends run with security hardening:- Read-only root filesystem (Docker)
- All Linux capabilities dropped
- No privilege escalation
- PID limits (256 processes)
- Full namespace isolation
- Persistent workspace via volumes, not writable root layer
terminal.docker_forward_env, but forwarded variables are visible to commands inside the container and should be treated as exposed to that session.
Background Process Management
Start background processes and manage them:pty=true) enables interactive CLI tools like Codex and Claude Code.
Completed background commands retain their exit status and captured output in the
active profile. Resume the conversation that launched the command (or its
compressed continuation), then use the original session_id with
process(action="log") for output and process(action="poll") for exit status.
Unrelated conversations and requests without a bound owning session cannot read
retained receipts, even with an exact process handle. process(action="list")
also includes retained results for the current task or conversation.
Mibyan keeps the newest 64 completed results, for up to 7 days after
completion, under logs/process-results/ in the profile’s Mibyan home. Each
receipt contains at most the existing rolling 200,000-character output tail,
with terminal secret-redaction rules always applied, even when live-output
redaction is disabled. Receipts expire on subsequent
result reads or writes. Recovery does not rerun commands or replay completion
notifications. This preserves work that finished while the parent was alive;
it does not keep unfinished children alive after a timeout or crash.
Sudo Support
On an interactive parent session, supported sudo commands use the masked password prompt (cached for the session). This includes literal absolute or quoted executable paths andenv prefixes with ordinary options and assignments, such as env -u UNUSED /usr/bin/sudo id. Passwordless sudo does not need a prompt. You can also configure SUDO_PASSWORD in your profile’s .env file on the agent machine.
Shell payloads such as bash -c 'sudo id', env -S split strings, dynamic executable paths, and unrecognized env options are not interpreted by the password rewriter. Invoke sudo directly when you need the interactive prompt. This handling does not change approval rules or the guard against agent-supplied sudo passwords.
Delegated subagents cannot open a password prompt: their concurrent work does not have a serialized human password channel. Run the command in the parent session instead, or provision SUDO_PASSWORD locally. Messaging/headless sessions do not have a secure password reply channel; never send passwords in chat.