Getting Started

This guide walks you through installing Ebla, creating your first library, and syncing files between devices. You'll have a working setup in under 10 minutes.

Prerequisites

For the server: Docker and Docker Compose installed on a Linux server or macOS.
For the client: Any Linux, macOS, or Windows machine.

Step 1: Install the Server

The quickest way to get a server running is with our install script. It sets up PostgreSQL and Ebla in Docker containers.

# Run as root or with sudo
curl -fsSL https://getebla.com/install.sh | sh

The installer will:

  1. Check that Docker and Docker Compose are installed
  2. Create the installation directory at /opt/ebla
  3. Generate secure random secrets for PostgreSQL and JWT authentication
  4. Write configuration files (docker-compose.yml, .env, server.toml)
  5. Start the PostgreSQL database and Ebla server containers
  6. Wait for the server to become healthy
  7. Display the admin URL and bootstrap token
Save the Bootstrap Token

The installer displays a one-time bootstrap token. You'll need this to create your admin account. If you lose it, check /opt/ebla/.env.

Expected Output

$ curl -fsSL https://getebla.com/install.sh | sh

Ebla Server Installer
=====================

Checking prerequisites...
  ✓ Docker installed (version 24.0.7)
  ✓ Docker Compose installed (version 2.21.0)

Creating /opt/ebla...
Generating secrets...
  ✓ PostgreSQL password generated
  ✓ JWT secret generated
  ✓ Bootstrap token generated

Writing configuration files...
  ✓ docker-compose.yml
  ✓ .env
  ✓ server.toml

Starting containers...
  ✓ ebla-postgres started
  ✓ ebla-server started

Waiting for server health check...
  ✓ Server is healthy

============================================
Ebla server is running!

  Admin URL:        http://your-server:6333/admin
  Bootstrap Token:  abc123-def456-ghi789

To create your admin account:

  curl -X POST http://your-server:6333/api/v1/setup/complete \
    -H "Content-Type: application/json" \
    -H "X-Bootstrap-Token: abc123-def456-ghi789" \
    -d '{"email": "admin@example.com", "password": "your-password"}'

============================================

Step 2: Create Your Admin Account

Before you can use Ebla, you need to create the first admin user. Use the bootstrap token from the installer output:

# Replace with your actual server URL and token
curl -X POST http://localhost:6333/api/v1/setup/complete \
  -H "Content-Type: application/json" \
  -H "X-Bootstrap-Token: YOUR_BOOTSTRAP_TOKEN" \
  -d '{
    "email": "admin@example.com",
    "password": "choose-a-strong-password"
  }'

You should receive a response like:

{
  "user": {
    "id": "usr_abc123",
    "email": "admin@example.com",
    "is_admin": true,
    "created_at": "2026-01-11T10:30:00Z"
  },
  "message": "Setup complete. You can now log in."
}

Step 3: Install the Client

Install the Ebla client on any machine you want to sync files from:

# Linux/macOS
curl -fsSL https://getebla.com/client | sh

# The binary is installed to ~/.local/bin/ebla
# Make sure ~/.local/bin is in your PATH

Verify the installation:

$ ebla --version
ebla version 0.56.0 (linux/amd64)

$ ebla --help
Ebla - File sync that respects your data

Usage:
  ebla [command]

Available Commands:
  login       Authenticate with an Ebla server
  logout      Clear stored credentials
  whoami      Show current user
  library     Manage libraries
  sync        Manage sync configurations
  daemon      Control the sync daemon
  status      Show sync status
  search      Search files and ask questions
  team        Manage teams
  log         Show commit history
  diff        Compare changes
  checkout    Restore files from commits
  config      Manage configuration
  p2p         P2P network settings
  help        Help about any command

Step 4: Log In to Your Server

Connect the client to your server. Ebla supports two authentication methods:

Browser-Based Login (Recommended)

This method opens your browser for secure authentication:

$ ebla login http://your-server:6333

  To complete authentication, visit:
    http://your-server:6333/app/cli-auth

  And enter code: ABCD-EFGH

  Waiting for authorization...

Open the URL in your browser, log in with your email and password, then enter the displayed code. The CLI will automatically detect the authorization and complete the login.

Password-Based Login (Headless/CI)

For servers without browser access:

$ ebla login http://your-server:6333 --password
Email: admin@example.com
Password: ********
Logged in as admin@example.com

Verify you're logged in:

$ ebla whoami
Email: admin@example.com
User ID: usr_abc123
Server: http://your-server:6333

Step 5: Create a Library

Libraries are the top-level containers for your files. Think of them like separate sync folders or projects.

$ ebla library create "My Documents"
Library created successfully

  ID:      e299620b-1234-5678-9abc-def012345678
  Name:    My Documents
  Owner:   admin@example.com

Use 'ebla sync add e299620b ~/path/to/folder' to start syncing.

List your libraries:

$ ebla library list
ID        NAME           OWNER              FILES   SIZE
e299620b  My Documents   admin@example.com  0       0 B

Step 6: Add a Folder to Sync

Connect a local folder to your library:

# Use the library ID prefix (first 8 characters)
$ ebla sync add e299620b ~/Documents

Sync configuration added:
  Library: My Documents (e299620b)
  Path:    /home/user/Documents

Run 'ebla daemon start' to begin syncing.

View your sync configurations:

$ ebla sync list
LIBRARY      PATH                    STATUS
e299620b     /home/user/Documents    pending

Step 7: Start the Sync Daemon

The daemon runs in the background and keeps your files synchronized:

# Start in foreground (useful for testing)
$ ebla daemon start

Ebla sync daemon starting...
  Server: http://your-server:6333
  User: admin@example.com
  Libraries: 1

[10:35:00] Scanning /home/user/Documents...
[10:35:01] Found 156 files (23.4 MB)
[10:35:01] Chunking files...
[10:35:03] Uploading 892 blocks...
[10:35:15] Upload complete
[10:35:15] Committed: abc123 (156 files, 23.4 MB)
[10:35:15] Watching for changes...
Running as a Service

For production use, run the daemon as a systemd service or launchd agent. See the Installation guide for instructions.

Step 8: Sync to Another Device

On a second device, install the client and sync the same library:

# Install client
curl -fsSL https://getebla.com/client | sh

# Log in to the same server
ebla login http://your-server:6333

# List available libraries
ebla library list

# Sync to a local folder
ebla sync add e299620b ~/Documents

# Start the daemon
ebla daemon start

The daemon will download all files from the server and then watch for changes on both devices.

Verify Everything Works

Check the overall sync status:

$ ebla status
Sync Status
===========

Server: http://your-server:6333 (connected)
User: admin@example.com

Libraries:
  My Documents (e299620b)
    Status: up-to-date
    Local path: /home/user/Documents
    Files: 156
    Size: 23.4 MB
    Last sync: 2 minutes ago

Daemon: running (PID 12345)
P2P: enabled (2 peers discovered)

Access the Web UI

Ebla includes a web interface for browsing files, searching, and administration:

Next Steps

Now that you have Ebla running, explore these topics:

Sync & P2P Learn about conflict resolution, P2P acceleration, and offline support Teams & Permissions Share libraries with team members and set up access controls AI Search Configure semantic search and natural language queries Configuration Customize server and client settings Operations Backups, monitoring, TLS, and production deployment CLI Reference Complete command reference with examples

Troubleshooting

Server won't start

# Check container logs
cd /opt/ebla
docker compose logs ebla-server

# Check if PostgreSQL is healthy
docker compose logs ebla-postgres

# Verify configuration
cat server.toml

Client can't connect to server

# Test connectivity
curl http://your-server:6333/health

# Check firewall
sudo ufw status
sudo ufw allow 6333/tcp

# Verify credentials
ebla whoami

Files not syncing

# Check daemon status
ebla daemon status

# Force immediate sync
ebla sync now

# Check sync configuration
ebla sync list

# View daemon logs
ebla daemon start  # Run in foreground to see logs

Getting help