Installing Semantix Studio

Semantix Studio runs on Windows and Linux. Get it from the download page: an installer for Windows, a single AppImage file for Linux. Neither one needs administrator rights or root.

What you need#

macOS is not supported. It is not quietly broken or half-working — it is not built. When it is real, it will appear on the download page, and not before.

Installing it on Windows#

Run the installer you downloaded, then open Semantix Studio from the Start menu. It installs for your user only, so it does not ask for an administrator.

Installing it on Linux#

From wherever you put your downloads:

# 1. make it executable
chmod +x Semantix-Studio*.AppImage

# 2. run it
./Semantix-Studio*.AppImage

That's the whole installation. The file you downloaded is the program — it does not unpack itself into your system, register services, or write anything outside your home directory.

If you'd like it in your menu like a normal application, move it somewhere on your PATH first:

mkdir -p ~/.local/bin
mv Semantix-Studio*.AppImage ~/.local/bin/semantix
chmod +x ~/.local/bin/semantix
semantix

What's inside the file#

The download carries its own engine room, the same on both systems. Four things ride inside:

• The Semantix shell — the IDE you actually look at: editor, search, the living graph.
• semantix-server — the local engine. Parses your code into symbols, references and callers, keeps the graph alive, runs the agent's tools, and answers the editor's questions. This is the piece that makes the index work, and it runs on your machine.
• semantix-trig — the scheduler's clock. It keeps the alarms for tasks that fire on a schedule.
• semantix-tasksd — the scheduler's hands. When an alarm goes off, this is what runs the task.

They start and stop with the app. You do not install, configure, or run any of them yourself — and that cuts both ways: close the Studio window and the scheduler stops with it. A task set for 4am runs at 4am only if the Studio is open at 4am.

First run#

The window opens on one button: Open Project. Point it at a folder.

The first time Semantix sees a folder it asks you to set it up — a name, and whether the project gets an agent with memory. Say yes to the defaults and it opens; your files are never touched or moved.

→ Opening a project

Then it indexes. The first index of a large project takes a moment — it is parsing every file, not scanning names. After that it keeps itself current as you edit, and only re-reads files that actually changed.

You can use the editor, the search and the graph immediately, with no account and no network. Understanding your codebase happens on your machine.

The agent needs an account. The agent panel says so — Sign in to continue, or Create your account — and that's where you do it. Signing in opens your browser: use an email and a password, or your Google or GitHub account. A new email account has to confirm its address from the mail we send before it can do anything. From then on the Studio checks in with your account when it starts. What the account is for: your conversation backups, your memory and your scheduled tasks all live against it, each one off until you turn it on.

The Studio tells us it exists. When it starts, it sends a short report: a random install ID, a one-way fingerprint of your computer, its version and your system type. Nothing about your code or what you do with it. The Privacy Policy says exactly what is in it and why.

→ Privacy — exactly what leaves your machine, and when

Giving the agent a model#

An agent needs a model, and there are three ways to hand it one, all under Settings → Models:

• Connect a provider. Paste one API key — OpenRouter or Anthropic, for example — and its whole catalogue becomes searchable in the chat's model picker, prices and context windows included.
• Switch on a coding agent you already have. If the claude command is installed and signed in on this machine, Claude Code is on by default and needs nothing else. Other installed agents — Cursor, Copilot, Gemini, OpenCode — appear alongside it with their own sign-ins.
• Add a custom model. Any OpenAI-compatible or Anthropic-compatible endpoint: a name, a base URL, the model id, and your key.

→ Models

Keys are stored on your machine, in plain JSON:

~/.semantix/USER/providers.json        connected providers
~/.semantix/USER/custom-models.json    custom models

Where Semantix keeps things#

Everything Semantix writes lives under one directory in your home folder — ~/.semantix/ on Linux, C:\Users\<you>\.semantix\ on Windows:

~/.semantix/
├── install.json               this copy's random install ID
├── projects.json              your project list
├── conversations.db           every conversation, all projects
├── analytics.db               your usage statistics
├── extensions/                installed extensions
├── logs/                      the on-device server's logs
├── USER/                      sign-in, keys, models, MCP servers, instructions, commands, tools
└── WORKSPACE/<project-id>/    per project: instructions, commands, tools, checkpoints,
                               and index/ — what Semantix learned about your code

Your projects are not touched. The index is kept beside Semantix, not inside your repository, so there is nothing new to add to .gitignore.

Not on your disk: what the agent remembers, your conversation backups, and your scheduled tasks. Those live on the Semantix server, against your account.

Updating#

You download Semantix once. After that, new versions arrive inside the app.

Shortly after it starts, the Studio checks whether a newer version exists. If one does, it asks you first, showing the version and what changed. Say yes and it downloads the update, checks its signature, replaces itself and reopens. Say no and nothing changes.

An update is only installed if it carries our signature, so a download that was tampered with is refused before anything is written.

Your index, settings and keys are in .semantix in your home folder and are untouched by this.

Uninstalling#

Windows: remove Semantix Studio from Settings → Apps, then delete the .semantix folder in your user folder to remove everything it wrote.

Linux:

# the program
rm ~/.local/bin/semantix        # or wherever you put the AppImage

# everything it ever wrote to this machine — index, settings, keys, conversations
rm -rf ~/.semantix

That is all of it on this machine. Deleting ~/.semantix also deletes your saved keys and every conversation, so if you only want to free the disk that indexes take, delete ~/.semantix/WORKSPACE/ and leave the rest — Semantix rebuilds an index the next time you open that project. (That folder also holds each project's own instructions, commands and custom tools, so move those first if you wrote any.)

What it doesn't remove is anything kept against your account: memory, conversation backups, tasks. To clear those before you go, use Forget project in the Project Manager for each project, and switch Local only on in Settings → Privacy, which offers to delete your backups.

If something goes wrong#

Windows blocks the installer. See the note under Installing it on Windows.

On Linux it won't start, and the terminal mentions FUSE. Your distro is missing FUSE. Install it (fuse or libfuse2 depending on the distro), or run the AppImage extracted: ./Semantix-Studio*.AppImage --appimage-extract-and-run.

On Linux it won't start, and nothing is printed. Run it from a terminal rather than a file manager — the AppImage prints its startup errors to stdout, and a double-click throws them away.

The graph or search is empty on a project you just opened. The first index is still running. Large projects take longer; it is parsing, not listing.

The agent panel only offers to sign in. That's not an error — the agent needs an account, the editor doesn't. Sign in there, or carry on without an agent.