Installing Semantix Studio

Semantix Studio ships as one file — an AppImage. There is no installer, no package to add to your system, and nothing that needs root. You download it, mark it executable, and run it.

Note

The public download is not up yet. The download page is where it appears the moment it is, along with its checksum and the exact filename. Everything below is how it works once you have the file.

What you need#

Semantix Studio is built and tested on Linux. That is the only platform it runs on today.

Requirement	What it means
Architecture	x86_64
Also needs	FUSE, which nearly every desktop distro already has — it's how AppImages mount themselves
Root	Not required, and never asked for

macOS and Windows are not supported. They are not quietly broken or half-working — they are not built. When they are real, they will appear on the download page, and not before.

Installing it#

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 AppImage carries its own engine room. 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.

Note

Running the scheduler as a service of its own, so tasks fire with the window closed and after you log out, is on the way. Until it lands, the honest rule is: the Studio open, the scheduler on. See When Semantix is closed.

Important

Your API keys are not in that list, and never will be. Nothing ships with a key in it, and Semantix does not resell you tokens — see About Semantix. You bring your own.

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 takes an email and a password, and 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.

→ 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, in this build — 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

Important

Those files hold real credentials. They live in your home directory, readable only by your user account, so treat them the way you'd treat any other file with a key in it — and don't commit them or copy them into a project.

Inside Semantix, a key is handled carefully: a saved flow never contains it (only an opaque reference to which model you picked), it is read fresh at run time, and it is deliberately kept out of logs and error output.

Where Semantix keeps things#

Everything Semantix writes lives under one directory:

~/.semantix/
├── 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#

There is no auto-updater. Semantix will not reach out, check a version, or replace itself while you aren't looking.

A new version is a new download: get the new AppImage, and use it instead of the old one. If you put it on your PATH as above, overwrite that file.

Your index, settings and keys are in ~/.semantix/ and are untouched by this.

Uninstalling#

# 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

Nothing was installed into your system, so 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#

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.

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.

Note

Semantix Studio is early — alpha moving toward beta, built and tested on one platform. If something here doesn't match what you're seeing, the honest answer is that it may be the docs that are behind, and we'd rather hear about it.