Installing Task Monki

Date: 2026-08-26

Task Monki is distributed through GitHub Releases. The app supports macOS, Windows, and Linux.

Requirements#

Install these before using Task Monki:

• Git
• at least one supported coding-agent runtime, installed and authenticated:
  • Codex CLI with a compatible App Server;
  • OpenCode with the native opencode serve API and one or more configured model providers;
  • an ACP profile: Grok Build, Cursor Agent, or claude-agent-acp;
• Optional: GitHub CLI, installed and authenticated, for branch publishing and draft pull-request features
• Optional: Docker Desktop for managed-data and existing-Compose previews. Compose previews require a Compose CLI that exposes docker compose config --no-env-resolution; Task Monki feature-probes this and refuses the preview before mutation when it is unavailable.

See the Preview Guide for recipe setup, private-input platform requirements, supported native and Compose behavior, and current limitations.

Task Monki does not bundle Git, agent runtimes, or GitHub CLI. Packaged desktop apps probe each registered runtime independently. One unavailable runtime does not prevent another from working. Authentication and upstream model-provider configuration remain owned by the selected runtime.

Settings provides custom executable paths for Git, GitHub CLI, Codex CLI, OpenCode, and every registered ACP runtime. Use Auto-detect to return a saved path to environment-override and then PATH-based discovery. On macOS, the packaged app also checks common user CLI locations because apps opened from Finder do not receive the interactive shell PATH.

Environment variables are supported as debug overrides and take precedence over saved Settings values:

TASK_MANAGER_GIT_PATH=/path/to/git
TASK_MONKI_CODEX_BIN=/path/to/codex
TASK_MONKI_OPENCODE_BIN=/path/to/opencode
TASK_MONKI_GROK_ACP_BIN=/path/to/grok
TASK_MONKI_CURSOR_AGENT_ACP_BIN=/path/to/cursor-agent
TASK_MONKI_CLAUDE_AGENT_ACP_BIN=/path/to/claude-agent-acp
TASK_MANAGER_GH_PATH=/path/to/gh

Git and one ready agent runtime are required to run a task. GitHub CLI is optional; GitHub delivery features report it as unavailable when gh cannot be resolved.

Codex and OpenCode are native server integrations. ACP profiles remain distinct integrations, not interchangeable model-provider shims. The browser development server only enables runtimes that attest its stronger isolation boundary; use the packaged Electron app for OpenCode and current ACP profiles.

Provider setup and readiness#

Runtime discovery is intentionally staged. Finding an executable does not prove that it is the correct agent, that its protocol is compatible, or that the current provider account can create a session. Settings and the New Task flow show these states separately:

Provider-owned authentication should be completed with the provider's own CLI; Task Monki neither collects credentials nor runs login flows. Runtime details show bounded, redacted diagnostics, the selected executable, its native launch form, and rejected candidates. For ACP runtimes, every candidate—including a custom path—must pass both a version command and a non-mutating, profile-owned launch-contract probe. A successful --version alone is not accepted as ACP support.

Each provider can be enabled independently in Settings. A disabled provider is removed from task and model choices and its agent process remains stopped. Executable paths can still be saved while disabled, but take effect only when the provider is enabled. Providers with active or recovery-required work must finish or be explicitly recovered before they can be disabled.

After an ACP session is attached, the task's Provider inspector shows only the schema-selected native model, mode, and configuration controls advertised by that session. Model catalogs remain provider-specific; changing a session model uses that agent's native model operation rather than translating it into a generic model name. Controls are available only while the session is idle and are disabled for active or recovery-required work.

Cursor offers Ask for approval, Auto-accept edits, and Full access through its native ACP permission requests; Claude Agent ACP remains Ask-for-approval only. Full access automatically selects only an exact allow_once option. A provider-remembered choice such as Cursor's allow_always always requires explicit confirmation, retains the provider's exact label and ID, and may outlive the ACP process because the provider owns its scope and lifetime. The provider process still runs outside a Task Monki filesystem or network sandbox, so these modes govern Task Monki's responses to reported requests rather than confining unreported provider activity.

Grok also offers Ask for approval, Auto-accept edits, and Full access. Task Monki starts its managed ACP process with Grok's process-scoped --permission-mode default, then answers only the exact permission options Grok sends. Grok's global --allow/--deny rules remain provider-owned; Task Monki does not rewrite global or repository configuration. The current Grok ACP may offer only one-time allow and reject choices for an individual request, in which case Task Monki does not invent a remembered or scoped choice.

Codex is different: it enforces and attests its managed sandbox. Restricted permits only worktree writes with network and exceptions disabled; Ask for approval and Approve for me review eligible sandbox exceptions; Full access intentionally removes the sandbox.

OpenCode likewise has no attested process sandbox. Its two presets both report full process access: Ask for approval gates native mutation and external- directory tools, while Full access uses approvalPolicy: never. Provider, plugin, MCP, and process-level network activity remains provider-controlled in both modes.

Provider environment contracts#

Agent children do not inherit arbitrary host variables. They start with Task Monki's minimal process environment plus a versioned, exact provider contract:

The allowlists use exact names—never provider-looking prefixes—so unrelated application secrets remain unavailable to runtime children. File-path and inline-config values that may lead to credentials are treated as sensitive in diagnostics. OpenCode custom providers that need another environment variable must store authentication through OpenCode's own auth/config mechanisms rather than relying on Task Monki to forward the entire host environment.

The contracts follow the providers' documented configuration surfaces: OpenCode CLI and config, Claude gateway/cloud settings, and the AWS SDK environment reference.

Downloads#

Use the installer for your platform:

macOS#

The macOS app uses Developer ID signing, Hardened Runtime, Apple notarization, and a stapled ticket.

1. Open the DMG.
2. Drag Task Monki.app to Applications.
3. Open Task Monki from Applications.

Do not remove quarantine attributes to bypass a trust failure. Delete a blocked copy and download it again from GitHub Releases. Report the version and Gatekeeper message if the new copy is also blocked.

Windows#

The first Windows release is unsigned. Windows can show SmartScreen or Unknown Publisher. To continue, select More info, then Run anyway. This warning remains until Task Monki adds Authenticode signing.

Run the NSIS installer and select the install directory. Task Monki installs for the current user by default.

Linux#

Make the AppImage executable, then launch that file:

chmod +x Task-Monki-<version>-linux-x86_64.AppImage
./Task-Monki-<version>-linux-x86_64.AppImage

Keep the AppImage in a location that your user can write. The updater replaces this file after an update download. Task Monki does not publish a DEB package.

Updating#

Installed desktop builds check GitHub Releases when Task Monki starts. They check again every six hours while the app is open. Task Monki does not download an update until you select Download.

You can also open Settings → Updates and select Check now. When a newer release exists, the left sidebar shows the update state. Select the notice to download the update. Select Restart to update when the download completes.

The Install on quit setting is on by default. With this option on, a downloaded update installs when Task Monki closes normally. It does not install during an operating-system shutdown. Turn the option off if you want to use only Restart to update.

Windows updates remain unsigned for now. The updater accepts the unsigned NSIS package by design. macOS updates still require the app's valid Developer ID signature. Every platform update also uses the digest in its GitHub update metadata.

If an update fails, select the sidebar notice or the Settings action to retry. You can always install a newer release manually from GitHub Releases.

The stable package identity preserves the same app data directory during a normal upgrade on one platform.

Task Monki stores its structured durable data in one versioned SQLite database. This data includes settings, tasks, evidence, runtime records, Discourse, and Preview control state. The database is under the platform application data directory. Large immutable attachments, artifacts, encrypted Preview-private values, and managed Design Git repositories remain files. Database records own their reachability and integrity metadata.

Startup rejects an unidentified, newer, or corrupt database and any invalid managed file required during initialization. Other managed bytes are verified before use and fail closed. Do not delete individual persistence files. The core recovery API can restore a verified backup or quarantine a closed storage root. The desktop UI does not expose these operations. Startup does not run them automatically.

First Launch#

Task Monki opens without a selected repository in packaged builds. Add a local Git repository from the repository menu before creating tasks. Use only repositories you can recover, because Task Monki creates worktrees, commits, branches, and optional draft pull requests when you explicitly ask it to.