Usage

Macaron Artifacts runs Claude Code, Codex, OpenCode, pi, Hermes, and OpenClaw in the same local WebUI. Each conversation selects its own harness, workspace, and optional model.

Install

Macaron Artifacts requires Node.js 22.19 or newer. Claude Code and pi use bundled SDKs; keep optional dependencies installed for Claude's native runtime. Codex and OpenCode v1/v2 require the corresponding native CLI. Provider authentication is configured separately. pi reads ~/.pi/agent; Hermes can use a local CLI or a configured gateway, while OpenClaw uses the bundled Gateway Client with an external gateway. Availability does not verify provider credentials or gateway connectivity.

Run it directly, or install it globally. Latest is the npm release; Nightly is the main build this page was deployed from.

bunx macaron-artifacts
# or
npm install -g macaron-artifacts && macaron-artifacts

bunx https://pkg.pr.new/macaron-artifacts@1ea972c

npm install -g https://pkg.pr.new/macaron-artifacts@1ea972c

Open http://127.0.0.1:43860.

Password protection and remote access

Use MACARON_PASSWORD or --password on the machine running your coding agents. To read a password without echoing it or adding it to shell history:

printf 'Artifacts password: '
read -r -s MACARON_PASSWORD
printf '\n'
export MACARON_PASSWORD
macaron-artifacts

You can also run macaron-artifacts --password "$MACARON_PASSWORD". CLI passwords can appear in shell history and process arguments.

For an SSH machine, run this command on your computer, then open http://127.0.0.1:43860 and enter the password:

ssh -N -L 43860:127.0.0.1:43860 user@host

The agents, their credentials, and workspace files stay on the server. A configured password applies to loopback access too. Without one, the default local-only launch behaves as before. Login lasts 24 hours in an HttpOnly, SameSite=Strict cookie; signing out or restarting the server invalidates it. The shared password grants access to the whole service, including all conversations, workspaces, and Profile settings.

For direct access through an HTTPS reverse proxy, pass --public-origin https://artifacts.example.com or set MACARON_PUBLIC_ORIGIN=https://artifacts.example.com, proxy to 127.0.0.1:43860, and preserve the browser's Host header. The server ignores X-Forwarded-* headers for trust and uses Secure cookies for that HTTPS origin. If the backend needs to listen on a network interface, use --host 0.0.0.0 or MACARON_HOST. A non-loopback listen address or public origin requires a non-empty password. Use HTTPS or SSH forwarding to encrypt the connection; password protection alone does not encrypt HTTP.

Connect from the website

Run macaron-artifacts --pair on the machine that has your coding agents installed. On the connect page, enter http://127.0.0.1:43860 and the one-time code printed by the command. The code expires after ten minutes and is consumed once; credentials stay in the browser tab and the agent machine.

For an SSH machine, keep the server bound to loopback and forward it to your computer:

ssh -N -L 43860:127.0.0.1:43860 user@host

Then use the forwarded http://127.0.0.1:43860 address in the connect form. The website never needs direct network access to the remote machine.

Pairing is a separate authorization method: an origin-bound Bearer grant allows the paired WebUI to use the service without a password cookie. It cannot access password endpoints or manage other pairing grants. When password protection is enabled, the same-origin WebUI must log in before managing pairing codes or connections.

Start a conversation

1. Select New conversation and enter your workspace directory.
2. Choose Claude Code, Codex, OpenCode, pi, Hermes, or OpenClaw. Leave the model field empty to use that harness's default. OpenCode and pi accept an optional provider/model override.
3. Send a message. Text, reasoning, and supported tool events stream into the conversation.
4. Respond to approval requests in the chat when they appear. For pi, the host gates tool execution through its SDK hook.

Switching conversations keeps background turns running. Refreshing reconnects to an active turn; Stop explicitly cancels it. Titles and follow-up suggestions arrive independently after the main response, so they do not hold the composer open.

Streaming follows each harness's native events. OpenCode exposes text/reasoning deltas and tool input snapshots. pi also exposes raw tool argument deltas; its command output arrives as cumulative updates.

OpenCode's native question dialogs and pi prompts that require a terminal UI are not supported here. Hermes and OpenClaw gateway prompts that require an external client are likewise outside the WebUI; tool execution approvals appear in the conversation.

Generated UI

• An inline ui4a/tsx fenced module renders inside its assistant message as the source arrives.
• A file at .artifacts/canvases/<name>.ui4a.tsx opens in Canvas. Relative TypeScript, TSX, and JSON imports resolve inside .artifacts.
• The small $ui4a/ui component library shares the app's theme. Separate $ui4a/chat, $ui4a/state, and $ui4a/fs modules provide scoped host capabilities.
• Choose a paired Shiki theme family from the sidebar; its light or dark variant follows the site appearance, and both syntax highlighting and interface colors follow it.

Workspace files remain in the selected directory. Deleting a conversation does not delete those files. Existing native session-history migration and attachments are not included in this version.

Configuration

macaron-artifacts --port 43860 --data-dir /path/to/session-data
macaron-artifacts --help

CLI options override their environment variables.

For a custom Claude gateway, launch with the same ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY environment as your CLI. Environment variables set only inside a shell alias do not reach a separately launched app.

The API binds to loopback by default and accepts same-origin browser requests. A configured password protects the API even on loopback. Generated React runs in the host page; use it with trusted code.

Update

Run or install the same macaron-artifacts package URL with the SHA of a newer successful build. App conversations remain in the configured data directory.

Feedback

github.com/MindLab-Research/macaron-artifacts/issues