SDK — Getting Started

This page walks you through authoring your first biome — Xema's name for an installable software bundle. You will install the xema CLI, scaffold a biome, install it into a local Xema instance, and invoke its first capability — end-to-end, in under five minutes, with no monorepo and no package manager.

Prerequisites

A machine running macOS, Linux, or Windows.
One of:
- Homebrew on macOS/Linux (brew), or
- Node.js 18+ with npm available, or
- A direct GitHub Releases download for your platform.

No clone, no package manager, no pre-existing Xema install required. The CLI bootstraps a local instance for you.

1. Install the `xema` CLI

Pick the distribution that fits your platform.

bash

1# Homebrew (macOS, Linux)
2brew tap xema-dev/xema
3brew install xema
4
5# npm (any platform)
6npm install --global @xemahq/xema
7
8# Or download a standalone binary from the GitHub Releases of xema-community

Verify:

bash

1xema --version

See the CLI page for every command and every install variant.

2. Start a local Xema

bash

1xema up

This boots the Xema platform on your machine with one command. Preview what it will start with xema up --dry-run, and stop it with xema down.

Leave the platform running. Open a second terminal for the rest of the walkthrough.

3. Scaffold a biome

bash

1xema biome scaffold hello-xema
2cd hello-xema

xema biome scaffold produces a self-contained directory:

text

1hello-xema/
2├── xema-biome.json             # the manifest
3├── contributions/
4│   └── hello.greet.contribution.json
5├── agents/
6│   └── greeter.agent.yaml
7├── README.md
8└── .gitignore

Open xema-biome.json to see the generated manifest. Open contributions/hello.greet.contribution.json to see the one example capability the scaffolder included.

4. Install the biome

bash

1xema biome install ./

The install command runs the full install flow against your local xema up instance:

Parses and validates the manifest.
Computes the permission digest (one capability in this case: hello:greet@1).
Records the install grant in the local authorization store.
Registers the capability with the local router.

Sandbox is the default environment for a freshly scaffolded biome. You can move it to org later via the Org Settings UI.

5. Invoke the capability

hello:greet@1 is an illustrative ref invented for this tutorial; no platform service produces it.

bash

1xema run hello:greet@1 --name Ada

Expected output:

jsonc

1{ "message": "Hello Ada from my first Xema biome" }

That is the end-to-end loop: scaffold, install, invoke. The same loop works against a single-VM self-host (xema up) and against a multi-node cluster (helm install xema-community) without code changes.

6. Iterate

Edit agents/greeter.agent.yaml, edit the contribution manifest, add new contributions to contributions/. Then:

bash

1xema biome validate        # pre-boot checks: manifest, agents, contributions, skills, workflows
2xema biome lint            # boundary + manifest + capability-call audit
3xema biome install ./      # reinstall over the previous version
4xema run hello:greet@1 --name Ada

Two checks run on every install:

Manifest schema — the manifest is parsed by the Zod schema. Unknown closed-set values are rejected.
Boundary check — your biome may only depend on its own files and on published @xemahq/* kernel packages.

7. Publish (when you are ready)

When the biome is ready to share:

bash

1xema biome publish ./

The publish command builds an OCI artifact, signs it, and pushes it to the configured registry. From there, anyone can install it with:

bash

1xema biome install oci://<registry>/<your-org>/hello-xema:1.0.0

See SDK / Publishing for the full publish flow and registry options.

SDK — Getting Started

Prerequisites

1. Install the xema CLI

2. Start a local Xema

3. Scaffold a biome

4. Install the biome

5. Invoke the capability

6. Iterate

7. Publish (when you are ready)

What to read next

1. Install the `xema` CLI