Quickstart

Install LinX first, or deploy Xpod first

Use the first section to start with LinX, the second to run Xpod yourself. Each one gives prerequisites, steps, a completion check, and where to get help.

Quickstart quickstartinstallself-hosting

This page covers two things: how to start using LinX, and how to get Xpod running. Reading and writing data from an application lives in a separate quickstart, because it needs a Pod you can already connect to.

If you first want to know what each piece is responsible for, read What LinX, Xpod, and drizzle-solid each do.

Every prerequisite and command below comes from public official material. The Xpod commands are quoted from the official README and we have not run them; LinX has no verified desktop installer. We mark what is official documentation and what is still unverified.

Use LinX

LinX is the client you open to get work done. You give it your material and your requirements, it produces a result, and you revise that result until it is usable.

Check these three things first

Device and system: look for a package for your machine in the release record. At the time of writing, the latest entry is linx-v0.3.33 (published 2026-06-30) and its only asset is undefineds-co-linx-0.3.33.tgz.
Account and sign-in: how you sign in and connect depends on the service you actually use. We have not verified any registration or sign-in flow, and this page promises no account, quota, or price.
Network: your machine can reach the Pod address you choose and can reach GitHub to fetch release files.

That .tgz asset is a package file, not a desktop installer. It is useful for builds and integrations, but it is not “download it and double-click.” So this page does not describe an installer wizard that we cannot confirm exists.

Where installation actually starts today

The entry point you can check is the release record. Each entry lists a tag and its files.
If an entry has a package for your platform and architecture, follow that entry’s instructions.
If it only has a package file such as .tgz, it is not a runnable desktop application. Please do not treat it as an installer.
Until this site can verify a real, downloadable, installable package, the download page stays in its empty state rather than offering a dead download button.

First launch and a first task

We have not performed a desktop installation, so there are no interface steps here. Once you have a usable build, start with something small, in this order. These steps describe the task, not the location of a button. If a step does not exist in your version, that capability has not shipped yet.

Gather material: collect what this week can give you — a few meeting notes, a progress list, two emails waiting on a reply.
State your requirements: “Lead with the conclusion. Separate what is done, what is stuck, and what is planned for next week. Leave dates blank until they are confirmed.”
Check the structure: the result should separate this week’s progress, current blockers, decisions needed, and next week’s plan.
Change one thing: pick a line that does not sound like you — “The second item is not settled; mark it as pending and drop the client name” — and ask for a new version.

What counts as success

Material you supplied shows up in the result, instead of a generic template.
A requirement you stated explicitly, such as leading with the conclusion, is visible in the result.
After one change you get a new version, rather than having to rewrite the whole thing yourself.

If one of these does not hold, write down your system, architecture, and version, plus the error text with personal details and credentials removed.

Where to get help

Install, launch, and connection problems: the LinX issue tracker. Include your system and architecture, the version, and a redacted error.
To understand how LinX works first: the LinX page.
To know where your data goes after installation: Storage, access, and migration.

Self-host Xpod

Xpod is the layer that stores data and serves APIs. It runs on your own machine or server, so prepare the runtime and its dependencies before you start.

Every command and configuration name below is quoted from the official README and repository files. We quote them and have not run a deployment, so treat the repository’s current version as the source of truth.

What you need

The official README states:

Bun 1.3+. When building from source, Bun is the main package manager and task runner.
Node.js 22+. If you only consume the published npm package, Node is enough at runtime.
The ABI note in the README gives the Node range as >=22 <27. Non-interactive shells, CI, and editor tasks may pick a different node from PATH, so check the version before starting.

Two deployment profiles (the README’s “Deployment Profiles”):

local: SQLite plus local disk. No Redis or MinIO required. A good fit for personal use, local development, and local app integration.
cloud: PostgreSQL, MinIO, and Redis. The README describes this profile as hosted, multi-user deployment with quota and usage infrastructure, plus node coordination, DNS, and reachability support.

Prepare the configuration

Install dependencies and build:
```
bun install
bun run build
```

Copy the environment template:

# local mode
cp example.env .env.local

# cloud mode
cp example.env .env.cloud

The variable names come from example.env in the repository. Names that appear in the README include XPOD_DEFAULT_* (default quota settings). We have not verified the values or the conditions attached to them, so read the official files and decide for your own deployment.
Run the ABI check first, to avoid native module errors caused by a mismatched Node version:
```
nvm use
bun run check:abi
```

Start it

Local mode:

bun run local

The README says to visit http://localhost:3000/ after startup.

Cloud mode:

bun run cloud

The README also documents single-file packaging:

# self-extracting launcher, output at .artifacts/xpod-single.cjs
bun run build:single:standalone
node .artifacts/xpod-single.cjs --mode local

# Bun native binary, output at dist/xpod-bun
bun run build:single:bun
dist/xpod-bun --mode local --port 5710

The README adds that on supported Unix platforms, npm install @undefineds.co/xpod can resolve a matching optional platform package for the native xpod binary.

Check that it is up

The README’s library-mode example uses /service/status to tell whether the runtime is available: a successful response (the example checks response.ok) means it is up. In local mode you can open http://localhost:3000/ first and then check that path.
Sign-in and identity: Xpod keeps Pod resources, WebID identity, and access control at the core. The README does not walk through creating the first account or signing in for the first time; check the Xpod repository’s documentation directory for the matching material. We have not run it, so we cannot confirm this step for you.

Where data lives and how to back it up

local profile: data lives in a SQLite file and on local disk. Backing up means backing up those two things. The exact paths come from your configuration; the README does not hard-code them.
cloud profile: PostgreSQL and MinIO carry persistence, and Redis handles coordination. The README describes the dependency set but does not give backup steps, so we are not going to invent backup commands. Before going live, decide how the database and object storage are backed up, following the official deployment documentation.

Common errors and official troubleshooting

Native module errors or a NODE_MODULE_VERSION mismatch: usually the wrong Node version. Follow the README and reinstall under the same Node major:
```
nvm use
bun install --force
```
A command is missing or behaves oddly: confirm that node on your PATH is within >=22 <27 and that Bun is 1.3+.
More on profiles and dependencies: docs/deployment-modes.md.
Anything else: the Xpod issue tracker.

To compare the hosted and self-hosted options first, see the Xpod page. Storage locations, access, and migration are covered in Storage, access, and migration.