Install engrams with a coding agent
Exact steps, checks, and stop conditions for a coding agent that installs engrams on one machine.
This page is for a coding agent, such as Claude Code, Codex, or Cursor, that a person asked to install engrams. Every step has a command and a check. Do the steps in order, and do not go to the next step until the check passes. A person can read it too; it is the same install as Run engrams locally, written for a machine to follow.
The result is the whole engrams stack on this machine: Postgres, a container registry, a blob store emulator, the control plane, a host agent, and the dashboard, with one enabled image and one test session that ran a command. It is for evaluation, not production. For a production install in a cloud account, stop and give the person Deploy to your cloud: it creates cloud resources and needs their decisions.
Rules for the agent
Section titled “Rules for the agent”- Do not create, guess, or copy model API keys. The last step asks the person for one.
- Do not run
sudowithout asking the person. Group changes such as adding the user tokvmneed their approval. just devruns until it is stopped. Start it as a background process and keep its log.- The first start compiles Rust and can take 10 to 20 minutes. A long wait is not a failure. Read the log before you decide that something is stuck.
1. Check the machine
Section titled “1. Check the machine”engrams runs on macOS on Apple Silicon and on Linux (x86_64 or arm64). Windows is not supported; use WSL 2 with a Linux distribution.
uname -smdocker info --format '{{.ServerVersion}}'Check: uname prints Darwin arm64, or Linux with x86_64 or aarch64. docker info
prints a version. If docker info fails, Docker is not running: ask the person to start Docker
Desktop, OrbStack, or Colima.
On Linux, check whether sessions can use Firecracker:
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo KVM-OK || echo KVM-NOKVM-NO is not a stop. The stack still runs, but sessions run as plain subprocesses with no
isolation. Tell the person, and say that adding their user to the kvm group fixes it.
2. Get the source and the toolchain
Section titled “2. Get the source and the toolchain”git clone https://github.com/cortexapps/engrams.gitcd engramscommand -v nix && echo NIX-OK || echo NIX-NOWith NIX-OK, run every later command inside the pinned toolchain. Put nix develop -c in
front of each one, for example nix develop -c just bootstrap. The first nix develop
downloads the toolchain and takes several minutes.
With NIX-NO, install the toolchain. On macOS:
# Rust from https://rustup.rs. The repository's rust-toolchain.toml picks the version.rustup target add aarch64-unknown-linux-muslbrew install just tilt-dev/tap/tilt jq squashfs protobuf pkg-config openssl node pnpm bunbrew install FiloSottile/musl-cross/musl-cross --with-aarch64xcode-select -pOn Linux you need Rust from rustup, Docker, just, tilt, jq, and bun.
Check:
just --version && tilt version && bun --version && cargo --versionEach command prints a version.
3. Create the local key and fetch the guest kernel
Section titled “3. Create the local key and fetch the guest kernel”just bootstrapjust pull-kernelCheck: both exit with code 0, and .env contains ENGRAM_KEK_MASTER_KEY. These steps run
once per machine. Running them again is safe.
4. Start the stack
Section titled “4. Start the stack”Start it in the background and write its log to a file:
mkdir -p varnohup just dev > var/just-dev.log 2>&1 &Wait until the orchestrator answers and the local admin key exists:
until curl -fsS http://127.0.0.1:8787/healthz > /dev/null && [ -s var/dev-api-key ]; do sleep 15donecurl -fsS http://127.0.0.1:8787/healthzCheck: the last command prints a JSON body with "ok":true. Put a limit of 30 minutes on the
wait. If the limit passes, read var/just-dev.log, and run tilt get uiresource to see which
resource failed. tilt logs <resource> prints the log of one resource.
The first lines of the log say which backend the stack picked: Firecracker when /dev/kvm is
usable, Apple Virtualization on an Apple Silicon Mac, subprocesses otherwise.
5. Enable the demo image
Section titled “5. Enable the demo image”just bake-demo-enableThis builds the image in deploy/demo/, pushes it to the local registry as
localhost:5001/demo:warm-1, enables it, and waits while engrams captures its base snapshot.
It also builds the engrams CLI to target/debug/engrams.
Check: the command exits with code 0. A non-zero exit prints the failing stage and the end of its output.
6. Prove that a session runs
Section titled “6. Prove that a session runs”Start a session with no agent, run a command in it, and delete it:
export ENGRAMS_URL=http://127.0.0.1:8787export ENGRAMS_API_KEY="$(cat var/dev-api-key)"SID=$(target/debug/engrams session create --image localhost:5001/demo:warm-1 --dev-vm)target/debug/engrams session exec "$SID" 'echo engrams-ok; uname -a'target/debug/engrams session delete "$SID"Check: session exec prints engrams-ok and exits with code 0. The install is complete. This
check needs no model key, because --dev-vm starts the VM with no agent in it.
7. Hand off to the person
Section titled “7. Hand off to the person”Tell the person these things:
- The dashboard is at http://localhost:5173. Registration is open in the local stack, so they can create an account there.
- To let an agent work, they add a model credential in the dashboard under Settings: their
Claude Code token, or an org secret named
ANTHROPIC_API_KEY(orCODEX_API_KEYfor Codex). - Your first session shows how to start an agent, watch it, and see it snapshot and resume.
just dev-downstops the stack and keeps its data. The nextjust devstarts where it stopped.
If a step fails
Section titled “If a step fails”| Symptom | What to do |
|---|---|
docker info fails |
Docker is not running. Ask the person to start it. |
just: command not found with Nix |
Put nix develop -c in front of the command. |
| The health wait passes 30 minutes | Read var/just-dev.log and tilt get uiresource; report the failed resource and its log to the person. |
| Port 8787, 5173, or 10350 is in use | Another stack, or an old one, is running. Run just dev-down, or ask the person what owns the port. |
bake-demo-enable fails at capture |
Read the printed stage. On Linux without KVM, check that the log says subprocesses were picked. |
| Sessions run without isolation | /dev/kvm is not usable by this user. Tell the person; do not fix group membership without approval. |