Getting started

From a clean checkout to your first chat.

Synoec runs from source. The desktop app and the synoec CLI share one engine, so a provider you connect in one is available in the other. This page installs both, connects a model and starts a first chat.

Requirements

Need	For
macOS on Apple Silicon	The main tested platform. Windows desktop and CLI builds exist and have testing releases; they were exercised on a Windows 11 VM, and clean-machine Windows journeys are still limited
Git	Cloning and project work
Bun 1.3.14	The engine, CLI and build scripts (pinned in package.json)
Rust	The desktop build compiles its process guardian with Cargo
A provider account or API key	OpenAI Codex, Claude, Cursor, Anthropic, Google Gemini, Amazon Bedrock, an OpenAI-compatible server and others

Install

git clone https://github.com/Devkison/Synoec.git
cd Synoec
bun install --frozen-lockfile

CLI. Install the synoec command (a native binary under ~/.local by default):

bun run cli:install
synoec --version

Desktop. Build, assemble and launch the app in one step:

bun run desktop:app

The assembled app is apps/desktop/.build/darwin-arm64/Synoec Desktop.app; open it directly next time. Quit the app before rebuilding it. The desktop build guide covers the separate build and assemble steps.

Testing releases. GitHub releases publish a Mac .dmg and a Windows .exe installer; the latest is v0.8.130, while the source is already 0.8.139. They are testing releases, so building from source gives the newest behavior. See Releases.

Connect a provider

Desktop. The first window asks What would you like to work on? and, until a Profile exists, offers Open project folder and Profiles & Providers.

1. Choose Profiles & Providers. This opens Settings → Profiles & Providers.
2. Choose New Provider, pick a provider card (Sign in with an account or Sign in with an API key), sign in or enter a key, then activate models on the Models step.
3. Create a Profile with New Profile: pick the providers it may use and its default chat model.

On a Mac, opening Providers also looks for a running Ollama and, when it finds one, adds it with its pulled chat models; see Local AI.

CLI. Run synoec on a terminal; with nothing configured, setup runs first. You can also run it directly:

synoec setup
synoec doctor

Both clients save to the same workspace, so either path is enough. A Profile only says which providers and models are available; the model for each chat is picked in the composer. See Providers and models.

Your first chat

The home screen reads Start a Quick Chat, or choose a project. The project name is a menu: pick one of your projects, Quick Chat, or Open project folder….

• Quick Chat. Choose New chat in the sidebar and type in Ask anything…. Quick Chats have no project folder.
• Project. Choose Open project folder…, pick a repository, then start a chat inside it. Project chats can read, edit and run commands in that folder.

Under the composer, pick a mode (Ask explores without changing anything; Agent acts) and check the model, then send. With the default sandbox level, Approve for me, the agent works inside the project and asks before anything riskier; change it in Settings → Permissions. Review edits in the Workbench’s Changes tool.

In the terminal, cd into a project and run synoec, or run one request:

cd /path/to/project
synoec
synoec -p "Explain how this project is built" --mode ask

Where things live

Configuration and history live under ~/.synoec (override with SYNOEC_HOME). Use Synoec’s own commands to change it.

Next steps

• Tour the app: Desktop app, Agora, Lysis.
• Learn the terminal: CLI.
• Organize work: Workspaces and memory, Tasks and subthreads.
• Add tools and web search: Tools and integrations.
• Track cost: Usage and pricing.
• When something goes wrong: Operations.

Limits

• Releases are testing releases; the current source is ahead of the latest one.
• Mac source builds are signed with an Apple Development identity when the Mac has one, otherwise ad-hoc; they are not notarized.
• Memory, web tools and Computer Use are optional and set up separately.

Related

Decisions behind this page: 0092 — see the decisions index.