Getting started

Install, bootstrap, and run your self-hosted exist.io Git forge and agent server.

This guide walks you through compiling the exist.io server daemon, initializing your first administrator account, creating a Git repository, and connecting an AI coding agent via MCP.

Prerequisites

• Go: Version 1.22 or higher
• Git: Version 2.30 or higher

1. Build the server and CLI

Compile the forge daemon (existd) and the companion CLI (exist):

# Clone the repository (if you haven't already)
git clone https://github.com/RavaniRoshan/exist.io.git
cd exist.io

# Build the forge daemon
go build -o bin/existd ./cmd/existd

# Build the companion CLI
go build -o bin/exist ./cmd/exist

2. Bootstrap your first administrator

Before launching the server, run the one-time offline bootstrap command to set up the SQLite database and create your root administrative credentials:

./bin/existd bootstrap \
  --email admin@example.com \
  --namespace acme \
  --data-dir ./data

This command:

1. Applies database migrations to ./data/exist.db in SQLite WAL mode.
2. Creates the root namespace (acme) and primary administrator user.
3. Outputs an administrative API token (prefixed with token_). Save this token securely.

3. Start the forge daemon

Launch existd:

./bin/existd --addr :8080 --data-dir ./data

The server binds to port 8080 and is immediately ready to accept Git Smart-HTTP connections, REST requests, and MCP sessions.

Key service endpoints

4. Interactive Onboarding, In-App Manual, & In-Browser Commits

When opening the web console (http://localhost:8080 in production or http://localhost:3000 during dev):

1. Interactive 5-step Onboarding Walkthrough: Automatically greets first-time administrators, detailing cluster network topology (:8080, :2222, /mcp), git client configuration, and agent leases.
2. In-App User Manual & System Guide: Accessible anytime via the “Manual” icon in the header, complete with live network port tables and copyable quick-start commands.
3. Canonical Quick Setup Screen: When a repository is newly created (0 commits), exist.io displays the canonical GitHub Quick Setup screen with HTTPS and SSH command blocks, git push instructions, and agent lease initialization commands.
4. In-Browser File Creation: Directly create and commit files (such as README.md or main.go) directly from the browser using the “Add file” button without touching your terminal.
5. Native SQLite Issues & Comments: Full issues lifecycle tracking with monotonic numbering, thread commenting, and state transitions backed by SQLite WAL storage.

Configure the exist CLI using your bootstrap API token:

export EXIST_ENDPOINT="http://localhost:8080/v1/origin"
export EXIST_TOKEN="<your-admin-token>"

Create and clone a repository

# Create a new repository in your namespace
./bin/exist repo create acme/demo-app

# Clone the repository using Git Smart-HTTP
git clone http://localhost:8080/acme/demo-app.git
cd demo-app

# Add a commit and push
echo "# My Demo App" > README.md
git add README.md
git commit -m "feat: initial commit"
git push -u origin main

Create a pull request

# Create a feature branch
git checkout -b feature/greet
echo "Hello exist.io!" >> hello.txt
git add hello.txt
git commit -m "feat: add greeting"
git push origin feature/greet

# Open a pull request with the CLI
./bin/exist pr create \
  -R acme/demo-app \
  --title "Add greeting feature" \
  --head feature/greet \
  --base main

5. Connecting AI coding agents via MCP

exist.io includes an embedded Model Context Protocol (MCP) server that grants AI coding agents structured access to read trees, inspect diffs, open pull requests, and review code.

Add the exist.io MCP server to your agent’s configuration file (e.g., Claude Desktop, Cursor, Cline):

{
  "mcpServers": {
    "exist-io": {
      "url": "http://localhost:8080/mcp",
      "headers": {
        "Authorization": "Bearer <your-admin-token>"
      }
    }
  }
}