Quickstart

This guide walks you through installing Tribunus Desktop, connecting an inference backend, starting your first agent session, and installing a plugin to extend its capabilities. By the end you will have a working coding agent that can read, explain, and suggest changes to your project.

Prerequisites

• macOS 14+ (Sonoma or later) or a modern Linux distribution with glibc 2.28+
• At least 8 GB of RAM; 16 GB recommended when running local inference
• An API key for a remote LLM provider (OpenAI, Anthropic, etc.) or a local Tribunus Compute engine

Step 1: Download and install Tribunus Desktop

Download the latest release from the GitHub releases page. Choose the package for your operating system and architecture.

macOS (Apple Silicon or Intel) — open the .dmg file and drag Tribunus Desktop into your Applications folder. On first launch, macOS may prompt you to grant accessibility permissions — these are needed for Desktop’s automatic code-editing features. You can enable them later in System Settings > Privacy & Security > Accessibility.

Linux (x86_64) — extract the .tar.gz archive and run the executable:

tar -xzf tribunus-desktop-*.tar.gz
cd tribunus-desktop
./tribunus-desktop

For convenience, move the directory to /opt/tribunus-desktop and create a .desktop entry, or use the AppImage variant for distribution-agnostic execution.

Windows. The developer preview supports macOS and Linux only. Windows is not yet supported, and there is no timeline for it at this stage.

Step 2: Launch the app

Open Tribunus Desktop from your Applications folder, Spotlight (macOS), or the terminal. The application starts with a welcome screen that presents three paths:

• New Session — start an agent workspace immediately.
• Open Project — browse for an existing project folder.
• Configure Backend — set up your inference provider before your first session.

The welcome screen also displays the current version, any available updates, and a link to the plugin catalog. Take a moment to explore the sidebar — it lists your recent sessions, installed plugins, and the settings panel.

Step 3: Connect a model

Tribunus Desktop needs an inference backend to power its agents. You have two options:

Tribunus Compute (local inference). If you have installed the Compute engine, start its daemon in a terminal:

tribunus-compute serve --port 8080

Then open Desktop and go to Settings > Inference Backend > Tribunus Compute. The app will auto-detect a running daemon on 127.0.0.1:8080. Load a model through the Compute CLI (tribunus-compose load --model <path>) and Desktop will pick it up.

Remote provider (API key). If you prefer not to run local inference, select Remote API in the backend settings. Enter your provider endpoint and API key:

1. Choose a provider from the dropdown (OpenAI, Anthropic, or a custom OpenAI-compatible endpoint).
2. Paste your API key. The key is stored in the system keychain, not in plain text.
3. Select a model from the list that populates after authentication.

Desktop will test the connection and report success or surface any configuration errors. You can switch backends at any time from the same settings panel.

Step 4: Open a project folder

Click Open Project on the welcome screen, or use File > Open Project from the menu bar. Navigate to a directory on your machine — any software project with source code files will work. Desktop will scan the folder and build a file tree in the session panel.

The project tree shows every file in your directory. You can expand directories, preview file contents inline, and mark files as context for the agent. The agent will use the files you mark as its working context when processing tasks.

For this guide, any project with a few source files is sufficient. If you do not have one handy, clone a small open-source repository:

git clone https://github.com/example/sample-project.git ~/Projects/sample

Then open ~/Projects/sample in Desktop.

Step 5: Run your first agent task

With a project open and a backend connected, you are ready to run your first agent task. Click New Session to create a fresh agent workspace. A chat panel opens where you can type instructions.

Start with something simple — ask the agent to explain a file in your project:

Explain the main entry point file in this project. What does it do, what modules does it import, and how does the control flow work?

The agent will:

1. Identify the relevant file(s) from the project tree.
2. Read the file contents.
3. Analyze the imports, function definitions, and control flow.
4. Construct a response with inline code references.

You will see the agent’s reasoning steps appear in the session log as it works. Each step shows the tool the agent called (read file, search, analyze) and the result it received. This transparency lets you understand — and later refine — how the agent arrives at its answers.

Try a follow-up task that asks for a change:

Add error handling to the main function: wrap the core logic in a try/except block and log any exceptions before re-raising them.

Desktop will produce a diff showing the proposed change. You can apply it directly to your project from within the app. Every change is isolated to the active session until you approve it.

Step 6: Install a plugin

Plugins extend Desktop with new capabilities. From the Plugins tab in the sidebar, open the plugin manager. It displays a catalog of official plugins and any community plugins you have added.

Click Browse Catalog and install the Git Integration plugin:

1. Find Git Integration in the list and click Install.
2. Desktop downloads and verifies the plugin binary against its published checksum.
3. A permissions prompt appears: the plugin requests access to your Git repositories and the file system. Review the scope and grant it.
4. The plugin appears in your installed list with an indicator light showing its status.

After installation, the Git plugin adds new tools to every agent session: git diff, git log, git status, and git commit. Now your agent can read commit history, check the working tree, and even create commits with your approval. Try asking:

Check the Git log for the last 5 commits and summarize what changes were made.

The plugin integration is seamless — the agent calls Git tools the same way it calls built-in file tools.

Step 7: Next steps

You now have a working Tribunus Desktop installation with a connected model and an extended tool set. Here is what to explore next:

Configure keyboard shortcuts. Open Settings > Keyboard Shortcuts to view the default bindings. You can rebind any action — session switching, quick open, plugin management — to a shortcut that fits your workflow. Desktop also supports multi-step macro bindings for power users.

Explore multi-agent sessions. Desktop supports multiple agents within a single session. Open a new agent tab and assign it a different model or a focused set of tools. Agents can delegate subtasks to each other via structured channels, enabling workflows like “agent A reads the codebase and drafts a plan, agent B implements each change, agent C reviews the diffs.”

Write custom plugins. The plugin system is language-agnostic. A plugin communicates with Desktop over JSON-RPC and can add new tools, custom model providers, or entire orchestration strategies. Start with the plugin SDK which provides templates, example plugins, and a test harness. The SDK includes a scaffold command that generates a working plugin project in Python, Rust, or JavaScript.

For a deeper look at the platform’s architecture, read the Core Concepts guide. For Compute-specific setup, see the Compute installation guide.