From Download to Running

What you need

• A desktop. A 64-bit Linux from the last few years, Windows 10 or later, or macOS 11 or later. Phones join later as remote views; the objects themselves live on the desktop.
• Disk. The installers are large because a headless browser ships inside so abjects can browse the web for you. Linux 226 MB, Windows 171 MB, macOS 290 MB.
• A mind to borrow. One of: an API key from any of the supported providers, a local model through Ollama (free), or the Claude Code, Codex, or Antigravity CLI already installed and logged in on this machine. Details in Pick a mind.
• No account. Abject has no signup. Your machine mints its own identity on first run.

First launch, per platform

The builds are not code-signed yet, so each operating system pauses once with a warning it shows for any software that has not paid for a certificate. This is the only time you will see it. Here is what to click.

Linux

AppImage. Mark it executable and run it:

chmod +x Abject-0.10.2.AppImage
./Abject-0.10.2.AppImage

AppImages need FUSE 2. On Ubuntu 22.04 and later and on Debian, install it once with sudo apt install libfuse2 (Fedora: sudo dnf install fuse). The AppImage starts Electron without the Chromium sandbox helper, because AppImages cannot carry a setuid binary and recent Ubuntu blocks user namespaces by default; the abject sandboxes are separate from that and unaffected.

.deb. Installs a launcher entry and a abjects command:

sudo apt install ./abjects_0.10.2_amd64.deb

Windows

1. Run the installer. SmartScreen shows "Windows protected your PC".
2. Click More info, then Run anyway.
3. Choose an install folder if you want one other than the default. Abject appears in the Start menu.

macOS

1. Open the .dmg and drag Abject into Applications.
2. Open it once. macOS says it cannot verify the developer and offers only to move it to the Trash. Click Done, not Trash.
3. Open System Settings, Privacy & Security, scroll to the bottom, and click Open Anyway next to Abject. Confirm once.

Prefer the terminal? Clearing the quarantine flag does the same thing in one line:

xattr -d com.apple.quarantine /Applications/Abject.app

Pick the build that matches your Mac: Apple Silicon for anything from 2020 on with an M-series chip, Intel otherwise (Apple menu, About This Mac). The download section lists whichever builds the current release ships.

Pick a mind

On first launch the settings window opens by itself on the AI tab. Nothing works until an abject can think, so this is the one step you cannot skip. Pick any of these, then click Save:

• An API key. Anthropic, OpenAI, Google Gemini, OpenRouter, DeepSeek, xAI Grok, Moonshot Kimi, MiniMax, or Meta. Paste the key next to the provider. Keys are stored in the app's data directory on your machine and sent only to that provider.
• Ollama, free and local. Install Ollama, pull a model (ollama pull and a model name), and leave it running. Abject finds it at http://localhost:11434 without configuration; a different host goes in the Ollama URL field.
• A coding CLI you already use. If the claude, codex, or agy command is on your PATH and logged in, it appears as a provider and rides the subscription you already pay for.
• A peer. Another Abject on the mesh can serve you its models through the PeerLLM provider. Useful when one machine in the house has the GPU.

Below the keys are four tiers: smart, balanced, fast, and code. Each points at a provider and model. Leave the defaults, or send the cheap bookkeeping to a cheap model and keep the smart one for planning. The abjects ask for a tier, never a specific model, so you can change your mind later.

Your first abject

1. Click Chat in the sidebar. A chat window opens.
2. Type what you want, in your words. Try: "a countdown to tonight's sunset for my city, with the sun sliding toward the horizon."
3. Watch the goal run. A window appears when the object is ready. Close the chat if you like; the window keeps running.
4. Click the ? in any window's title bar to see what that object can do and ask it questions in plain English.

The first time an abject wants to run a shell command, read a file outside its own sandbox, or reach a new website, a permission prompt appears and waits. Say yes once, or set standing rules under Settings, Permissions. The Web sub-tab has domain allow and deny lists; Filesystem has allowed paths and a read-only mode; Shell has a command allow list.

Your phone

There is nothing to install on the phone. The desktop app can show itself in a phone browser over an encrypted, direct connection:

1. On the desktop, click Network in the toolbar and open the Frontends tab.
2. Click Generate Pairing QR. The code is single-use and expires in about five minutes.
3. Scan it with the phone's camera. It opens client.abject.world with a pairing token, generates its own key pair, finds your desktop through the signaling server, and connects over WebRTC.
4. After the handshake the phone is remembered. Next time it reconnects on its own; revoke it from the same Frontends tab whenever you like.

The signaling server only introduces the two ends; it never sees the session. When the phone is on a cell network that blocks direct connections, traffic relays through a TURN server if the signaling server offers one, still encrypted end to end.

The terminal client

commune is a tabbed terminal view of your chats, goals, and permission prompts. It is a single executable with nothing to install, and it does nothing on its own: it connects to the desktop app, which must be running. Download it from the download section, mark it executable on Linux and macOS, and run it. It looks for the app at ws://127.0.0.1:7723.

Where things live

Everything Abject knows about you is in one directory:

Inside: your identity keys, provider keys, every workspace and the objects in it, the knowledge base, and a skills folder. Drop a SKILL.md into skills (Claude Code or OpenClaw format, unchanged) and rescan from Settings; the agents can use it on their next task. Set ABJECTS_DATA_DIR before launching to put all of it somewhere else. Delete the directory to start over as a stranger.

What it talks to

There is no telemetry and nothing phones home. The connections it does make:

• Your model provider, whichever you chose. With Ollama that is your own machine.
• signal.abject.world, so peers and paired phones can find your machine. It relays introductions only; every session is encrypted end to end with keys the server never has. Run your own with pnpm whisper from the source tree and point the app at it.
• The web, when an abject is asked to. Web search goes through DuckDuckGo with no API key; page fetches and browsing go wherever the task leads, within the domain rules you set under Permissions.

Updating and uninstalling

There is no auto-updater yet. Download the new version and install it over the old one; the data directory is untouched and your workspaces come back as they were. The changelog says what changed.

To uninstall, remove the app the usual way for your platform (delete the AppImage, apt remove abjects, the Windows uninstaller, or drag it out of Applications) and, if you want no trace, delete the data directory above.

When something sticks

The AppImage does nothing when launched.

Almost always missing FUSE 2. Install libfuse2 (or fuse on Fedora) and try again. Running it from a terminal shows the actual message.

"Port 7719 already in use."

Another copy is running, or something else took the port. Set WS_PORT to a free port before launching; the terminal client's port moves with it (it is always WS_PORT plus four).

Ollama is running but not offered.

Abject probes http://localhost:11434 at startup. If Ollama is on another host or port, enter its URL in the AI tab and save; if it started after Abject, restart Abject.

The CLI provider is missing.

The claude, codex, or agy command has to be on the PATH of the launched app, not just your shell. Launch Abject from a terminal where the command works, or install the CLI system-wide.

The window is blank or the desktop looks flat.

The renderer needs WebGL. On machines without it the desktop falls back to a flat 2D mode rather than staying blank; if you see nothing at all, launch from a terminal and read the log.

I want to start over.

Quit Abject and delete the data directory listed above. The next launch is a fresh first boot, settings window and all.

Still stuck? Ask on Discord or open an issue on GitHub with the log from a terminal launch.