Getting Started

Your first half hour as a platform developer: build the core CLI, bring up the local dev stack, sign in to GitHub, and run a first coding session that changes nothing.

Before you start

CORE is one of several sibling repositories. Its Go module lives in grpc/, and grpc/go.mod resolves the shared libraries through relative replace directives:

github.com/org-runink/inference => ../../inference
github.com/org-runink/mesh      => ../../mesh
github.com/org-runink/security  => ../../security
github.com/org-runink/store     => ../../store
github.com/org-runink/tts       => ../../inference/tts

So a normal build expects inference, mesh, security and store checked out next to your core checkout. grpc/vendor/ is committed, so the CLI also builds offline with -mod=vendor when the siblings are absent.

Sibling checkouts are shared state. If a build fails with a missing symbol from security or store, the sibling is probably on someone else’s branch. Do not switch it. Use a detached worktree of the sibling plus a GOWORK file outside the repo instead.

Build the CLI

The core CLI (Cobra + Viper) replaced the Makefile; there is no Makefile.

cd grpc
go build -o core ./cmd/core          # with the siblings checked out
GOFLAGS=-mod=vendor go build -o core ./cmd/core   # or from the committed vendor tree
./core --help

go run ./cmd/core <command> works too. Config resolves from ./core.yaml or ~/.core.yaml, then CORE_* environment variables, then flags (see CLI Reference).

Run the apps locally

core dev up runs the apps natively (no VMs, no images, no sudo in the run loop): both app backends, the shared inference server (mistralrs-server), the Flutter UIs, and the security stack (envelope encryption, pipe mesh, rotating raft mTLS, eBPF).

core dev up            # everything (the default is all)
core dev up face       # one app
core dev down          # stop everything

Things core dev up needs, from internal/devstack/devstack.go:

The app repos. It reads the environment variables FACE_REPO and PULSE_REPO (defaults ../face and ../pulse), not the CLI’s --face-repo flag.
A mistralrs-server binary and GGUF weights under ../pulse/grpc/agents. Without them it logs mistralrs-server binary or model not found under …/grpc/agents — apps spawn their own if configured. and carries on.
Flutter, for the console UI. Without it you see console skipped (flutter not found).

Run state goes under .dev/: logs are .dev/*-{backend,frontend}.log, PIDs are .dev/<name>.pid, and ports are written to .dev/ports.env. On first run it mints a dev mesh CA and generates a per-machine envelope KEK at .dev/secrets/CORE_ENVELOPE_KEK with crypto/rand (delete that file to rotate it).

Get portless URLs (one-time sudo)

core dev hosts         # map *.runink.org.local → 127.0.0.1 and grant the gateway :443
core dev secure        # optional: add the single mTLS SNI gateway

The success banner ends with CORE dev up (envelope + pipe-mesh + rotating raft mTLS + eBPF + diagnostics/MCP + self-heal). followed by the per-app URLs. The CORE console runs as a shell only (/api/* needs the operator and a cluster).

Sign in to GitHub

core auth login        # GitHub Device Flow, cached in ~/.core/auth.json
core auth status

core session uses this token by default. It switches to GitHub App installation tokens only when CORE_GH_APP_ID and CORE_GH_APP_PRIVATE_KEY (or CORE_GH_APP_PRIVATE_KEY_FILE) are set, which is meant for unattended runs.

Run a first coding session, safely

core session start --repo org-runink/core \
  --prompt "Explain what internal/session/tools.go confines, then call done" \
  --dry-run

--dry-run runs the full loop but never pushes or opens a PR; it prints the diff instead. With no --inference-url, the CLI probes local endpoints and logs using inference endpoint … (auto-discovered). Every run_shell and browser_* call stops at a [y/N] prompt. See Coding Sessions.

Where the DevEx pages are

In the console, open the DevEx group in the rail. Each page can be deep-linked as ?tab=<name> (for example ?tab=gitops). The page-by-page reference is Console Pages, and the whole rail is mapped in the console map.

Deploying to a cluster instead

core dev is the local run loop. Deploying to k0s is a different layer: core deploy platform|face|pulse|all with --mode local (multipass VMs) or --mode onhost (the single-node k0s on the box). See CLI Reference.

CLI Reference