Ciele Desktop

Ciele Desktop is a macOS and Windows application that opens on a choice.

• Sign in to your organization: the app opens your organization's console in a window of its own, with a session that survives restarts. The address is configurable, so the same path also reaches a self-hosted Ciele on your own server.
• Use locally (self-host): a guided setup stands up a complete Ciele on this machine: database, migrations, scheduled jobs and all. It needs no terminal, and Docker Desktop is the only thing you install yourself.

Both can coexist, and you can switch between them at any time. Everything you actually do with Ciele happens in the product UI you already know, the app adds a window around it, not a second interface.

Which path to pick

The local path is a real Ciele, not a demo: the same containers, the same migrations, the same scheduled jobs the server self-host runs. What it is not meant for is serving a production widget to the public, which needs an address the public can reach.

Install

Both downloads are on the latest release.

macOS

1. Download the .zip for your processor.
2. Unzip it and move Ciele.app to your Applications folder.
3. Right-click (or Control-click) Ciele.app and choose Open, then Open again in the dialog.

That third step matters. The beta is unsigned, so double-clicking it the usual way stays blocked by macOS until you have opened it once this way. You only have to do it once.

Windows

1. Download the Setup.exe installer.
2. Run it. SmartScreen says "Windows protected your PC" because the beta is unsigned. Select More info, then Run anyway.

If the download itself is blocked, right-click the file, open Properties, and check Unblock.

Signing in to your organization

Choose Sign in on the welcome screen. The app loads your organization's console and remembers the session, so later launches go straight there.

To point the app at a self-hosted server instead, open Settings and change the server address. Reach it from the control icon on the welcome screen, or with ⌘, on macOS and Ctrl+, on Windows. Anything http:// or https:// works. The app keeps the origin and drops any path you paste with it.

The app plays the same short interface sounds as the console. Interface sounds in Settings turns them off for this machine.

Sign out clears the app's stored session for that server: cookies, cache and all. It closes more than the window. On a shared machine, that is the thing to do.

If the address does not load, the app says so on its own screen. It shows the address it tried, what went wrong, and buttons to retry or correct it. You never land on a browser error page in a window with no address bar.

Setting up a local Ciele

Choose Use locally. The wizard runs each step and verifies it before it opens the next one. A green check means the step worked, not that it finished.

1. Docker Desktop

The wizard checks that Docker Desktop is installed and running. Those are different problems with different fixes, and it says which one you have. Each failure carries its own walkthrough, written for someone who has never installed developer tooling. The install link points at the page for your platform. Install or start Docker Desktop, then press Try again. The check re-runs in place.

2. Data folder and secrets

The app creates a folder for this installation and generates every password and key the stack needs. You never edit an environment file.

If a configuration already exists, the app keeps it rather than generating a new one. Your database is sealed with the secrets already in that folder. Fresh secrets would lock you out of it.

3. Download Ciele

Pulls the published container images for this version of the app. This is the slow step on a first run. Nothing is built from source, which is why setup takes a coffee break and not an afternoon.

4. Start the stack

Brings up the database, the app and the scheduled jobs, detached, they keep running after you quit Ciele Desktop.

5. Prepare the database

Applies the schema and waits for Ciele to answer. "The containers started" and "Ciele is serving" are different claims, and this step waits for the second one.

6. Demo content (optional)

Loads an example organization with assistants, so you see a populated product before adding anything of your own. Skip leaves you with an empty, working Ciele.

7. Connect an AI model (optional)

Point Ciele at any OpenAI-compatible server or a hosted provider. For Ollama on this machine, the address is http://host.docker.internal:11434/v1: inside a container, localhost is the container.

Skipping is fine. Without a model, assistants answer from the built-in keyword engine, and Knowledge search falls back to lexical matching. Everything else works.

When a step fails it says what failed and keeps its logs behind Show details. Try again resumes from that step rather than starting over.

Once setup finishes, Open Ciele loads the local console. The first account you create owns the organization. Later launches skip the wizard entirely.

Day two

Stack status shows whether your local stack is up. Reach it from the wizard's last step, from Settings, or from the Ciele menu. It starts and stops the stack without Docker Desktop. "Running" there means Ciele answered, not that containers exist.

Stopping is reversible and touches no data. Quitting the app does not stop the stack. It runs detached, on purpose.

Where your data lives

Back up the database the same way any self-host does, see Database. Uninstalling the app removes neither the volumes nor the stack.

Updating

The app checks for a newer release on launch and shows a dismissible notice with a download link. There is no automatic update, because neither platform auto-updates an unsigned app.

Updating the app is what rolls your local stack forward. Each build pins the container images matching its own version, so the next setup or start pulls those and re-runs migrations. Your data stays where it is.

Starting over

To reset the local installation, stop the stack from the status screen and remove the compose project's volumes with Docker Desktop, or from a terminal:

docker compose --project-name ciele down -v

That deletes the local database and uploaded files. The next time you choose Use locally, the wizard runs from the beginning.

Troubleshooting

"Docker Desktop is not installed" when it is. An app launched from the Dock or the Start menu does not inherit your shell's PATH. Ciele therefore looks for the Docker CLI where Docker Desktop installs it. On macOS that is the Homebrew and /usr/local/bin locations. On Windows it is Program Files and the per-user Programs folder. It will not find a Docker you installed anywhere else. On macOS, a symlink into /usr/local/bin fixes that.

The stack sits on "Starting". Postgres may still be initialising on a first run. Give it a minute, then press Check again. If it stays there, open the logs from Docker Desktop. A container that keeps restarting is usually short of memory.

"Could not download the images." The pull could not reach the registry. Check your connection or proxy and press Try again. Nothing downstream ran, so there is nothing to undo.

Assistants answer, but they ignore my knowledge. No embedding model is configured, so retrieval falls back to keyword matching. Add an embedding model in Configuration.

"Ciele did not load" when signing in. The address in settings is not serving Ciele. The screen names what went wrong. A typo gives "that address does not exist". A server that is off gives "nothing is listening". An address that answers without being Ciele says so. Change address takes you straight to the setting.

macOS says the app is damaged or cannot be opened. That is Gatekeeper on an unsigned app. Right-click Ciele.app, choose Open, then Open again. Double-clicking will not offer that option.

Windows blocks the installer. That is SmartScreen on an unsigned app. Select More info, then Run anyway. If the file was blocked at download, unblock it first from its Properties.

What the desktop app is not

• It does not serve production widgets. Local widgets are for testing and preview. Publishing to real visitors needs a reachable server.
• It is not signed or notarized, and it does not auto-update.
• It runs the default profiles only. The heavy optional workers stay off. Add them from Workers if you need them.