Platform Support

CoAutoResearch includes platform-specific paths for macOS, Linux and Windows. Installation guidance is not evidence that every backend and feature has been validated on every platform. Release notes should name the actual environments checked. Paper tools have additional requirements described in paper generation.

Required Tools

  • Node.js 20 or newer.

  • Python 3.10 or newer.

  • Git.

  • OpenAI Codex CLI for the default backend.

  • Claude Code CLI for the optional Claude backend.

The package CLI starts the local web UI with Python. It tries these Python commands in order:

  1. COAUTO_PYTHON or PYTHON, if set.

  2. python3

  3. python

  4. py -3

macOS And Linux

The simplest dashboard-first flow is:

co-auto-research ui

The CLI opens the UI in your browser after the server starts. If that is not available, open the printed URL manually, then create projects from the sidebar. For a scripted command-line flow:

co-auto-research init my-project
cd my-project
co-auto-research ui

For direct UI server use:

python3 ui/server.py --host 127.0.0.1 --port 8765

On POSIX, agent cleanup tracks the dedicated process group plus discoverable descendants that retain the per-run process marker, including ordinary setsid() descendants. This is cleanup attribution, not an OS sandbox: a same-user process that deliberately clears the marker needs cgroup, container, or platform-supervisor containment.

Windows Native

Windows native use should work with Node.js, Python 3, Git, and the selected agent CLI on the Windows PATH.

Keep native Windows projects on NTFS or ReFS. Runtime-session persistence pins each project ancestor with a no-follow Windows handle and requires the filesystem to expose a trustworthy 128-bit file identity. A filesystem or provider that returns the Windows “identity unavailable” sentinel is rejected instead of weakening link, replacement, or recovery checks.

PowerShell examples:

co-auto-research ui

The CLI opens the UI in your browser after the server starts. If that is not available, open the printed URL manually, then create projects from the sidebar. For a scripted command-line flow:

co-auto-research init my-project
cd my-project
co-auto-research ui

For direct UI server use:

py -3 ui/server.py --host 127.0.0.1 --port 8765

If py -3 is unavailable but python works, use:

python ui/server.py --host 127.0.0.1 --port 8765

Agent Executable Resolution

Codex remains the default backend. Choose Codex or Claude Code when creating a project, change the per-project default in Settings, or override one launch from the launch dialog. Set COAUTO_AGENT_BACKEND=claude or COAUTO_AGENT_BACKEND=codex only when the server environment should force one backend; while set, runtime launches use the forced backend even if the UI saves a different choice. Other values are ignored with a visible warning.

The UI resolves Codex in this order:

  1. COAUTO_CODEX, if set.

  2. CODEX_BIN, if set.

  3. On macOS, the newest installed CLI among codex on PATH and the Codex bundled with ChatGPT/Codex App.

  4. On other platforms, codex.cmd, codex.exe, codex.bat, then codex on PATH.

This matters on Windows because npm global binaries are commonly installed as .cmd shims. CoAutoResearch never interpolates agent arguments through cmd.exe: for an npm .cmd/.bat shim it invokes the sibling .ps1 shim with a PowerShell argument vector, or uses a native .exe. A batch shim without a sibling PowerShell shim is rejected; configure the native executable explicitly in that unusual case. If Codex fails to start, run:

codex --version
codex login status
Get-Command codex

Then start co-auto-research ui from the same PowerShell session. If needed, pin the executable explicitly:

$env:COAUTO_CODEX = (Get-Command codex).Source
co-auto-research ui

The UI resolves Claude Code similarly:

  1. COAUTO_CLAUDE, if set.

  2. CLAUDE_BIN, if set.

  3. claude.cmd, claude.exe, claude.bat, then claude on PATH.

claude --version
claude auth status
Get-Command claude
$env:COAUTO_AGENT_BACKEND = "claude"
$env:COAUTO_CLAUDE = (Get-Command claude).Source
co-auto-research ui

Before starting framing, autoresearch, chat, resume, or restart, the UI always checks the selected backend with --version. With the default providers it also checks codex login status or claude auth status. With API-key providers, readiness requires the relevant key instead: OPENAI_API_KEY for Codex or ANTHROPIC_API_KEY for Claude Code. A definitely missing or unauthenticated selected backend blocks startup with provider-specific instructions; the UI never silently falls back to the other backend.

API-Key Providers

Settings exposes provider choices per backend:

  • Codex: Use existing Codex CLI login or OpenAI API key.

  • Claude Code: Use existing Claude Code configuration, Anthropic API key, Z.AI GLM Coding Plan, or Custom Anthropic-compatible gateway.

Provider switching does not delete saved keys. Use the Clear action beside a key field when you want to remove it. Saved Codex keys are injected only into Codex runs; saved Claude keys and gateway credentials are injected only into Claude Code runs.

Claude Code With Anthropic-Compatible Gateways

Claude Code can run through an Anthropic-compatible gateway while CoAutoResearch still drives the normal Claude Code CLI. In Settings, choose Claude Code, then set Claude provider to Z.AI GLM Coding Plan or Custom Anthropic-compatible gateway. Z.AI GLM uses:

$env:ANTHROPIC_BASE_URL = "https://api.z.ai/api/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<your Z.AI key>"

The UI also detects gateway credentials in ~/.claude/settings.json and the project’s .claude/settings.local.json env blocks. A complete gateway config is treated as usable even if claude auth status reports that no Anthropic login is present.

Use https://api.z.ai/api/anthropic for Claude Code. Z.AI’s OpenAI-compatible endpoint, https://api.z.ai/api/coding/paas/v4, is for OpenAI-compatible clients and should not be used as Claude Code’s ANTHROPIC_BASE_URL.

Shell aliases and functions are not used when CoAutoResearch starts Claude Code; the UI launches a real executable with subprocess. If your GLM setup is a shell alias such as glm() { ... claude "$@"; }, move the env values into Claude settings or the UI Settings form, or set COAUTO_CLAUDE to a wrapper script file.

Codex also documents native Windows sandbox modes. If native sandbox setup is blocked by enterprise policy or admin restrictions, use WSL2.

Windows With WSL2

WSL2 is a good option when the research code, datasets, or build tools expect a Linux environment. In WSL2, use the macOS/Linux commands above.

For best filesystem performance, keep projects under the Linux home directory, for example:

mkdir -p ~/code
cd ~/code
co-auto-research init my-project

Avoid working from /mnt/c/... for large projects when possible.

File Attachment Behavior

The UI copies selected local files and folders into the project when you send. The originals stay unchanged. Each folder is limited to 50 MiB and must not contain symbolic links, Windows junctions, or other reparse points. No symlink permission is required. For larger materials, attach a selected subset or provide a source location for the agent to assess.

For projects created by older versions, Update project template also copies previously linked external folders into project snapshots. The same folder limits apply, and the source folders remain unchanged. If a copy cannot finish, its original link is retained so that the material is not lost.

Remote Servers

Remote use is OS-independent as long as the server has Node.js, Python 3, Git, and the selected agent CLI installed. Keep the UI bound to 127.0.0.1 and forward the port with SSH or an equivalent secure tunnel.

See Remote server setup.