Linzumi CLI

▓▓╗     ▓▓╗▓▓▓╗   ▓▓╗▓▓▓▓▓▓▓╗▓▓╗   ▓▓╗▓▓▓╗   ▓▓▓╗▓▓╗
▓▓║     ▓▓║▓▓▓▓╗  ▓▓║╚══▓▓▓╔╝▓▓║   ▓▓║▓▓▓▓╗ ▓▓▓▓║▓▓║
▓▓║     ▓▓║▓▓╔▓▓╗ ▓▓║  ▓▓▓╔╝ ▓▓║   ▓▓║▓▓╔▓▓▓▓╔▓▓║▓▓║
▓▓║     ▓▓║▓▓║╚▓▓╗▓▓║ ▓▓▓╔╝  ▓▓║   ▓▓║▓▓║╚▓▓╔╝▓▓║▓▓║
▓▓▓▓▓▓▓░░░░░░░░╚▓▓▓▓║▓▓▓▓▓▓▓╗╚▓▓▓▓▓▓╔╝░░░░░░░░▓▓║▓▓║
╚═══▒▒▒@@@@@@@@▒▒═══╝╚══════╝ ╚════▒▒▒@@@@@@@@▒▒╝╚═╝
 ▒@@@@@@@@@@@@@@@@▒             ▒@@@@@@@@@@@@@@@@▒
@@@@@@@@@@@@@@@@@@@@@           @@@@@@@@@@@@@@@@@@@@@
   @@@@@@@@@@@@@@@                 @@@@@@@@@@@@@@@
          ║║                             ║║
          ║║                             ║║
          ║║        ()-().----.          ║║
          ║║         \"/` ___  ;_________║║_.'
          ║║          ` ^^   ^^          ║║
──────────╨╨─────────────··────··────────╨╨──────────────
          your agent, your laptop, coding live

Copy this into your terminal:

codex --ask-for-approval never --sandbox danger-full-access -- 'Get me up and running with Linzumi from https://linzumi.com/agents.md. Read it with curl.'

That's the launch path: the first Codex is only the bootstrapper. It opens the agent instructions, confirms your email and workspace details, asks you for the emailed code when it arrives, creates /tmp/hello_linzumi, starts that hot-reload app on your computer, creates the shared support channel, starts a Linzumi Codex session in a work thread, and opens the browser editor pointed at the demo app.

Terms:

• Bootstrapper Codex: the outer Codex started by the pasted command. It sets up Linzumi and local processes, but does not edit the demo app.
• Linzumi Commander: the long-running local bridge started with linzumi commander; it owns the secure tunnel, trusted folder, browser editor, and inner Codex launch.
• Linzumi Codex session: the inner agent running inside the Linzumi thread; it edits /tmp/hello_linzumi and posts progress.
• Human: the workspace owner who opens the one-time login link and watches the work in #general and #linzumi-support.

The snippet uses automatic command approval and full local process access because the bootstrapper must start a real Linzumi Commander and browser editor on this computer. It is intentionally not the dangerous sandbox-bypass mode.

Today, your AI coding agent has two homes, both bad.

It can run alone in your terminal, where nobody — your teammate, your eng lead, your future self at 2am — can see what it's doing or help when it gets stuck.

Or it can run in someone else's sandbox VM, where "works for the agent" rarely means "works on your laptop." You merge, pull, run the test suite, and find out at 4pm.

Linzumi gives it a third home: your real laptop, in a thread your team can watch live. Real processes, real env vars, real dotfiles, real teamwork. Diffs land in chat as the agent makes them. Your reviewer opens a browser VS Code pointed at your folder and has an opinion before the agent's even finished. You approve from your phone on the way to lunch.

In three minutes from now you'll have it working end to end.

What you'll have in three minutes

• An AI coding agent running on your real laptop, editing the generated Hello Linzumi app in a thread your team can read along with.
• A browser VS Code editor pointed at /tmp/hello_linzumi, share-able by link with no clone and no deploy.
• A tunneled local preview of the app running on your computer with hot reload.
• A private support channel with the Linzumi team, in case anything goes sideways.

One pasted command. No cloud VM. The editor, agent, and dev server stay on your laptop the whole time.

Manual Runner Setup

The agent-first command above is the launch path. Use this manual path when you want to connect your laptop yourself before starting work from the browser.

You'll need Node.js 20+, the Codex CLI, and a Chromium-based browser (Chrome, Edge, Arc, or Brave). Safari mostly works; live collaboration is smoother in Chromium.

npm install -g @linzumi/cli@latest
linzumi start ~/code/my-app

Here's what the next 30 seconds look like:

1. Your browser opens to Linzumi.
2. Sign in (or sign up — one click).
3. Linzumi asks if it can connect to this computer. Click allow.
4. Your laptop appears as a runner in your workspace, and ~/code/my-app is added to your trusted-paths list automatically.
5. Type something in chat — "Explain this project and tell me how to run it" — and Linzumi Codex picks it up on your machine.

That's it for manual setup. The rest of this README is detail.

Agent-first launch path

That one prompt is the launch path. The canonical agent instructions are hosted at https://linzumi.com/agents.md; https://linzumi.com/skills.md stays available for compatibility. The bootstrap agent will confirm your email and workspace choice up front, ask for the emailed code after signup sends it, say hello to @sean in the shared support channel, generate /tmp/hello_linzumi, start its hot-reload Node server, start the Commander for that folder, start a Linzumi Codex session in a work thread, and open the browser editor. The Linzumi Codex session then adds confetti to the demo page while you watch. Workspace names are plain display names from 2 to 100 characters; Linzumi generates the URL-safe workspace slug.

Under the hood, the npm package exposes these commands for the bootstrap agent to run. They are not extra human setup steps after the one pasted Codex command.

npx -y @linzumi/cli@latest signup --email [email protected] --workspace-name "Alice's Linzumi" --agent-name BuildBot
npx -y @linzumi/cli@latest claim --pending <pending_id> --code <XXXX-XXXX>
npx -y @linzumi/cli@latest channel post <support_channel_id> "Hello @sean, starting this launch run."
npx -y @linzumi/cli@latest thread new "Hello Linzumi confetti" --message "Preparing the Hello Linzumi demo. Next I will generate /tmp/hello_linzumi, start its hot-reload server bound to 0.0.0.0 on port 8787, and ask Linzumi Codex to add confetti when the page loads."
commander_id="hello-linzumi-commander-${thread_id%%-*}"
npx -y @linzumi/cli@latest init-hello-linzumi-demo-app --parent-dir /tmp --name hello_linzumi --host 0.0.0.0 --port 8787 --reset --json
project_dir="$(cd /tmp/hello_linzumi && pwd -P)"
(cd "$project_dir" && npm run dev > "$project_dir/dev.log" 2>&1 &)
npx -y @linzumi/cli@latest commander "$project_dir" \
  --runner-id "$commander_id" \
  --allowed-cwd "$project_dir" \
  --forward-port 8787 \
  --sandbox danger-full-access \
  --approval-policy never

The agent-owned Commander reads ~/.linzumi/agent-token.json, uses the workspace/channel scope from the approval flow, trusts only the selected folder, marks that same folder trusted in Codex's normal project config so Codex does not stop for an interactive trust prompt, advertises the explicit preview port, and listens only to the approving human unless --listen-user is explicitly passed. Use a unique Commander id per launch thread; Linzumi stores trusted-folder config per Commander id, so reusing an old fixed id can pick up stale allowed-cwd config. The bootstrap agent waits for Runner connected: before starting Codex in the Linzumi thread.

By default, the Commander downloads the Linzumi-approved code-server runtime for your platform and verifies its checksum before enabling the browser editor. Linux editor launches are wrapped with bubblewrap (bwrap) for filesystem confinement.

linzumi claim also prints workspace_name, workspace_id, and login_url. That one-time link logs the human into #general in their own selected workspace. The claim also provisions #linzumi-support, a shared channel connected to Linzumi's workspace so our team can see setup issues from our side; the bootstrap agent posts a hello there with the printed support_channel_id. Keep demo work in task threads; use the support channel when signup, Commander, preview, or browser-editor setup gets stuck.

Once the Commander is online, the bootstrap agent can ask Linzumi to start Codex and open the browser editor for the same thread and folder:

npx -y @linzumi/cli@latest codex start <thread_id> \
  --runner "$commander_id" \
  --cwd "$project_dir" \
  --work-description "Work only in the canonical Hello Linzumi project directory printed by pwd -P for /tmp/hello_linzumi. Add tasteful confetti when the Hello Linzumi page loads, keep the hot-reload app working on port 8787, and post the exact files changed."

npx -y @linzumi/cli@latest editor open <thread_id> \
  --runner "$commander_id" \
  --cwd "$project_dir"

The launch target for this path is zero-to-Hello-Linzumi-editor+preview in under 3 minutes, measured from signup through browser VS Code readiness, forwarded preview readiness, and the first visible Codex edit.

What just happened

You now have:

• A runner. Your laptop, listed in the workspace, advertising /tmp/hello_linzumi and the explicit preview port.
• A workspace you can invite teammates into. They open the same browser app, see the same threads, and can start their own runners on their own machines.
• A private Linzumi support channel. We can see this channel; we cannot see your repo contents, your tokens, your Codex transcripts, your editor session, or your other threads. Stuck? Post there — we read it.
• A browser VS Code editor, opened against /tmp/hello_linzumi and ready for shared editing.

Three things to try first

1. Watch the demo change live. The Linzumi Codex session edits the generated page, and hot reload shows the change in the tunneled preview.
2. Make a real change without context-switching. The Codex session running in Linzumi edits files on your disk. Watch the diff land in chat, or jump into the browser editor and shape it yourself.
3. Show a teammate something on your screen. Open the browser editor or share your local dev server through a normal HTTPS link. No exposing localhost, no copy-pasting IPs, no "screenshare real quick."

Working as a team

This is what makes Linzumi different from running an AI coding agent alone in a terminal.

• Your laptops are always in sight. Every machine you've run linzumi start on shows up as a runner. From any channel, you can see how many of your runners are reachable right now and which ones are listening on that channel.

• Put Codex on the job from the channel. Pick an available runner and a trusted folder from the channel menu, type what Codex should work on, hit start. Linzumi attaches a fresh Codex to that runner with the folder and settings you picked.

• One Codex per thread. Once a Linzumi Codex session picks up a thread, it owns the thread — no second Codex can step in and trample the work. The lock holds for the life of the thread.

• Browse what your team's been up to. Open the runners dropdown to see, across every device, the most recently active threads with short AI-written summaries. Jump in and keep working.

• Chat with humans without waking Codex. Start a message with & and Codex won't see it. Side conversations live in the same thread without nudging the agent.

Trusted folders — the security model

Linzumi only runs Codex or opens the editor inside folders you've explicitly trusted. The trust list lives at ~/.linzumi/config.json.

linzumi paths list
linzumi paths add ~/code/my-app
linzumi paths remove ~/code/my-app

linzumi start <path> adds <path> to the trust list automatically on first use. linzumi connect uses the list as-is — or pass --allowed-cwd <paths> for a one-off comma-separated override.

There's no credential escalation: Linzumi only asks the runner to start Codex or the editor inside trusted folders. Those processes still run with your shell's operating-system privileges, so choose trusted folders intentionally. Every action is auditable from the thread.

When something looks wrong

• linzumi: command not found — your global npm bin folder isn't on PATH. Run npm prefix -g; add the printed path's bin folder to your shell.
• codex: command not found — install the Codex CLI, or pass --codex-bin <path> to linzumi start.
• Browser sign-in opens but never returns to the CLI. Your browser can't reach the address the CLI is listening on. Pass --oauth-callback-host <ip-or-host-your-browser-can-reach>.
• Browser editor never says it's ready. Rerun linzumi start and watch the console for the editor download step. The very first launch on a slow network can take a minute or two.
• Collaboration looks off in Safari. Switch to Chromium for now.
• Anything else. Post in your Linzumi support channel — we read it.

Pinning a version

npm install -g @linzumi/[email protected]
linzumi --version

Advanced

Most people never need anything in this section.

Lower-level connect

linzumi start is what you want almost every time. The lower-level form is useful when you already know your workspace and channel:

linzumi connect \
  --workspace <your-workspace> \
  --channel <your-channel> \
  --cwd ~/code/my-app

All the flags

--agent-token-file <path>   Agent token cache for `linzumi commander`
--oauth-callback-host <ip>  Sign-in callback host your browser can reach
--codex-bin <path>          Codex executable, default `codex`
--model <name>              Model requested for Codex sessions and labelled in Linzumi
--reasoning-effort <value>  Reasoning effort requested for Codex sessions and labelled in Linzumi
--fast                      Advertise this runner as low-latency in the workspace
--forward-port <ports>      Comma-separated local TCP ports Linzumi may share as authenticated previews
--allowed-cwd <paths>       Override ~/.linzumi/config.json with comma-separated trusted roots
--log-file <path>           JSONL runner event log

--runner-id, --auth-file, --code-server-bin, --codex-url, --launch-tui, --listen-user, --sandbox, --approval-policy, --stream-flush-ms, and --token are also accepted; linzumi --help shows them all with brief descriptions. They exist for multi-runner orchestration, custom Codex deployments, and CI scenarios — not for everyday use.