Building And Deploying

​

What A Build Compiles

• The repository pins Rust 1.94.1 in rust-toolchain.toml; make install-build-deps installs exactly that toolchain into a checkout. The published crates declare rust-version = "1.94.0", so cargo install rkat needs Rust 1.94 or newer.
• The default feature set needs a C compiler and libc headers (bundled SQLite and a few other C sources compile through the cc crate) and nothing else. TLS is rustls; no OpenSSL development package is required and the release gate rejects binaries that link one.
• cmake is needed only by the optional live-webrtc feature of the meerkat facade and meerkat-rpc crates (meerkat-live webrtc, bundled Opus through audiopus_sys). rkat has no such feature, and no shipped binary enables it by default, so a cargo install of any of them never compiles it.

​

Build Cost

cargo build --locked -p rkat --release   # same package and profile as `cargo install rkat`

• The largest single crate is the floor, and only opt-level = 0 moves it. Even with CARGO_BUILD_JOBS=1, the build needs as much memory as its biggest rustc process. In both runs above that was meerkat-mob at ~11 GiB: going from opt-level = 3 to 1 halved the aggregate peak, the rkat crate, and meerkat-machine-schema, but left meerkat-mob where it was. A third run (the same rkat build with the low-memory profile plus meerkat-mob pinned to opt-level = 0) brought meerkat-mob down to ~6.3 GiB, after which the largest process is meerkat-runtime at ~7.4 GiB. Below that, the levers are the feature set (dropping mob removes the crate), swap, and the prebuilt binaries.
• Aggregate memory scales with the job count. Cargo runs up to one rustc per core. The aggregate peaks above happened while four or five large first-party crates were compiling at once; with N jobs, budget for the N largest crates that can be in flight together. meerkat-mob, meerkat-runtime, and meerkat-machine-schema did overlap in the default build, and that overlap produced its peak.
• Wall time scales with cores only up to the serial tail. The hundreds of small dependencies compile in parallel in the first few minutes, but the large first-party crates depend on each other, and the final rkat crate compiled alone for roughly the last third of the wall time. A 4-core cloud VM should expect a few times the wall time above, and the tail does not shrink with more cores. cargo install also has no warm cache to reuse, so every install is a cold build.
• Disk is transient for cargo install. The temporary target directory is deleted after the binary is installed, but it must fit while the build runs. A checkout that keeps its target/ needs the full figure per profile.

​

Lowering Memory

​

Where profile settings come from

• The Meerkat workspace ships no [profile.release], so its own release builds run at Cargo’s defaults (opt-level = 3, codegen-units = 16, lto = false, debug = false) except where a lane injects pins.
• Even if it did, that would not reach you. cargo install rkat unpacks the published rkat crate as the root of its own temporary workspace; the repository’s root Cargo.toml is not part of that crate. A downstream binary that depends on meerkat = "=0.8.32" is likewise governed by its own root manifest, never by Meerkat’s.

​

Low-memory profile

# .cargo/config.toml in the directory you run `cargo install` from,
# or ~/.cargo/config.toml. Library embedders: put the same tables in the
# root Cargo.toml of your own binary crate instead.

[profile.release]
opt-level = 1        # cuts LLVM's working set on the generated crates the most
codegen-units = 16   # Cargo's release default; read the notes before lowering it
lto = false          # Cargo's default; never enable "thin" or "fat" on a small host
debug = false
strip = "symbols"    # smaller output; no effect on compile-time memory

# Generated machine catalog: data-shaped code that gains nothing from
# optimization. The release lane pins this on its 16 GB runners.
[profile.release.package.meerkat-machine-schema]
opt-level = 0

[profile.release.package.meerkat-mob]
opt-level = 0

[profile.release.package.meerkat-machine-schema]
opt-level = 0

[profile.release.package.meerkat-runtime]
opt-level = 1

[profile.release.package.meerkat-mcp]
opt-level = 1

CARGO_BUILD_JOBS=2 CARGO_PROFILE_RELEASE_OPT_LEVEL=1 \
  cargo install rkat --locked \
    --config 'profile.release.package.meerkat-machine-schema.opt-level=0'

​

What each lever does

• CARGO_BUILD_JOBS (or -j) caps the number of concurrent rustc processes. Aggregate memory is the sum of the compilers running at once, so this is the first lever on any memory-limited host. Wall time rises roughly in proportion.
• opt-level: going from 3 to 1 removes most of LLVM’s expensive passes. Measured on the crates whose peak is in LLVM, it halved the rkat crate (~10.1 to ~4.8 GiB) and, together with the opt-level = 0 pin, meerkat-machine-schema (~9.4 to ~4.8 GiB), and it cut the whole build’s wall time from ~25 min 29 s to ~19 min 6 s. It did not move meerkat-mob; only opt-level = 0 did (~11.5 to ~6.3 GiB). The runtime cost of 1 is modest for an agent host that spends its time waiting on network I/O. opt-level = 0 is free for meerkat-machine-schema because it is a generated catalog, not hot code; on meerkat-mob it is a real trade.
• codegen-units: LLVM optimizes a crate’s codegen units in parallel, bounded by your core count, so a crate split into 16 units can hold 16 LLVM contexts at once. Lowering it reduces that per-crate parallelism at the cost of a longer compile for that crate, and codegen-units = 1 also widens inlining scope, which can raise memory for the largest crates. Measure on your host before changing it; the release lane leaves it at 16.
• lto: leave it at the default false. "thin" or "fat" LTO pulls the whole dependency graph into one optimization pass at link time and multiplies link-stage memory.
• Features: meerkat-cli/Cargo.toml lists the subsystems behind rkat’s default features (mob, rpc-surface, openai-realtime, comms, schedule, workgraph, mcp, skills, storage backends, providers). A narrower --no-default-features --features ... build compiles fewer crates; dropping mob removes meerkat-mob, the crate that sets the memory floor above, along with meerkat-mob-mcp and meerkat-mob-pack. The repository’s surface feature matrix (scripts/run-surface-feature-matrix, behind make test-feature-matrix-surface) keeps three reduced rkat combinations compiling: --no-default-features --features session-store, session-store,mcp, and session-store,comms,mcp,workgraph. Other subsets are not exercised, so check that yours builds before relying on it. Reduced builds are source builds only; no reduced binaries are published (see the note under Homebrew Tap).

​

Containerizing The Binaries

# syntax=docker/dockerfile:1.7

# One Debian release for both stages, so the glibc rkat links against in the
# build stage is the glibc present in the runtime stage.
ARG DEBIAN_RELEASE=bookworm

FROM rust:1.94-${DEBIAN_RELEASE} AS build
ARG RKAT_VERSION=0.8.32
# Low-memory defaults for a 16 GB builder; remove both on a large build host.
# Under 16 GB, also add: --config 'profile.release.package.meerkat-mob.opt-level=0'
ENV CARGO_BUILD_JOBS=2 \
    CARGO_PROFILE_RELEASE_OPT_LEVEL=1
RUN cargo install rkat --version "=${RKAT_VERSION}" --locked --root /opt/rkat \
      --config 'profile.release.package.meerkat-machine-schema.opt-level=0'

FROM debian:${DEBIAN_RELEASE}-slim
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates \
    && rm -rf /var/lib/apt/lists/*
COPY --from=build /opt/rkat/bin/rkat /usr/local/bin/rkat
ENV RUST_LOG=warn
WORKDIR /data
ENTRYPOINT ["rkat"]

• ARG DEBIAN_RELEASE is declared before the first FROM and used in both FROM lines, so the two stages cannot drift apart when someone bumps one of them. rust:1.94-bookworm matches the pinned toolchain family.
• --locked builds with the Cargo.lock shipped inside the rkat crate, so the container compiles the dependency set the release was tested with.
• To build from a checkout instead of crates.io (unreleased commits, local patches), replace the RUN cargo install line with WORKDIR /src, COPY . ., and cargo build --locked -p rkat --release, and copy /src/target/release/rkat (the build stage above sets no WORKDIR, so without that line the checkout lands in /). The repository’s own examples/035-mdm-tux-rs/Dockerfile does exactly that for the example’s binaries, with the same rust:1.94-bookworm build stage and debian:bookworm-slim runtime stage.
• The companion surfaces are separate crates with the same shape: cargo install meerkat-rpc (binary rkat-rpc), meerkat-rest (rkat-rest), and meerkat-mcp-server (rkat-mcp).
• rkat resolves project realm state under .rkat/ in its working directory and the global realm’s config under ~/.rkat/ (see Configuration); mount a volume at /data, and point HOME at persisted storage if the global realm matters, so state outlives the container.

FROM debian:bookworm-slim
ARG RKAT_VERSION=0.8.32
ARG RKAT_TARGET=x86_64-unknown-linux-gnu
RUN apt-get update \
    && apt-get install -y --no-install-recommends ca-certificates curl \
    && rm -rf /var/lib/apt/lists/* \
    && curl -fsSL "https://github.com/lukacf/meerkat/releases/download/v${RKAT_VERSION}/rkat-${RKAT_VERSION}-${RKAT_TARGET}.tar.gz" \
       | tar -xz -C /usr/local/bin \
    && rkat --version

​

Where The Prebuilt Binaries Come From

• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu
• aarch64-apple-darwin
• x86_64-apple-darwin
• x86_64-pc-windows-msvc

gh attestation verify rkat-0.8.32-x86_64-unknown-linux-gnu.tar.gz --repo lukacf/meerkat

​

Linux glibc floor

1. Any versioned glibc symbol reference is newer than the declared floor (MEERKAT_GLIBC_FLOOR=2.31).
2. The binary has a dynamic NEEDED entry on libssl or libcrypto. All first-party TLS is rustls, so an OpenSSL dependency means a crate regressed into a native-TLS stack.

​

Other platforms

​

MobKit

​

See Also

• CD and distribution for the release pipeline, Homebrew tap, SDK bootstrap, and credentials.
• Build And CI for the contributor build, test, and BuildBuddy lanes.
• Quickstart for the featured install paths.