Your first synth, running in five minutes.

1 · Install Caedos

macOS or Linux, in a terminal:

curl -fsSL https://caedos.com/install.sh | sh

Windows, in PowerShell:

irm https://caedos.com/install.ps1 | iex

The script downloads the build for your computer from the latest release on GitHub ↗, checks it against the release's checksums, and puts caedos in ~/.local/bin, or on Windows in %LOCALAPPDATA%\Programs\Caedos, which it adds to your PATH. It needs no admin rights, and changes nothing else. Read it first if you like: install.sh · install.ps1.

Or download it:

Unpack it and run caedos from that folder: ./caedos start in a terminal on Linux, or double-click caedos.exe on Windows. Every release lists signed checksums: check a download.

Why there's no Mac download

Apple hasn't notarized Caedos yet. Notarizing needs a paid Apple Developer membership, which Caedos doesn't have yet. Until it does, macOS refuses to open Caedos if a browser downloaded it. macOS doesn't flag what curl downloads, so on a Mac, install with the script, which picks the build for Apple silicon or Intel. The Mac build is beta until it's notarized.

Windows is beta

The Windows build isn't code-signed yet. Where Smart App Control is on, Windows blocks it, and there's no way past that while it stays on. A browser download also shows a SmartScreen warning; the PowerShell script doesn't.

2 · Open it

caedos start

You'll see something like this (the data folder depends on your system):

Caedos  0.1.0 · build …
    Free for personal use and work.

    Control room    http://localhost:2233
    Claude Code     claude mcp add --scope user caedos -- caedos mcp
    Any MCP client  command caedos, argument mcp
    Data            /home/you/.local/share/caedos
    Model key       not set · add one in Settings
    Running         nothing yet

Open the control room at http://localhost:2233. It says Nothing running yet. That's right. Caedos runs while that terminal is open, and q stops it.

3 · Connect Claude Code

claude mcp add --scope user caedos -- caedos mcp

Any other MCP client: the command caedos, with the argument mcp. As JSON:

{ "mcpServers": { "caedos": { "command": "caedos", "args": ["mcp"] } } }

If caedos isn't on your PATH, use its full path: the start screen prints both lines for your computer. caedos mcp connects your AI to the Caedos that's running, and finds its port by itself.

Then say something ordinary:

Keep an eye on Hacker News for new stories about my product and post them to this Slack webhook: …

Your AI reads the handbook, writes the synth, validates it, shadows it against the real world, and deploys it leashed. Open the control room to see it.

Or by hand, in the control room:

1. Blueprints → HN keyword watcher → View config. Copy the JSON.
2. + Install a Synth. Paste it and change query=claude in the URL to your word.
3. Shadow. You'll see the titles it read and what it would remember. Shadowed — nothing was sent.
4. Deploy, then paste your WEBHOOK_URL when it asks.

When it has something to send

The first time a process sees a list, it remembers it and sends nothing; otherwise you'd get 20 "new" stories at once. After that, anything it would send waits in the process's approval queue. Approve one and check your channel. When you trust it, press Allow and it sends on its own.

Working overnight

Use a computer that doesn't sleep, and run:

caedos service install

Caedos then starts when you sign in, and starts now. It stops when you sign out: to keep it running signed out, you need admin rights on Windows and macOS, or loginctl enable-linger on Linux. caedos service uninstall undoes it.

A computer that's asleep runs nothing. When it wakes, each process that was due runs once, and the control room says how long it slept.

Troubleshooting

• caedos: command not found. The installer printed the line that puts its folder on your PATH; add it, then open a new terminal. Or run Caedos by its full path, ~/.local/bin/caedos.
• Port 2233 is taken. CAEDOS_PORT=2300 caedos start (in PowerShell, $env:CAEDOS_PORT=2300 first). Caedos saves its port in its data folder, so caedos mcp and the other commands follow it.
• Your AI says Caedos isn't running. Run caedos start, or caedos service install to keep it running. The chat doesn't need restarting.
• A Mac won't open it. A browser downloaded it. Install with the script instead.
• Double-clicking it shows nothing on Linux. Run caedos start in a terminal.
• Smart App Control blocked it. The Windows build isn't code-signed yet, and there's no way past while Smart App Control is on.
• ⚠ Settings is amber. No model key yet. Fine for no-LLM blueprints; add one in Settings for the rest.
• source_errors in a trace. The source failed: a URL, a 429, a timeout. That's weather, not a broken synth.
• Everything says idle. Nothing changed. Idle is not broken.
• Something else. caedos doctor checks this computer's Caedos: its data folder, database, vault key, service and model key.

Where your work lives

• Windows %LOCALAPPDATA%\Caedos
• macOS ~/Library/Application Support/Caedos
• Linux ~/.local/share/caedos

That folder holds the database, caedos.db, and the key to its vault, vault.key. Keep the two together: without the key, stored credentials can't be read. Caedos snapshots the database there every hour, and caedos restore brings a snapshot back with every process paused. CAEDOS_DATA_DIR moves the folder.

To update, run the install command again, then caedos service install again if you use it, which restarts Caedos on the new version. Caedos never checks for updates itself: watch releases on GitHub ↗.

Next

• Write your own: the handbook is at http://localhost:2233/api/os/docs, and your AI gets it automatically over MCP.
• Browse blueprints → · How it works → · Security →

FAQ