the-ai-alliance/semiont/semiont-local

You are helping a user get Semiont running on their own machine. The semiont launcher is a single static binary that drives their container runtime and pulls the published service images. It needs no source checkout and no Node.js.

What they need

• A container runtime: Apple Container, Docker or Podman. The launcher detects which. Check with container --version, docker --version or podman --version.
• The launcher: from Homebrew on macOS and Linux. On Windows, the GitHub Release carries a zip holding semiont.exe; see Semiont on Windows.
• Inference: an Anthropic key, or Ollama for a model that runs on the machine and needs no key.

Fastest path

brew install the-ai-alliance/semiont/semiont

With Anthropic, register where the key comes from. The launcher stores the pointer, never the key, and reads it at every start. Exporting ANTHROPIC_API_KEY in the shell works too, and wins over a registered pointer.

semiont settings secret set ANTHROPIC_API_KEY op://YourVaultName/Anthropic/credential

Create a knowledge base in a new directory. --domain is its permanent identity, stamped into its event log, and has no default. Use --inference ollama for the local model.

mkdir my-kb && cd my-kb
semiont init --yes --domain example.com:my-kb --inference anthropic

Start the stack, then create a person who can sign in:

semiont start

semiont useradd --email you@example.com

useradd prompts for the password. Open http://localhost:3000: the Browser lists the knowledge bases the launcher runs, and signing in happens at the knowledge base's identity provider.

To run a knowledge base that already exists, clone it and run semiont start from inside it.

For the launcher's own verbs (semiont browse, semiont mark, semiont yield --upload), sign the launcher in once:

semiont login

Common operations

Run each from the knowledge base's directory.

semiont --help lists every verb, and semiont <verb> --help its options.

Where things are

Everything derived from the event log (the database, the graph, the vectors, the job queue) is kept outside the knowledge base, in a directory the launcher keeps for it. semiont status --verbose lists those directories and their sizes. The secrets the launcher generates for a stack are kept there too, or in 1Password when semiont settings secret-store names a vault.

Guidance for the AI assistant

• Check what they need first. The usual failures are a container runtime that is not running, and an inference key the start cannot read.
• `semiont status` is the first diagnostic. It names the service that is unhealthy; semiont logs --service <name> says why.
• Configuration is in the knowledge base, in the documents under .semiont/stack/. semiont start --list-configs shows the Inference documents it has. Each service's own configuration is written from them and mounted into its container at /etc/semiont/<service>.json; there is no such file on the host to edit.
• A change of configuration takes a restart: semiont stop, then semiont start.
• The knowledge base is a git repository. Its resources, .semiont/config.yaml, .semiont/stack/ and .semiont/events/ are committed. Secrets never are: a document names the environment variable that holds one.
• `semiont` comes from Homebrew or the GitHub Release, never from npm. If which semiont resolves to an npm install, that copy is shadowing the launcher: uninstall it.
• Going further. Running knowledge bases on your computer covers ports, the Browser and local-network access; Configuration covers the documents; Troubleshooting covers what goes wrong.