Install & Run

Welcome! In this Getting Started guide, we’ll first see how to install TrailBase, followed by tutorials on building a first application.

TrailBase is a single executable and therefore very easy to install. It’s as simple as downloading the latest release for your system and running it. If you prefer building your own binary, check out our GitHub page.

If you want to get started even quicker, you can simply run one of the following commands:

curl -sSL https://trailbase.io/install.sh | bash

iwr https://trailbase.io/install.ps1 | iex

# Mimic "install" with Docker. Add the alias to your shell's rc to persist.
alias trail='
  mkdir -p traildepot && \
  docker run \
      -p 4000:4000 \
      -e ADDRESS=0.0.0.0:4000 \
      --mount type=bind,source="$PWD"/traildepot,target=/app/traildepot \
      trailbase/trailbase /app/trail'

Once installed, you can run

trail help

to check that the executable is properly installed and list all available command line options.

Install Optional Auth UI

If you want to install the auth UI, you can simply run:

trail components add trailbase/auth_ui

which will add a WASM component exposing additional UI endpoints.

Start the Server with Dashboard

After successfully installing TrailBase above, you can run

trail run

to bring up the server on localhost:4000.

On first start, a ./traildepot depot directory will be created. It contains configuration, databases, secrets and a few more things. Moreover, an admin user will be created and their credentials printed to the terminal. Watch out for something like:

Created new admin user:
        email: 'admin@localhost'
        password: '<random>'

Optionally, you can change the credentials to something more deliberate:

trail user change-password admin@localhost mypassword
trail user change-email admin@localhost [email protected]

Note that no authentication is necessary, since you already have privileged OS-level access to the local depot.

Armed with your new credentials, open http://localhost:4000/_/admin/ in your browser and log in.

We encourage you to take a few minutes, click around, and maybe create a table or two. Note that when creating, altering, or deleting tables, indexes or views a schema migration file will be created in traildepot/migrations. This allows TrailBase to enforce consistent schemas across multiple database instances for dev, test, prod, … .

If you installed the auth UI above, feel free to explore it as well: http://localhost:4000/_/auth/login.

If you like what you see and want to get your hands dirty, consider checking out some of the tutorials. Lastly, if you have any issues or feedback, don’t hesitate to reach out either on GitHub, Discord or via [email protected].

Start an MCP

The binary also ships with a built-in local MCP server that can be started independently and pointed at a running TrailBase instance to support agentic workflows.

In order for the MCP to proxy tool requests, especially for admin APIs, authentication is required. If you have local access to the depot, the MCP can authenticate itself by running:

trail [--depot=./traildepot] mcp --user=admin@localhost http://localhost:4000

Or if you’re trying to connect to a remote TrailBase instance, you can look up an admin’s tokens in the dashboard in the profile dialog when clicking the user icon on the bottom left. They can then passed as follows:

TOKENS=<eyJhd...> trail mcp https://mytrailbase.org

Agents can communicate with the MCP using stdin.