{entry.data.description}
} ) } + + diff --git a/site/src/content/docs/docs/getting-started/faq.md b/site/src/content/docs/docs/getting-started/faq.md index e4a9b3217..cefa89966 100644 --- a/site/src/content/docs/docs/getting-started/faq.md +++ b/site/src/content/docs/docs/getting-started/faq.md @@ -66,6 +66,8 @@ migrating a session. A cold start from an image's base snapshot is under a secon pre-warmed pool. These are the numbers from the reference deployment; measure your own fleet before you promise them to anyone. -## What is the license? +## Is it open source? -engrams is free software under the GNU Affero General Public License v3.0. +Yes. The whole system is open source on [GitHub](https://github.com/cortexapps/engrams): the +control plane, the host agent, the dashboard, the CLI, and the Firecracker fork. You can read, +change, and run every line. diff --git a/site/src/content/docs/docs/getting-started/install-with-an-agent.md b/site/src/content/docs/docs/getting-started/install-with-an-agent.md new file mode 100644 index 000000000..db79a34ba --- /dev/null +++ b/site/src/content/docs/docs/getting-started/install-with-an-agent.md @@ -0,0 +1,169 @@ +--- +title: Install engrams with a coding agent +description: Exact steps, checks, and stop conditions for a coding agent that installs engrams on one machine. +sidebar: + order: 2 +--- + +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](../local-quickstart/), 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](../../guides/deploy-overview/): it creates cloud resources and needs +their decisions. + +## Rules for the agent + +- Do not create, guess, or copy model API keys. The last step asks the person for one. +- Do not run `sudo` without asking the person. Group changes such as adding the user to `kvm` + need their approval. +- `just dev` runs 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 + +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. + +```sh +uname -sm +docker 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: + +```sh +[ -r /dev/kvm ] && [ -w /dev/kvm ] && echo KVM-OK || echo KVM-NO +``` + +`KVM-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 + +```sh +git clone https://github.com/cortexapps/engrams.git +cd engrams +command -v nix && echo NIX-OK || echo NIX-NO +``` + +With `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: + +```sh +# Rust from https://rustup.rs. The repository's rust-toolchain.toml picks the version. +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 +xcode-select -p +``` + +On Linux you need Rust from rustup, Docker, `just`, `tilt`, `jq`, and `bun`. + +Check: + +```sh +just --version && tilt version && bun --version && cargo --version +``` + +Each command prints a version. + +## 3. Create the local key and fetch the guest kernel + +```sh +just bootstrap +just pull-kernel +``` + +Check: 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 + +Start it in the background and write its log to a file: + +```sh +mkdir -p var +nohup just dev > var/just-dev.log 2>&1 & +``` + +Wait until the orchestrator answers and the local admin key exists: + +```sh +until curl -fsS http://127.0.0.1:8787/healthz > /dev/null && [ -s var/dev-api-key ]; do + sleep 15 +done +curl -fsS http://127.0.0.1:8787/healthz +``` + +Check: 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