Marline Help

1. Overview

Marline is a native desktop IDE for building agentic applications. It combines a visual node-graph planner, a project-scoped chat with Claude Code (or OpenAI / Anthropic), a real built-in terminal, and an OS-keychain-backed secret vault into a single Tauri desktop app that runs on Windows, macOS, and Linux.

What makes it different

The vault. Every other AI IDE lets the model read your .env file. Marline keeps API keys, database URLs, and OAuth tokens in the operating system's own keychain and shows the AI a presence flag only — never the value.

What you can do

• Plan an app visually with a node graph before you write a line of code.
• Generate the implementation with Claude Code, OpenAI, or Anthropic — with per-turn token & cost tracking.
• Store and manage credentials in the OS keychain without exposing them to the agent.
• Run your dev server in a real built-in terminal with auto-detected preview URLs.
• Review every AI edit as a git diff before it lands.

2. Getting started

Installing

1. Download the installer for your OS from the Marline download page.
2. On Windows, run the signed installer and follow the prompts.
3. On macOS, mount the .dmg, drag Marline into /Applications, then right-click → Open the first time to accept the developer signature.
4. On Linux, mark the .AppImage executable and double-click it, or use your distro's package if provided.

First launch

The first time Marline runs, it creates its local database and settings folder:

• Windows — %APPDATA%\dev.marline.app\
• macOS — ~/Library/Application Support/dev.marline.app/
• Linux — ~/.local/share/dev.marline.app/

Nothing is sent anywhere. No account is created. The app is fully usable offline; the network is only touched when you explicitly run an AI turn against a cloud provider you've configured.

3. Creating a project

Open File → New project. You'll be asked for three things:

• Name — what you want to call this project inside Marline.
• Working directory — the folder on disk where Marline will read and write files. This is what Claude Code sees when it uses Read / Edit / Write, and what the terminal runs its shell in.
• AI provider — Claude Code, OpenAI, Anthropic, or the built-in mock.

After creation, the project appears in the left rail and opens in a new tab. Every project has its own chat history, its own vault, its own flow graph — nothing is shared between projects except your global Settings.

Provider setup

• Claude Code — install the claude CLI from Anthropic and make sure claude --version works in a shell outside Marline.
• OpenAI — set OPENAI_API_KEY in the Environment tab.
• Anthropic — set ANTHROPIC_API_KEY in the Environment tab.
• Mock — no setup; it echoes your last message. Useful for smoke-testing the UI.

4. The Flow tab

The Flow tab is where you plan the app. Rather than chatting with the AI in a free-form window, you draw a graph of your intent. Each node holds either input (a paragraph you wrote, an attached image, a text file) or AI-generated output. Downstream nodes see everything upstream, so by the time you reach the Out node, every generation is grounded in the full context of the plan.

Working the canvas

• Drag from the palette on the left to add a node.
• Connect nodes by dragging from the bottom port of the source to the top port of the target.
• Ctrl+B on the selected node toggles bypass — the node's own output is excluded from downstream context, but its inputs still pass through to whatever it feeds.
• Selection marquee — click and drag on empty canvas to lasso-select multiple nodes.
• Delete removes the selected node(s).
• Scroll to zoom, drag empty canvas to pan.

The Out node

Every project graph has one Out node — Marline auto-places it the first time you open the graph. It aggregates every upstream node's output into a single Markdown handoff document. That handoff is what gets sent to the build session when you click Accept FlowState & Build. See section 7 for the transition to the build phase.

5. Node types

Marline ships with twelve node types. Sources produce content from user input; planning nodes ask an AI to write a specific chunk of the plan; composition nodes reshape upstream flow; the Out node is where everything converges.

Sources

Planning nodes

Composition

Terminal

6. AI Analyze

Running a node

Select a node and click AI Analyze in the properties panel. The node's status flips to generating, the static icon is replaced with an infinity loader animation, and the model streams its response directly into the node's output.

Clarifying questions

If the model needs more context to finish a node, it can respond with a set of clarifying questions instead of an answer. The node's status becomes awaiting_input and a form appears asking each question inline. Answer them and click Submit answers to re-run with the added context. Nothing is generated until the model has what it needs.

Cost tracking

Every AI turn shows token counts and estimated cost. Claude Code reports its cost directly from the CLI; OpenAI and Anthropic estimate from published rates and prefix the number with ≈ in the tooltip so you know it's an estimate.

7. Accept FlowState & Build

Select the Out node and you'll see two buttons in the properties panel:

• Preview handoff — opens the fully assembled Markdown document so you can review exactly what the build session will see.
• Accept FlowState & Build — freezes the graph, unlocks the Environment tab (Vault + Preflight-identified credentials), and hands the assembled Markdown to a Claude Code build session in the LiveDev tab.

Accepting is not one-way. If you want to iterate on the plan after seeing the build progress, unlock the Out node from the properties panel — the graph becomes editable again, and downstream tabs stay accessible for reference. The Out node's button will re-label to Rebuild with new changes once it detects that upstream content has drifted from what was last accepted.

8. The Vault & Preflight

The Vault is where every API key, database URL, and OAuth token for your project lives — and where Marline earns its "private-first" claim.

How storage works

Values live in the operating system's keychain:

• Windows — Credential Manager.
• macOS — Keychain.
• Linux — Secret Service (GNOME Keyring / KWallet).

The SQLite metadata mirror stores only:

• the credential name (e.g. STRIPE_SECRET_KEY);
• whether it's currently present (yes / no);
• an 8-character SHA-256 fingerprint of the value.

Values are never written to the SQLite database, log files, IPC messages, or agent contexts. The AI receives an object shaped like { STRIPE_SECRET_KEY: present } — never the string itself.

The Preflight-driven list

The Vault does not show a static catalog of every credential Marline has ever heard of. It shows the exact list your project's Preflight node identified — nothing more, nothing less. If Preflight didn't name it, it doesn't appear. If Preflight later re-identifies the manifest with a different set of services, the list updates.

Setting a value

Click Set value on a credential row, paste your secret, and click Store in keychain. The value moves straight to the OS keychain from that dialog and is dropped from memory as soon as it's stored. The value is never inspected, logged, or copied anywhere else.

Validation

For credentials with a known validation endpoint (OpenAI, Anthropic, GitHub, etc.), the Validate button pings the provider's API using your key. The outcome — ok, unauthorized, rate_limited — is stored with the metadata row. The response body itself is never stored.

Env file generation

Generate env files writes .env.local, .env.example, and .env.production.template into the project root, sourced from the current vault. .env.local is gitignored by default. If Claude Code needs to know which env var names your code should reference, it can Read these files — but the actual values only exist in the OS keychain and, briefly, in your generated .env.local.

Reset

9. The assistant panel

The right-hand chat is a general-purpose assistant scoped to the active project. It runs against whichever provider the project is configured for.

Streaming

All four providers stream text as the model produces it — you'll see the response appear character by character rather than in one blocking dump. Claude Code additionally streams tool-use events: you'll see collapsible cards for every Read, Edit, Write, MultiEdit, Glob, Grep, and LS call the agent runs, so you can follow along with what it's actually doing.

Attachments

Drag a file, image, or Markdown document into the composer, or paste an image straight from the clipboard. Images go to the model directly for vision-capable providers (OpenAI GPT-4o, Claude Code via its Read tool). Text files are inlined into the prompt as Markdown fences.

Slash commands

• /clear — wipe the conversation for this project. Also clears the Claude Code --resume session so the next turn starts fresh.
• /revert — roll back the last diff Claude produced. Runs git checkout -- . && git clean -fd in the project root. See section 12.

Token & cost display

Every assistant turn's footer shows total tokens and cost. Claude Code reports cost directly from the CLI. OpenAI and Anthropic estimate from published per-1M-token rates — the exact hover-tooltip breakdown marks these with ≈.

10. Multi-provider AI

Marline routes each project to one of four providers, chosen at project creation and changeable in Settings → Providers.

Switching provider mid-conversation is safe — the next turn runs on the new provider. The vault behaviour doesn't change when you switch; secrets are never sent to any provider.

11. Built-in terminal

The engine

Marline's terminal is xterm.js on the frontend and Rust's portable-pty on the backend. On Windows that means ConPTY — the native Win32 pseudo-console — and on macOS and Linux, real POSIX PTYs. Interactive terminal applications (htop, vim, git log's pager, REPLs) work exactly the way they do in your OS's native terminal.

The shell is launched as a direct child of the Rust process — no hidden Node runtime in the middle, no node-pty intermediary — so the memory footprint is minimal and startup is instant.

Opening one

Right-click a pane tab and choose New terminal, or split the current pane and drop a terminal into the new leaf. Every terminal is a real independent shell; closing its pane kills the shell.

Preview URL detection

Marline scans terminal output for http://localhost:PORT and http://127.0.0.1:PORT URLs. When your dev server prints one, it pops as a clickable pill in the assistant panel — click to open it in your OS browser.

12. Reviewing changes

When a Claude Code chat turn edits files, Marline runs git status and git diff HEAD in the project root and surfaces the results at the top of the chat as a diff card.

The diff card

If the project directory isn't a git repository, the diff card is skipped silently — but you'll still see the raw file changes on disk if you look at them yourself. If you'd like the safety net, run git init in the project root before your first Claude Code turn.

13. Templates & export

Flow templates

A template is a reusable slice of a Flow you can drop into any project. Select one or more nodes, click Save as template at the top of the palette, and give it a name. Templates are stored globally (not per-project) and appear in the Templates section of the palette from then on. Drag a saved template onto any project's canvas to instantiate a copy.

Project export

File → Export project writes a .zip containing the entire project working directory, the Flow graph, the vault metadata (never the values), and the chat history. Values do not leave the OS keychain — the archive is safe to send to a colleague or upload as a backup.

Project import

File → Import project unpacks a .zip into a fresh project. You'll need to re-enter any credentials — the OS keychain isn't portable across machines, so the vault list will show every envVar as empty until you populate it.

14. Mouse & keyboard

15. Troubleshooting

"Claude Code CLI was not found on PATH"

Marline couldn't spawn the claude command. Install the CLI from Anthropic's documentation and confirm claude --version works in a fresh terminal outside Marline, then restart Marline so it picks up the updated PATH.

"CHAT_PROVIDER_ERROR"

Usually a missing or invalid API key. Open the Environment tab, confirm the relevant envVar is set and shows set, and try Validate. If validation fails with unauthorized, the key itself is bad — regenerate it in the provider's dashboard and re-store it in the Vault.

AI Analyze is stuck on "generating"

Check the LiveDev tab for the underlying agent's log. If the provider is rate-limited, unreachable, or returned an error, the run will eventually fail. In the meantime, clicking Cancel on the node resets it to empty.

The preview URL pill isn't appearing

Only http://localhost:PORT and http://127.0.0.1:PORT are scanned. Custom hostnames, HTTPS, and remote URLs aren't detected. If your dev server binds to a hostname like myapp.test, the pill won't materialize — visit the URL manually from the terminal.

The graph is showing every wire the wrong colour

Wires colour by upstream node type. If a node's status shifts to bypassed, its outgoing wires desaturate to signal that the wire is present but the node's own output isn't contributing downstream — this is expected, not a bug.

Everything else

The application log is written to the same folder Marline uses for its database — see section 2 for the path. Include a redacted excerpt (no keys, no values) when reporting a bug.

16. Reporting a bug

Send bug reports to support@ctrlcolab.com. Please include:

• The Marline version (visible in Help → About Marline).
• Your OS and version.
• Reproduction steps — the shorter the better.
• A screenshot if the bug is visual.
• Anonymised log lines from the app log file (never include a raw key or secret; the log won't contain them, but sanity-check before sending).

If the bug involves a specific Flow, the File → Export project archive is the fastest way to hand us a reproducible copy — the archive never contains vault values.

17. Support

Marline is built by CTRL Colab. Reach out any time at support@ctrlcolab.com, or visit ctrlcolab.com/marline for release notes, the download page, and links to the other things we make.