# Run engrams locally

> Start the whole stack on one machine and enable the demo image.

Source: https://engramsfactory.com/docs/getting-started/local-quickstart/

This page runs every part of engrams on one machine so you can see a session boot, stream,
and snapshot. It is not a production shape. On an Apple Silicon Mac the sessions run under
Apple's Virtualization framework; on a Linux machine with `/dev/kvm` they run under
Firecracker; anywhere else they run as plain subprocesses with no isolation at all.

## Prerequisites

If you have Nix, `nix develop` in the repository gives you the pinned toolchain and you can
skip to the next section. If you use direnv, `direnv allow` once and the shell activates on
its own.

Without Nix, on macOS:

```sh
# Rust, per rust-toolchain.toml (https://rustup.rs), then the guest target:
rustup target add aarch64-unknown-linux-musl
brew install just tilt-dev/tap/tilt jq squashfs protobuf pkg-config openssl node pnpm bun
brew install FiloSottile/musl-cross/musl-cross --with-aarch64
```

You also need Docker Desktop, OrbStack, or Colima for the registry and Postgres containers,
and the Xcode Command Line Tools for `codesign`.

On Linux you need the same Rust toolchain, Docker, `just`, `tilt`, `jq`, and `bun`. If you
want Firecracker rather than subprocesses, check that you can use KVM:

```sh
[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo OK || echo FAIL
```

`FAIL` usually means your user is not in the `kvm` group. engrams falls back to subprocesses
in that case and says so when it starts.

## Start the stack

From the repository root:

```sh
git clone https://github.com/cortexapps/engrams.git && cd engrams
just bootstrap     # writes a local master key to .env (once)
just pull-kernel   # fetches the guest kernel for this machine's backend (once)
just dev           # starts everything under Tilt
```

`just dev` picks the backend for this machine on its own: Firecracker when `/dev/kvm` is
usable, Apple Virtualization on an Apple Silicon Mac, subprocesses otherwise. It brings up
Postgres, a local container registry, and the blob-store emulator in Docker, then the
coordinator, the host agent, the orchestrator, and the dashboard as local processes.

Tilt's status page is at http://localhost:10350 and shows every process and its log. The
dashboard is at http://localhost:5173. Open it and create an account; registration is open in
the dev stack, and there is nothing to configure.

## Enable the demo image

In a second terminal:

```sh
just bake-demo-enable
```

This 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.
The capture boots a VM, runs the image's warm-up command, and freezes the result; it takes a
minute or two the first time. The command exits non-zero if the capture fails, with the
failing stage and the last of its output.

## Give the agent a key

The Claude Code harness needs a credential. In the dashboard, open Settings and either
connect your Claude Code token, which authenticates sessions you start yourself, or add an org
secret named `ANTHROPIC_API_KEY`, which authenticates sessions started from the CLI, Slack,
and other automations. For Codex the org secret is `CODEX_API_KEY`, and the personal path is
a ChatGPT connection under Settings → Credentials.

Now you have a running stack with one enabled image. [Your first session](https://engramsfactory.com/docs/getting-started/first-session/)
starts an agent in it.

## Stop and reset

`just dev-down` stops every process and container and leaves the data in place, so the next
`just dev` starts where you left off. `just clean-var` removes the local sandbox working
directories and snapshots, and `just db-reset` destroys and recreates the dev database.
