# engrams > engrams is the open source, self-hosted software factory. It runs Claude Code, Codex, or your own coding agent in a Firecracker microVM in your own cloud, starts work from a prompt, a schedule, a pull request, a Slack thread, or a webhook, and snapshots idle sessions to object storage. It is an open source alternative to Devin and Factory.ai, made by Cortex. --- # What is engrams > Sessions, tasks, profiles, images, harnesses, and hosts, and what happens to a session over its life. Source: https://engramsfactory.com/docs/getting-started/overview/ engrams is the open source, self-hosted software factory. It runs AI coding agents in isolated microVMs on your own infrastructure, as an open source alternative to Devin and Factory.ai. It gives people one place to direct their work: start a task, inspect its changes, and continue the conversation from the dashboard or Slack. Turn repeat work into an automation that starts on a schedule or an event. Each agent runs in its own Firecracker microVM. engrams supplies the environment, controls access to connected tools, and snapshots idle sessions so work can continue later. Claude Code and Codex ship as harnesses; custom harnesses use the same session controls. ## The objects A **session** is one running sandbox. It pairs an image with an optional harness and lives in one microVM on one host. Everything else is defined in terms of sessions. An **image** is a plain OCI image you build with `docker build` and push to any registry. The contract is any Linux image with `/bin/sh`. You enable an image once; engrams turns it into a chunked root filesystem and captures a base snapshot on the fleet, and sessions boot from that snapshot. Runtime settings that are not part of the image, like environment variables, memory, and a warm-up command, are entered when you enable it. A **harness** is the agent runtime that runs inside the VM. Claude Code and Codex ship as harnesses. A harness is never baked into your image: the host stages it as a read-only bundle and mounts it into the VM at boot, so upgrading the agent does not mean rebuilding images. A **profile** is an admin-curated bundle of session settings: the image, the repositories to clone, environment variables, the egress policy, which integrations the agent may use, and which skills and session apps it gets. Profiles are how an organization hands developers a known-good configuration. The profile editor shows, beside the form, exactly what a session launched from it is granted: the image, the powers, the hosts it can reach, and how each credential is delivered. (Image: The profile editor, with the session policy panel listing powers, reachable hosts, and credentials) A **task** is one unit of agent work. It starts from a profile, gets a prompt, and owns one or more sessions. Tasks are what you see in the dashboard, in a Slack thread, and in `engrams task list`. An **automation** is a trigger, a tree of blocks, and typed inputs. It starts sessions in response to a schedule, a Slack mention, a pull request, a Linear issue, or a webhook, and every run keeps a step-by-step record. [Pull request review](https://engramsfactory.com/docs/platform/reviews/) and [Slack threads](https://engramsfactory.com/docs/platform/slack-threads/) ship as automations. [Automations](https://engramsfactory.com/docs/platform/automations/) has the whole model. A **host** is a Linux machine with KVM that runs microVMs. Hosts dial the coordinator, report their capacity, and receive sessions. Hosts never need an inbound port. (Image: The Start a task composer: a prompt, a profile, and the harness, route, model, and effort pickers) ## The life of a session A session moves through a small set of states. 1. **Created.** The coordinator has picked a host and the host is booting a VM from the image's base snapshot. 2. **Active.** The in-guest daemon is up and the harness is running. Prompts, commands, and file transfers work. A session reaches this state only after the agent has started, so a command sent to an Active session never races the boot. 3. **Idle.** The agent went quiet for longer than the idle timeout. The host snapshotted the VM's memory and disk into content-addressed chunks and destroyed the VM. The session holds no host resources. 4. **Active again.** The next prompt, command, or event subscription restores the snapshot, on the same host if it still has the chunks cached, and on any other host otherwise. You do not have to know whether a session is live or paused; engrams resumes it for you. Two states are terminal. **Completed** is what you get when you delete a session. **Dead** is what happens when a session's snapshot can no longer be restored, which in practice means the blob store lost the chunks or a hard time limit expired. If a host stops sending heartbeats while a session is Active, the session becomes **HostLost**, and it returns to Idle if a recoverable snapshot exists. ## What survives what | Event | Disk state | Memory state | Conversation log | | -------------------------------------- | ------------------- | ------------------- | ------------------------------ | | Resume on the same host, chunks cached | preserved | preserved | preserved | | Resume on a different host | rebuilt from chunks | rebuilt from chunks | preserved | | Every host lost, blob store intact | preserved | preserved | preserved | | Blob store lost | gone | gone | preserved in Postgres | | Host crash before the first snapshot | gone | gone | up to the last persisted event | The conversation log lives in Postgres, so a session's history outlives its VM in every case. ## What engrams is not - **engrams is not a hosted service.** You run it, in your cloud or on your own hardware. If you want someone else to run the sandboxes, E2B and Modal do that well. - **engrams is not a development environment for people.** Sessions exist for agents. You can open a shell or an IDE into one, but a workspace product for engineers at their editors is what Coder is for. - **engrams is not a container runner.** Production isolation is Firecracker on Linux with KVM. The macOS backend on Apple Virtualization and the process backend exist for development only. - **engrams is not a model provider.** You bring an Anthropic or OpenAI key, or point a harness at a router such as OpenRouter. ## Tested platforms Production runs on Kubernetes with a dedicated node pool that has nested virtualization enabled. That is Intel-only on every managed provider today. | Cloud | Cluster | KVM nodes | | ------------ | ------------ | ---------------------------------- | | Google Cloud | GKE Standard | C3 family (Sapphire Rapids) | | AWS | EKS | m8i (Granite Rapids), or `*.metal` | For development, an Apple Silicon Mac runs sessions under Apple's Virtualization framework, and any Linux machine with `/dev/kvm` runs them under Firecracker. Two limits are worth knowing before you plan a deployment. The CPU platform is a one-way door for snapshots: an image whose base snapshot was captured on a newer CPU never restores on an older one, so a fleet that mixes platforms has to bake images per platform. And the built-in harnesses need a glibc-based image; an Alpine image boots, but the bundled agent binary exits at once and the session never becomes Active. --- # Install engrams with a coding agent > Exact steps, checks, and stop conditions for a coding agent that installs engrams on one machine. Source: https://engramsfactory.com/docs/getting-started/install-with-an-agent/ 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](https://engramsfactory.com/docs/getting-started/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](https://engramsfactory.com/docs/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 ` 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 ```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. 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 Start a session with no agent, run a command in it, and delete it: ```sh export ENGRAMS_URL=http://127.0.0.1:8787 export 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 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` (or `CODEX_API_KEY` for Codex). - [Your first session](https://engramsfactory.com/docs/getting-started/first-session/) shows how to start an agent, watch it, and see it snapshot and resume. - `just dev-down` stops the stack and keeps its data. The next `just dev` starts where it stopped. ## 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. | --- # 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. --- # Your first session > Start an agent from the CLI, watch it work, and see it snapshot and resume. Source: https://engramsfactory.com/docs/getting-started/first-session/ This page assumes a running stack with the demo image enabled, per [Run engrams locally](https://engramsfactory.com/docs/getting-started/local-quickstart/). It uses the CLI because a terminal shows the moving parts; the dashboard does the same things with a form. ## Build the CLI The `engrams` CLI is a single binary built with cargo: ```sh cargo build --profile cli -p engram-cli ``` That leaves `target/cli/engrams`. Put it on your `PATH` or call it by path; the examples below call it by path. ## Point it at the stack The CLI needs a URL and a credential. For scripts, both come from the environment: ```sh export ENGRAMS_URL=http://localhost:8787 export ENGRAMS_API_KEY=$(cat var/dev-api-key) ``` `var/dev-api-key` holds an admin key that `just dev` mints for exactly this purpose. Against a real deployment you would run `engrams auth login` instead, which opens a device-code flow in the browser and stores a personal key in `~/.config/engrams/hosts.json`. The [CLI reference](https://engramsfactory.com/docs/reference/cli/) covers the precedence. ## Start a session ```sh SID=$(target/cli/engrams session create \ --image localhost:5001/demo:warm-1 \ --harness claude \ --prompt "List /workspace and describe what you find.") echo "$SID" ``` The command prints the session id as soon as the coordinator has accepted it. Behind that line, a host restored the image's base snapshot into a fresh VM, the in-guest daemon came up, and the Claude Code harness started with your prompt. Watch the transcript: ```sh target/cli/engrams session logs "$SID" ``` This tails the session's event log: the agent's messages, each tool call as it starts and finishes, and the run's completion. `--since 0` replays from the beginning. The same events are what the dashboard renders, so open the session there too. The right pane has the session's overview, the files it changed with their diffs, a shell into the VM, and diagnostics. (Image: A session in the dashboard with the Changes tab open, listing three changed files) Run a command inside the VM while the agent works: ```sh target/cli/engrams session exec "$SID" 'uname -a; ls /workspace' ``` `session exec` streams stdout and stderr and exits with the remote command's exit code. The dashboard's Shell tab is the interactive version, a terminal in the VM as root. (Image: The Shell tab: a root prompt inside the session's VM) ## Watch it snapshot and resume Leave the session alone. A few minutes after the agent's last event, the idle timeout fires: the host snapshots the VM's memory and disk and destroys it. `session get` shows the session as idle and it holds no host resources. Now send another prompt: ```sh target/cli/engrams session prompt "$SID" "Now write a short README for what you found." ``` The prompt resumes the snapshot, and the agent continues in the same process with the same context, because the memory it had is the memory it gets back. When you are done: ```sh target/cli/engrams session delete "$SID" ``` ## Tasks and profiles `session create` is the admin's escape hatch: it takes a raw image URI and needs no setup beyond an enabled image. Day to day, work starts as a task from a profile: ```sh target/cli/engrams task create --profile backend --prompt "Fix the flaky test in CI" ``` A profile bundles the image, the repositories to clone, environment variables, the egress policy, integration access, and skills, so the person launching a task chooses a name rather than a configuration. Profiles are created in the dashboard under Settings. `engrams profile list` shows the ones you can use. --- # FAQ > Short answers to the questions people ask before they run engrams. Source: https://engramsfactory.com/docs/getting-started/faq/ ## Is it ready for production? It runs one company's production, on GKE, every day. It is also a 0.x project: the wire formats between components change, the API is not versioned yet, and the Firecracker it ships is a fork that is rebased on upstream daily. Plan on upgrading the whole deployment at once, control plane and host fleet together. ## Do I need Firecracker? For production, yes. Production isolation is Firecracker on Linux with KVM, and there is no container mode. Two other backends exist for development: Apple's Virtualization framework on an Apple Silicon Mac, which gives you real microVM isolation on a laptop, and a subprocess backend with no isolation at all for iterating on the orchestration layer. ## Which hosts can run the fleet? Any Linux node with KVM. On managed Kubernetes that means a node pool with nested virtualization, which is Intel-only on every provider today: the C3 family on GKE, and either m8i or bare metal on EKS. Bare metal anywhere works too; the host agent does not care who owns the machine. ## Can I use my own images? Yes. A session image is any Linux image with `/bin/sh`, built with `docker build` and pushed to any registry. There is no build tool to learn and nothing of engrams inside the image. Use a glibc-based image: the bundled agent binaries do not run on Alpine. ## Does anything happen without a person typing a prompt? Yes. Automations start sessions from a schedule, a Slack mention, a pull request event, a Linear issue, or a signed webhook, and can prompt them, wait for them, run commands inside them, and post results to Slack or GitHub. Pull request review and Slack threads ship as automations you enable. There is no general approval block yet; a person is in the loop through the Slack thread, the dashboard, and the pull request review itself. ## Which agents run inside? Claude Code and Codex ship as harnesses. A harness is a bundle the host mounts into the VM at boot, so the agent runtime is upgraded fleet-wide without touching images. ## Which models? Whatever the harness supports with your key. The Claude Code harness talks to Anthropic with an API key or a personal Claude Code token; the Codex harness talks to OpenAI with an API key or a ChatGPT connection. Either can be pointed at OpenRouter instead, which fronts many providers behind one key. ## How much does an idle session cost? Nothing on the host. An idle session is a set of chunks in the blob store, deduplicated against the image's base snapshot and every other session of that image, and a row in Postgres. A thousand sessions of a 4 GiB image take about 100 GiB of blob storage, not 4 TiB. ## How fast is resume? Under 100 ms when the session resumes on the host that snapshotted it and the chunks are still in that host's cache. One to two seconds on a different host, which is also the cost of migrating a session. A cold start from an image's base snapshot is under a second and needs no pre-warmed pool. These are the numbers from the reference deployment; measure your own fleet before you promise them to anyone. ## Is it open source? 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. --- # Glossary > The words engrams uses, each with the page that owns it. Source: https://engramsfactory.com/docs/getting-started/glossary/ **Session.** One running sandbox: an image plus an optional harness in one microVM on one host. Sessions are created, become active, go idle, resume, and end. See [What is engrams](https://engramsfactory.com/docs/getting-started/overview/). **Task.** One unit of agent work, started from a profile with a prompt. A task owns one or more sessions and is what the dashboard, Slack, and `engrams task` show. **Profile.** An admin-curated bundle of session settings: image, repositories, environment, egress policy, integration access, skills, and session apps. **Automation.** A trigger, a tree of blocks, and typed inputs that start and drive sessions without a person typing a prompt. Runs are durable and recorded step by step. See [Automations](https://engramsfactory.com/docs/platform/automations/). **Model router.** A service such as OpenRouter that supplies models to a harness in place of the provider's own API, with a per-model policy for who may launch them. See [Model routers](https://engramsfactory.com/docs/guides/model-routers/). **Session app.** An HTTP service inside a session, published at its own hostname behind the login wall. See [Session apps](https://engramsfactory.com/docs/guides/session-apps/). **Image.** A plain OCI image, built with `docker build` and pushed to any registry, that a session boots from. See [Images and harnesses](https://engramsfactory.com/docs/concepts/images-and-harnesses/). **Image config.** The runtime settings for an image that are not in the image: name, environment, working directory, resources, and the warm hook. Entered in the dashboard when the image is enabled. See [Images and harnesses](https://engramsfactory.com/docs/concepts/images-and-harnesses/). **Enable.** The step that turns a pushed image into something sessions can boot: engrams materializes the image into chunks, boots a capture VM on the fleet, runs the warm hook, and freezes a base snapshot. **Base snapshot.** The frozen memory and disk of an enabled image after its warm hook ran. Every session of that image starts from it. **Harness.** The agent runtime inside the VM, such as Claude Code or Codex. Staged by the host as a read-only bundle and mounted at boot, never baked into the image. **Host.** A Linux machine with KVM that runs microVMs. Hosts dial the coordinator and need no inbound port. **Backend.** The virtual machine technology a host uses: Firecracker in production, Apple Virtualization on a Mac, or plain subprocesses. See [Sandbox backends](https://engramsfactory.com/docs/concepts/sandbox-backends/). **Snapshot.** A session's memory and disk, written as chunks so the VM can be destroyed and restored later. Taken when a session goes idle. **Chunk.** A fixed-size, immutable block of disk or memory, stored under the hash of its content. Chunks are what make snapshots cheap and deduplicated. See [Storage and snapshots](https://engramsfactory.com/docs/concepts/storage-and-snapshots/). **Manifest.** A versioned list of the chunks that make up one disk or memory image. A session's manifest points at the base image's chunks plus the ones the session changed. **Warm hook.** A command run once inside the capture VM before the base snapshot is frozen, so sessions start with caches filled and daemons running. See [Authoring a warm hook](https://engramsfactory.com/docs/guides/warm-hooks/). **Connection.** A configured, credentialed instance of an integration, such as a Slack workspace or a Google Cloud service account, that profiles can grant to sessions. **Skill.** A read-only bundle of tools mounted into the VM alongside the harness: shared browser, IDE, git credentials, and admin-uploaded packs. **API key.** A credential for the API and CLI. Personal keys come from `engrams auth login`; admin service keys are minted in Settings for scripts and CI. --- # Sessions > A person starts an agent from the dashboard, Slack, or the CLI; engrams runs their harness in a microVM and keeps the record. Source: https://engramsfactory.com/docs/platform/sessions/ Most of what people do with engrams starts with a prompt. You pick a profile, type what you want done, and an agent goes to work in its own microVM on a host you run. engrams is not the agent: it runs the agent runtime you already use, Claude Code or Codex or your own, in the cloud, with the isolation, the credentials, and the durability handled for you. (Image: The Start a task composer: a prompt, a profile, and the harness, mode, model, and effort pickers) ## A task and its sessions A **task** is one unit of work: a prompt, a profile, and one or more sessions. A **session** is one microVM running one harness. The dashboard, Slack, and `engrams task list` all show tasks; a task's page is the transcript of its primary session. A task can spawn sub-tasks, and the tree is shown on the parent. A **profile** is what an admin hands you: the image, the repositories to clone, environment variables, the egress policy, the integrations the agent may use, the skills it gets, and the session apps it publishes. The composer shows, before you launch, exactly what the session will be able to reach and which credentials it will carry. ## Starting one From the dashboard, Start a task takes a prompt and a profile. Beside them are the pickers the profile leaves open: - **Harness**: Claude Code or Codex, or a harness your organization registered. - **Mode**: Build, or Plan for a read-only pass that ends in a plan you approve. - **Model** and **effort**: the harness's models and its effort levels, or a model from a connected router such as OpenRouter. From Slack, mention the bot in a channel that is mapped to a profile; see [Slack threads](https://engramsfactory.com/docs/platform/slack-threads/). From a script, `engrams task create --profile ` does the same and attributes the session to your API key. ## While it runs The session page streams every message and tool call as it happens. You can: - **Reply and steer.** Type while the agent works; the prompt queues and can be edited or withdrawn until the agent reads it. Esc or Stop interrupts the current turn. - **Open a shell.** A terminal into the VM, in the page or from `engrams session shell`. - **Open the IDE or the browser.** When the profile grants them, a code editor and a browser run inside the VM and are tunneled to your page. - **Read the changes.** The Changes tab shows the diff the agent has made so far, and the pull requests it opened. - **Move files.** Upload into the VM and download out of it, from the page or the CLI. (Image: A shell into a running session, beside the transcript) ## Pausing and resuming When the agent goes quiet, engrams snapshots the VM and destroys it. The session holds no host resources while paused. Your next message restores it, on the same host if the chunks are still cached there and on any other host otherwise, in well under a second on the same host and a second or two elsewhere. You never have to know whether a session is live. The rail beside the transcript shows the session's durability: the checkpoints it has, when the last snapshot was written, and whether the newest one is recoverable. A dead session, one whose snapshot can no longer be restored, keeps its transcript; the history lives in Postgres, not in the VM. ## Whose credentials A session a person starts runs as that person. The harness gets their own credential: a Claude Code token pasted once under Settings → Credentials, or a ChatGPT connection for Codex. A session started by a schedule or a webhook runs with the organization's key instead. The same split applies to integrations. A profile can grant an integration with the organization's connection, or with the launching person's own connection when they have made one. In the second case a session by someone who has not connected their account gets that integration switched off rather than silently falling back to the org credential. In every case the credential is brokered at the host's egress proxy and never enters the VM; see [Egress and secret brokering](https://engramsfactory.com/docs/concepts/egress-and-brokering/). ## Apps from inside a session A profile can name ports a session publishes. Each becomes a hostname behind the login wall, so a dev server the agent starts is one click away for anyone in the organization. See [Session apps](https://engramsfactory.com/docs/guides/session-apps/). --- # Automations > An agent with ways in, with durable runs, typed inputs, and a visual builder. Source: https://engramsfactory.com/docs/platform/automations/ An automation is an agent with ways in. The agent is a profile and a prompt. A way in is something that happens: a pull request opening, a Slack mention, a schedule, a webhook from a system you run. When it happens, the way in's steps run, and then the event reaches the agent. It is the part of engrams that turns "an agent I can talk to" into work that happens without anyone typing a prompt. The agent's **scope** says how many agents there are. One agent for each event starts a fresh session every time. One agent for each Slack thread, pull request, or Linear issue keeps one session per thread, pull request, or issue, and every later event for the same one reaches that session. One agent for the whole automation is a standing agent that every event reaches. Each way in says what it does with the agent: starts it, reaches it only when it is already running, closes it, or runs its own steps and no agent. Every run is short and durable: it runs the way in's steps, hands the event to the agent, and ends. The agent's session outlives the run. A run survives a server restart and picks up where it was. (Image: The automation builder, with a schedule trigger and a create-session block on the canvas) ## Two ways to write one **Describe it.** Settings → Automations → New automation opens a prompt: "When a PR opens, run the tests and page #eng-alerts if they fail." A drafting agent reads your repository and your existing automations, asks when a decision is yours, and assembles a draft on the canvas while you watch. The draft lands disabled. You edit it by hand, and the agent and you can edit at the same time. **Build it.** The builder is a canvas: one column per way in, with its trigger as the first node and its steps below, and the automation's one Agent node under every column. A plus sign on any edge inserts a step, and an inspector on the right edits the selected node. The Agent node's inspector holds the profile, the prompt, the scope as a dropdown (each event, each Slack thread, each Slack channel, each pull request, each Linear issue, the whole automation, or a key of your own), and the Slack reply switch. The trigger's inspector holds what the way in does with the agent. The step menu is grouped by purpose, with the engine's internals under Advanced. In any text field, type `${{` and the field completes the variables the step can read: the trigger, the inputs, the event's fields, and the outputs of the steps above, each with a preview from the latest delivery. Nothing here is JSON in disguise; when the server rejects a definition, the error points at the node and the field. **Try it.** The Try it button in the header renders the draft as it is on screen, unsaved edits included, against the latest delivery the trigger would see, and shows what each block would do, which filters pass, and which fields did not render. Nothing runs. A new automation can be tried before it is created. Dry run goes further on a saved automation: a real run that boots no session and posts nothing. Every save is a new version. Runs that are in flight finish on the version they started with, and the Settings tab shows the version history with a diff. (Image: The New automation composer, where a sentence becomes a draft on the canvas) ## Triggers | Trigger | Fires on | You set | |---|---|---| | Integration event | An event from GitHub, Slack, or Linear | the provider, the event keys, and a scope: an explicit list, or the keys of one of your map inputs | | Schedule | A cron expression in an IANA timezone | the schedule and the timezone; one schedule per automation | | Webhook | A signed request from a system without a connector | a registration (see below), the event keys, and an optional filter on the payload | | Manual | The Run now button | nothing | GitHub events cover pull requests opening, updating, and closing, review comments, issues, pushes, check runs, and releases. Slack events are app mentions, messages, and reactions. Linear events are issue and comment creation and updates. An integration trigger can mark some event keys as continue-only: they never open a run, they only join one that is already open. That is how a reply in a Slack thread reaches the run that owns the thread and never starts a second one. ## The agent The agent gets the event at the end of every way in that starts or reaches it: it continues the agent's kept session when one is alive, else it starts one from the profile with the prompt, and it posts the new session's link where the agent talks back. It can reply in the Slack thread the event came from: the agent's replies land in the thread as it works, its questions arrive as Slack forms, and the message gets a reaction while a turn runs. One way in, one filter, and the agent is the shape of a standing agent: a bot that answers in a channel, a reviewer that follows a pull request across pushes, a helper that keeps one session per ticket. The Slack threads built-in is this shape. ## Steps A way in's steps run before the event reaches the agent. Most ways in need none, or a filter. The steps below are for the automations that need more than one session, or work that is not a conversation. **Sessions.** Create session starts an agent from a profile with a prompt, and can override the harness, model, effort, network policy, and capabilities the profile grants. Send prompt delivers a follow-up and waits for the turn to end, for a signal, or for nothing. Wait for session parks until the session is idle or ended. Session status reads a session without touching it. End session tears one down; sessions a run creates are kept by default. **Inside a session.** Run command executes a shell command in the sandbox and captures its output and exit status. Write files places rendered files into the sandbox's filesystem. **Integrations.** Integration action calls an action on a connected integration with the organization's credential: post or update a Slack message, join a channel, post a pull request review, create or update an issue comment, set a commit status, create a Linear issue or comment. The credential is resolved on the server and the block never sees it. **Decisions.** Decide asks a decision model typed questions about a state, in one call: pick one of a list of options, rate on ordered levels, or yes or no. Each answer has a calibrated confidence, so a branch can act on a sure answer and ask a person about the rest. It needs an [OpenRouter key](https://engramsfactory.com/docs/guides/model-routers/); without one it answers `decided: false` and the graph takes its fallback, and the builder does not offer it. List profiles returns the organization's profiles as options for a Decide question. Slack choice posts a question with one button per option into a thread and waits for the click. **Control.** Filter ends the run quietly when its conditions fail. Branch runs one of two lists. Loop repeats a list until a condition holds or an iteration cap is reached. Code runs a JavaScript module in a sandbox with no network, no timers, and no filesystem, to compute a value or a yes-or-no; it gets 250 ms of CPU. **Events.** Wait for event receives the next delivery routed into this run, with an optional deadline, and is what a conversation-shaped automation loops on. **State.** Read, write, delete, and list entries in a per-automation key-value store. A write can carry an expected version, which makes it a compare-and-swap, and a miss is an output you branch on rather than an error. **Routing.** Look up PR session maps a pull request to the session that authored it, so review feedback can go back to the agent that wrote the code. Claim handle binds an external identifier to the current agent so later events route to it. Text fields are templates with `${{ … }}` placeholders and a small set of filters. Every block can see the inputs, the trigger, the event, and the outputs of earlier blocks by id. A block can retry up to five times on transient errors. ## Runs A run is `completed`, `filtered` (a filter or a boolean code block ended it on purpose), `failed`, `superseded`, `halted` (stopped by a person), or `deadline`. The Activity tab lists each run as an entry with the trigger that started it, and consecutive filtered runs fold into one quiet row so noise does not bury the runs that did work. A failed run shows its reason on the row. An entry unfolds in place into its step trace; each step says what its block did in a sentence ("Exited 0", "Started session se-abcde, relayed to the thread"), with its duration and the error verbatim when it failed. A click on a step opens its details: the rendered inputs, the outputs, and the command output. Replay on canvas draws the run on the Build canvas: the way in it came through and the blocks it ran light up with what they did, the rest fades, and a click on a block shows its inputs and outputs for that run. A run on an older version is drawn on that version. The Activity page in the Automations section shows every automation's entries in one ledger. Retry starts a fresh run with the same trigger payload. Stop asks a run to halt at its next checkpoint. A run deadline, up to 48 hours, ends a run that outlived its usefulness. **Concurrency** is a setting on the automation: a key template rendered when an occurrence arrives, and a policy for what happens when a run with that key is already active. | Policy | What happens to the new occurrence | |---|---| | `queue` | Waits, and starts when the current run finishes. | | `supersede` | Takes over; the current run ends as superseded. Pull request review uses this, keyed on the PR, so a new push cancels the review in flight. | | `skip` | Is recorded as a filtered run and dropped. | | `join` | Is delivered into the active run, where a Wait for event block receives it. | **Finalize hooks** run one block when a run ends in a status you choose. They can post a recap or flip a status comment, and they can never change the run's outcome. **Agents** are what a scope keeps: one agent per thread, pull request, or issue, with one kept session, that many short runs contribute to. The Agents tab lists each one, titled by the place it owns (`owner/repo#123`, `#channel · thread`), with its last run and a Close action; a recent-drops list explains why a delivery did not start a run. A way in that closes the agent (a pull request closing, say) ends it; its session stays. The automations list shows the scope as a badge ("per PR", "per thread"). ## Inputs Inputs make an automation configurable without editing it. Each input has a key, a label, a type, and an optional default, and the Inputs tab renders them as a form: strings, numbers, booleans, enums, lists, maps keyed by repository or channel or team, free-form JSON, and references to org secrets by name. A map input's keys can be the trigger's scope, so adding a repository to a map is how you enroll it. Credentials never live in a definition. Integration actions use the organization's connection. A secret reference input holds a name that the server resolves at run time. A session gets what its profile grants, and a block can narrow that further: deny-default network, drop the profile's secrets, add a system prompt. A session can also be created on behalf of a particular person, so it runs with that person's credentials and git identity. ## The built-ins Two automations ship with engrams. They are created disabled and stay that way until you configure them. Their structure is locked, their inputs and a few marked fields are yours to set, and Duplicate gives you a fully editable copy. **PR review** listens for pull requests on the repositories you list. [Pull request review](https://engramsfactory.com/docs/platform/reviews/) has the whole product; in short, it opens a review pass, posts an acknowledgment comment, starts a finder session and a verifier session on the reviewer profile with a deny-default network and no profile secrets, clones the pull request head, runs the finder and then the verifier, settles the findings through a policy gate, posts them as a single GitHub review, and updates the acknowledgment with the count. A new push supersedes the review in flight. Each repository is `auto`, which reviews every pull request, or `on_request`, which reviews when someone comments `@ review`. **Slack threads** answers mentions in the channels you map to profiles. Every mention is one short run: the author must be a linked engrams user, and the thread's session runs as that person. The first mention starts the session, and each later mention hands it the next turn together with the thread replies written in between. The session relays the agent's output into the thread as it streams, round-trips the agent's questions as Slack forms, and marks each turn with a reaction. The session is kept, so a person can pick it up later. [Slack threads](https://engramsfactory.com/docs/platform/slack-threads/) has the setup. ## Custom webhooks For a system without a connector, register a webhook under Settings → Automations. You choose a slug, and the URL is `POST https:///api/v1/hooks/`. The response shows the signing secret once; it is sealed into the org secret store and cannot be read back, so rotation is delete and recreate. The sender signs the raw body with HMAC-SHA256 and sends three headers: ``` X-Engrams-Signature-256: sha256= X-Engrams-Event: deploy.finished X-Engrams-Delivery: ``` A bad signature is a 401, an unknown slug is a 404, a retired registration is a 410, and an accepted delivery is a 200. Fields named like credentials are stripped from the payload before it is stored. GitHub, Slack, and Linear do not use this path; they arrive through their integrations. ## Limits An automation has at most 64 blocks, 8 entrypoints, and 8 finalize hooks. A loop runs at most 100 iterations. A wait is at most 24 hours and a run at most 48. A command's output is kept up to 256 KiB, and Write files takes up to 32 files and 4 MiB. There is no HTTP block, no sleep block, and no approval block; a Slack question round-trip exists only inside the Slack threads built-in. Retry restarts a run from the beginning. --- # Pull request review > A finder and a verifier review each pull request on the repositories you enroll, and post the confirmed findings as one GitHub review. Source: https://engramsfactory.com/docs/platform/reviews/ Pull request review ships as a built-in automation. Enable it, list the repositories it should watch, and every pull request on them gets a review from two agents: a finder that reads the diff and proposes findings, and a verifier that checks each one and drops what it cannot confirm. What survives is posted to GitHub as one review with inline comments. (Image: The Reviews page: one row per reviewed pull request with its findings by severity) ## Enrolling a repository Open Settings → Automations → PR review → Inputs. The **repositories** map lists each repository with two settings: | Setting | Values | Meaning | |---|---|---| | Mode | `auto` or `on_request` | `auto` reviews every pull request when it opens, when new commits arrive, and when a draft is marked ready. `on_request` waits for a collaborator to comment `@ review`. | | Autofix | on or off | Whether the review may push fixes for the findings it is sure about. | The other inputs are the **reviewer profile** the agents run on, the **mention handle** a person uses to request a review (your GitHub App's login by default), the **review lenses** to apply, and free-text **organization instructions** that both agents read. The GitHub connection has to exist first; [Connect GitHub](https://engramsfactory.com/docs/guides/connect-github/) covers the app and its webhook. ## What a review does 1. A new pull request opens a review pass and posts an acknowledgment comment: "engrams is reviewing ``." 2. The finder session starts on the reviewer profile with a deny-by-default network, no profile secrets, and read access to the repository's contents. It clones the pull request head and reads the diff with the lenses and instructions you set. 3. If the finder proposes anything, a verifier session starts the same way, takes each candidate, and confirms or rejects it. 4. A policy gate settles the confirmed findings, and one GitHub review is posted with inline comments. The acknowledgment comment is updated with the count. A new push supersedes a review in flight: the running pass ends as superseded, its sessions are torn down, and a fresh pass starts on the new head. Only the newest head ever gets a review, so a busy pull request does not pile up stale comments. ## The Reviews page Reviews in the sidebar is the ledger: one row per reviewed pull request, newest pass first, with the repository, the author, the pull request's state, the stage the pass reached, and the findings by severity. Filters narrow it by repository, author, state, stage, and severity. A row opens the pull request's dossier: the findings ledger, the state of the addressed pass, and the finder's and verifier's transcripts, so you can see why a finding was kept or dropped. Retry runs the pass again on the same head. The summary comment engrams posts on GitHub links straight to the dossier. ## Where it lives Pull request review is an automation like any other. Its structure is locked; its inputs are yours, and Duplicate gives you a fully editable copy if you want a different flow. Each review is an entry on the automation's Activity tab, with the same step trace every automation gets. See [Automations](https://engramsfactory.com/docs/platform/automations/). --- # Slack threads > Mention the bot in a channel and a session opens for that thread, as the person who asked, with their credentials. Source: https://engramsfactory.com/docs/platform/slack-threads/ Slack threads is the built-in automation that turns a mention into a session. Mention the bot in a channel it is a member of, and engrams starts a session as you, relays the agent's work back into the thread, and keeps the same session for the whole thread. ## What a person sees Mention the bot in a channel or in a thread. Within a moment a reaction marks the message as in progress and the agent's first message lands in the thread. From there: - The agent's messages arrive in the thread as it produces them. - When the agent asks a question, it arrives as a Slack form; answering it continues the session. - Each turn gets a reaction while it runs and another when it ends. - Mention the bot again in the thread to send the next turn. The replies people wrote in the thread since the previous turn go with it, so the agent sees the conversation. - The session is kept for as long as the thread needs it, so someone can pick it up in the dashboard later with the full history. The session runs as the person who wrote the mention: their harness credential, their git identity, and their personal integration connections where the profile asks for them. A mention from someone whose Slack email does not match an engrams user gets a reply asking them to log in first, and nothing starts. ## Turning it on The Slack app has to be connected first; [Connect Slack](https://engramsfactory.com/docs/guides/connect-slack/) has the manifest and the three URLs. Then open Settings → Automations → Slack threads → Inputs. | Input | Meaning | |---|---| | `default_profile` | The profile every thread runs on, unless a channel override or smart routing picks another. With no default, only channels with an override are answered (or every channel, with smart routing on). | | `channels` | Channel overrides: a map from channel to the profile its threads run on. An override always wins. | | `routing` | `default` or `smart`. See [Smart routing](#smart-routing). `default` unless you change it. | | `smart_profiles` | The profiles smart routing chooses between. Empty means every active profile. | | `smart_min_confidence` | Smart routing picks a profile on its own at or above this confidence, from 0 to 1. Below it, it asks in the thread. 0.8 by default. | | `ask_timeout` | How long the profile question waits for a click before smart routing takes its best pick. Ten minutes by default. | Enable the automation. The bot must be a member of a channel to see messages in it: it can join a public channel on its own, and a private channel needs a person to invite it. ## Smart routing With an [OpenRouter key](https://engramsfactory.com/docs/guides/model-routers/), the Slack page offers smart routing. For a new thread in a channel with no override, a decision model reads the thread and picks the profile. It reads each profile's description, its repositories, and its integrations, so keep descriptions specific: "the web app and its API" routes better than "development". - When the model is confident, the session starts on its pick. The thread's first message names the profile and the confidence. - When the model is not confident, or the person asks to choose, the thread gets a question with one button per likely profile. The click decides. With no click before the timeout, the model's best pick runs, and the question shows what was chosen. - A thread that resumes its kept session is never routed again. Without an OpenRouter key, smart routing is not offered. If it was on and the key is removed, threads use the default profile, exactly as with `default` routing. ## How it works Slack threads is an ordinary automation with its structure locked: an agent with one way in. The way in is the Slack app mention event. Every mention is one short run: it admits the author, folds the thread replies since the previous turn into the message, and ends on the agent. The agent's scope is the thread, so the first mention in a thread starts its session and a later mention continues it. One session serves the whole thread, and the queue policy keeps its turns in order. The session's relay posts the agent's output into the thread on its own, with no run open. Smart routing is three blocks in the graph: List profiles, Decide, and Slack choice, and it runs only when a thread has no session yet. The Activity tab under the automation lists each turn's run with its step trace, and Duplicate gives you an editable copy if you want a different flow. See [Automations](https://engramsfactory.com/docs/platform/automations/) for the model. --- # Architecture > The four processes, what each owns, and how they talk. Source: https://engramsfactory.com/docs/concepts/architecture/ engrams is four kinds of process and three external services. Two of the processes run in your cluster's control plane, one runs on every host, and one runs inside every VM. ``` dashboard · CLI · Slack · webhooks │ ┌────────▼────────┐ ┌─────────────────┐ │ orchestrator │───────▶│ coordinator │────▶ Postgres │ auth · tasks · │ │ scheduler · idle│ │ integrations │ │ eviction · events│ └─────────────────┘ └────────┬────────┘ │ hosts dial in ┌──────────────────────┼──────────────────────┐ ┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐ │ host agent │ │ host agent │ │ ... │ │ ┌────┐┌────┐│ │ ┌────┐┌────┐│ │ │ │ │ VM ││ VM ││ │ │ VM ││ VM ││ │ │ │ └────┘└────┘│ │ └────┘└────┘│ │ │ └──────┬──────┘ └──────┬──────┘ └─────────────┘ └──────────────┬───────┘ blob store (GCS · S3 · local) image chunks · memory chunks · snapshots ``` ## The orchestrator The orchestrator is the product surface and the only thing a person or a browser talks to. It owns users, sign-in, and API keys; tasks and profiles; org secrets and per-user credentials; the Slack, Linear, GitHub, and Google Cloud integrations; pull request review; automations; and the Connect RPC API that the dashboard and the CLI call. It serves the dashboard's static files. It is written in TypeScript and runs on Bun. For anything that touches a VM, the orchestrator calls the coordinator. It is the deployment's login wall: the coordinator has no public address. ## The coordinator The coordinator is a stateless service in front of Postgres. It schedules sessions onto hosts, preferring the host that already holds a session's snapshot; it evicts sessions that have gone idle; it runs the enable pipeline that turns a pushed image into a base snapshot; it stores every session event and fans events out to subscribers; and it garbage-collects chunks nobody references. Run as many replicas as you like: Postgres is the only authority, and every background job is lease-guarded so replicas never do the same work twice. ## The host agent One host agent runs on every machine that runs VMs. It dials the coordinator over HTTP, registers, and sends a heartbeat every few seconds with its capacity and what it is running. Hosts never need an inbound port, which is what makes a fleet behind NAT or across clouds work. The host agent owns everything a VM needs on the machine: the chunk cache on local NVMe, the thin pool that holds image and session volumes, the page-fault handler that lazily loads VM memory from chunks, and the egress proxy that every VM's outbound traffic goes through. It composes a sandbox backend, which is the driver for the VM technology in use, with the harness routing that carries prompts and events between a session and the coordinator. ## The in-guest daemon Inside every VM, a small daemon is the first process after init. It starts the harness, runs commands and streams their output, uploads and downloads files, and opens shells. It is not baked into your image: the host stages it in a bundle and the init shim copies it into the VM at boot, so a fix to the daemon ships to every image at once. The harness runs as the daemon's child. When a session resumes from a snapshot the daemon has a clean point to respawn it, which is how a resumed agent picks up its own conversation. ## The external services **Postgres** holds sessions and their event logs, snapshot manifests, hosts, enabled images, registry credentials, and sealed secrets. Managed Postgres on either cloud is fine; the requirements are version 14 or later and `LISTEN/NOTIFY`. **The blob store** holds chunks: the immutable, hash-keyed blocks of disk and memory that every image and snapshot is made of. GCS, S3, and S3-compatible stores such as MinIO work, and a local directory works for development. [Storage and snapshots](https://engramsfactory.com/docs/concepts/storage-and-snapshots/) explains what lives there. **An OCI registry** holds your session images. Any registry that `docker push` can reach works; engrams pulls from it when you enable an image. ## The three wire surfaces | Between | Protocol | Notes | |---|---|---| | clients and the orchestrator | Connect RPC over HTTP/1.1, plus SSE for event streams | the public API; see the [API overview](https://engramsfactory.com/docs/reference/api/) | | coordinator and host agents | HTTP for registration and heartbeats, framed RPC for work | hosts dial out; a version mismatch refuses the connection | | host agent and the VM | length-prefixed frames over vsock on Firecracker, a virtio console on Apple Virtualization | authenticated by a first-frame token | The [engrams repository](https://github.com/cortexapps/engrams) carries the full design document with the trait boundaries and the database schema. --- # Storage and snapshots > Content-addressed chunks, versioned manifests, and the three places engrams gets copy-on-write for free. Source: https://engramsfactory.com/docs/concepts/storage-and-snapshots/ Everything a VM is made of, its disk and its memory, is stored as chunks: fixed-size, immutable blocks named by the hash of their content. Disk chunks are 16 MiB; memory chunks are 512 KiB. A manifest is a versioned list of chunk hashes that describes one disk or one memory image. Chunks live in your blob store and never change; manifests point at them. This is the whole trick. Because a chunk's name is its content, two identical chunks are one chunk. An image's base snapshot is written once, and every session of that image shares it. A session's own manifest starts as a copy of the base manifest and gains new entries only for the chunks the session wrote. A thousand sessions of a 4 GiB image take about 100 GiB in the blob store, not 4 TiB. ## Three levels of copy-on-write **Disk.** A VM's root filesystem is served from its manifest. Reads that hit the base image come from shared chunks; writes produce new chunks and new manifest entries. The base manifest never changes, so enabling an image is a one-time cost. **Memory.** When an image is enabled, engrams captures the VM's memory once. Every session of that image maps that canonical memory privately, and the hardware's memory management unit does the copy-on-write: a page is copied only when a session writes to it. One copy of the memory serves every session on the host. **Fork.** Forking a session is a manifest copy of a few kilobytes. The forked session shares every chunk with its parent until one of them writes. ## Where the bytes live | Tier | What | Where | What it costs | |---|---|---|---| | Persistent | chunks, manifests, working-set traces | the blob store | deduplicated by construction; the base image is stored once | | Cache | recently used chunks, assembled disk files | each host's local NVMe | bounded to a share of the disk; least recently used chunks are evicted | | In memory | the canonical memory map plus each session's private pages | host RAM | one canonical copy per image per host | | Metadata | sessions, event logs, manifest references, hosts | Postgres | managed and backed up like any database | ## How a VM reads its disk and memory On Firecracker, a VM's disk is a thin volume in a device-mapper pool on the host. The kernel owns it: no host process is in the data path, and a host agent restart does not touch a running VM's disk. A base image is staged into the pool once per host, and every session's volume is a snapshot of that image, so creating a session writes nothing. Guest writes land in the pool. Memory is paged in lazily. The host agent owns a `userfaultfd` for the VM's memory region, and on a page fault it resolves the address to a chunk, fetches it if needed, and copies the page in. To hide that latency on resume, hosts record which chunks a session touched in its first seconds and prefault those chunks before the VM's CPUs start. On the macOS backend the volume is a sparse file under the host's working directory, and the same staging and checkpoint code runs over it. Memory chunking is Firecracker-only. ## What a snapshot is A snapshot is two manifest versions, one for disk and one for memory, plus a row in Postgres that points at them. Taking one pauses the VM for the page-cache sync and a volume snapshot, tens of milliseconds however much the session has written, then uploads the blocks that changed since the previous checkpoint as chunks, writes the memory that differs from the canonical map as chunks, records the manifests, and destroys the VM. Restoring is the reverse, on whichever host the coordinator picks: the host stages the manifest into a fresh volume, fetching only the chunks it does not already hold. ## Garbage collection Chunks that no manifest references are collected by the coordinator on a schedule. Deleting a session drops its manifests; deleting an image drops its base manifest once no session references it. The blob store is the durable tier: as long as it holds a session's chunks, that session can be restored on any host, including a fleet that has been replaced entirely. --- # Sandbox backends > Firecracker for production, Apple Virtualization for Mac development, subprocesses for iterating. Source: https://engramsfactory.com/docs/concepts/sandbox-backends/ A backend is the driver for whatever runs a session: a microVM monitor or, in one case, nothing at all. The rest of engrams does not know which one is in use. Three ship. | Backend | Isolation | Snapshots | Runs on | Use it for | |---|---|---|---|---| | Firecracker | microVM on KVM | memory snapshot with lazy paging, disk on a kernel thin volume | Linux with `/dev/kvm` | production | | Apple Virtualization | microVM on Apple's Hypervisor framework | clone of the root filesystem | macOS 12 or later on Apple Silicon | development on a Mac with real isolation | | Process | none; a host subprocess | tarball of the working directory | macOS or Linux | iterating on the orchestration layer without a VM | Production isolation is always Firecracker. The other two exist so the same code paths can be exercised on a laptop; the Apple backend runs the same in-guest daemon and harness bundles and the same image pipeline, so a session that works on a Mac works on the fleet. `just dev` picks the backend for the machine it runs on: Firecracker when `/dev/kvm` is readable and writable, Apple Virtualization on an Apple Silicon Mac, subprocesses otherwise. Set `ENGRAM_SANDBOX_BACKEND` to force one. ## What a Firecracker host needs A production host is a Linux machine with KVM. On managed Kubernetes that means a node pool with nested virtualization, which every provider offers on Intel only: the C3 family on GKE, m8i or bare metal on EKS. The fleet's Helm chart runs a node-prep step that does the setup below on each node; this list is what that step does, for anyone running hosts outside Kubernetes. **KVM.** `/dev/kvm` must be readable and writable by the host agent's user. ```sh [ -r /dev/kvm ] && [ -w /dev/kvm ] && echo OK || echo FAIL ``` **Lazy memory paging.** The host agent needs `/dev/userfaultfd` with mode `0666` (a udev rule) and the sysctl `vm.unprivileged_userfaultfd = 1`. **Session disks.** The kernel needs device-mapper thin provisioning (the `dm_thin_pool` module, shipped with the Ubuntu cloud image kernel) and the node needs `thin-provisioning-tools`. The node-prep step builds a pool from two files on the host's working filesystem and checks it on every boot; `ENGRAM_THIN_POOL` gives the host agent the pool's name. A Firecracker host agent refuses to start without one. **The guest kernel and the bundles.** Each host stages a guest kernel and the read-only bundles for the in-guest daemon, the harnesses, and the skills. The VM boots with `init=/sbin/engram-init`, a shim that copies the daemon out of its bundle and hands over to it, so nothing of engrams is in your image. **The egress proxy.** Every host runs a filtering proxy on TCP 443 and DNS on port 53, and every VM's outbound traffic is redirected through it. It is mandatory: a host that cannot load the proxy's certificate authority or bind its ports refuses to start. Every host in a fleet loads the same CA pair, so a session that migrates keeps trusting its new host. ## The CPU platform is a one-way door A base snapshot captured on a newer CPU never restores on an older one. Keep a fleet on one platform, or bake images per platform. The Terraform quickstarts pin GKE to Sapphire Rapids (C3) and EKS to Granite Rapids (m8i) by default; if you run both clouds and want one bake to serve them, the AWS side offers `m7i.metal-24xl` for parity, at a much higher price. --- # Images and harnesses > A session is a plain OCI image plus an agent runtime the host mounts at boot. Source: https://engramsfactory.com/docs/concepts/images-and-harnesses/ ## Images A session image is a plain OCI image. You build it with `docker build`, push it with `docker push` to any registry, and tell engrams about it once. There is no build tool, no manifest format, and nothing of engrams inside the image. The contract is any Linux image with `/bin/sh`. ``` my-repo/ ├── Dockerfile └── ... your code ``` ```sh docker build -t registry.example.com/team/api:warm-1 . docker push registry.example.com/team/api:warm-1 ``` Two requirements are worth stating. Use a glibc-based image: the bundled harness binaries do not run on Alpine, and a session on a musl image never becomes active. And install what your agent needs to work: `git`, `curl`, and the like are your workspace's requirements, not the platform's, so they go in your Dockerfile. `/workspace` is the working directory. engrams runs no git operations of its own; the repositories a profile lists are cloned into it, and the agent takes it from there. ## Enabling an image Settings that are not part of the image are entered when you enable it, under Settings → Images → Enable a new image: a display name, environment variables, a working directory, the VM's size, and a warm hook. They describe what the image is. What a session may reach and what secrets it holds are session policy, set on the profile, so the same image serves a locked-down profile and a permissive one. engrams stores the settings, not the image, so a settings change is not a rebuild. (Image: The Enable a new image dialog: image URI, name, description, image env, workdir, and the VM's vCPUs, memory, disk, and swap) | Field | Meaning | |---|---| | Image URI | The full OCI reference, `[:port]/:`. Fixed once enabled. | | Name, Description | The display name in pickers, and free text. | | Image env | Non-secret environment variables for every session of this image. The Dockerfile's `ENV` is read at enable time and merged underneath, so a key here overrides the same key in the image, and a value the session supplies overrides both. | | Workdir | The working directory for the harness and for `engrams session exec`. Defaults to the Dockerfile's `WORKDIR`, then to `/`. The directory must exist in the image. | | vCPUs | Required. Placement reserves it against a host's CPU budget. | | Memory MiB, Disk GiB, Swap MiB | The guest's memory, the session's disk budget, and an ephemeral swap device that is discarded at every snapshot. Swap of 0 means none; a good default is a quarter of memory, clamped between 1 GiB and 8 GiB. | | Warm capture hook | A command run once at enable time, with its own timeout, working directory, capture-time environment, and network policy. See [Authoring a warm hook](https://engramsfactory.com/docs/guides/warm-hooks/). | The CLI covers the fields a script needs. The warm hook is set in the dashboard. ```sh engrams image enable --uri registry.example.com/team/api:warm-1 --name team-api --vcpus 2 --memory-mib 4096 ``` Enabling is the expensive step. engrams pulls the image, writes it as chunks into the blob store, boots a capture VM on the fleet, runs the warm hook, and freezes the result as the image's base snapshot. Sessions boot from that snapshot in under a second, with whatever the warm hook left running still running. The Images page shows the capture as it happens, and so does `engrams image jobs`. Cheap fields, like the name and environment, take effect on the next session. Changing the resources or the warm hook means a new capture, so the dialog asks you to confirm, and `engrams image update` asks for `--allow-recapture`. Sessions keep working against the old snapshot until the new one is ready. ## Harnesses A harness is the agent runtime inside the VM. It is a read-only bundle that each host stages and mounts into the VM at boot, alongside the in-guest daemon and the skills. Your image never contains it, so a new agent version rolls out to the whole fleet without a rebuild, and one image can run under different harnesses. Two harnesses ship, and Settings → Harnesses shows them with their models, effort levels, and credential status. [Bring your own harness](https://engramsfactory.com/docs/guides/custom-harness/) is the contract for registering a third. (Image: The Harnesses page: Claude Code and Codex with their models, effort levels, and org credentials) **Claude Code** runs Anthropic's agent. It offers the Opus, Sonnet, and Haiku models, a Build mode and a Plan mode, and three effort levels that map to the agent's thinking budget. For sessions a person starts, it uses that person's Claude Code token, which you paste into Settings once (`claude setup-token` prints it). For sessions started by Slack, cron, or the API, it uses an org secret named `ANTHROPIC_API_KEY`. **Codex** runs OpenAI's agent. It offers the GPT-5 family, the same Build and Plan modes, and four effort levels. Personal sessions use a ChatGPT connection made in Settings, which the harness refreshes from inside the VM; programmatic sessions use an org secret named `CODEX_API_KEY`. Either harness can be pointed at a model router instead of the provider's own API. OpenRouter is built in; an admin connects it under Settings → Model routers, and its models appear in the picker. A harness declares which hosts it must reach, and the egress proxy allows exactly those plus whatever the profile allows. Harness credentials sit one layer above the image: they are resolved when the session is created and injected into the harness's environment, never written into the image or the snapshot. --- # Egress and secret brokering > Every VM's traffic goes through a proxy on its host; credentials are injected there, so an agent can call an API without ever holding the key. Source: https://engramsfactory.com/docs/concepts/egress-and-brokering/ An agent in a session can reach the network only through a proxy on the host that runs its VM. The proxy decides, per session, which hosts are reachable, and for the services you have connected it inserts the credential into each request on its way out. The VM never holds a key it could leak, log, or commit. ## How traffic leaves a VM There is no proxy setting inside the VM and nothing for an agent to bypass. The host redirects every VM's TLS on port 443 and its DNS to the proxy, and drops everything else: other ports, other VMs, and the private address ranges. A session's policy is registered with the proxy before its agent starts, so no request can slip out ahead of it. For a DNS query outside the allow-list the proxy answers as if the name did not exist. For a TLS connection to a host that is not allowed, it closes the connection without sending a byte, so a blocked call never looks like a success to the agent; `curl` reports an empty reply. Responses from allowed hosts pass through unchanged, so an upstream 401 is a 401. The proxy is a node-local daemon that outlives the host agent, so a host roll or an upgrade does not cut a session's open streams to a model API. ## What a session may reach The policy comes from the profile. New profiles deny by default, and most of what a session needs is opened for it: - The **harness** declares the hosts it must reach, the model API and its telemetry, and they are merged in. - Every **integration the profile grants** opens that service's hosts. - Anything else goes under **Add extra hosts** in the profile editor's Network section: exact hostnames, or patterns with one leading wildcard label such as `*.githubusercontent.com`. The profile editor shows the result beside the form, and the task composer shows the same receipt before a person launches. A block in an automation can narrow a session further, to a deny-by-default network with no profile secrets, which is how the pull request reviewer runs. (Image: The profile editor, with the session policy panel listing powers, reachable hosts, and credentials) Two things are refused regardless of the allow-list. The Google credential-exchange endpoints are blocked even under a broad `*.googleapis.com` pattern, because a service account key that reached them could mint tokens the policy never granted. And if you allow a DNS-over-HTTPS resolver, VMs can resolve any name through it, so do not. ## TLS The proxy sees the hostname at the start of each TLS connection and takes one of two paths. An allowed host with nothing to broker is passed through as an opaque byte stream: the proxy never decrypts it. A host with a brokered credential is terminated at the proxy with a certificate minted for that hostname and signed by a certificate authority every session image trusts. The authority is the same across the whole deployment, so a session that migrates to another host keeps trusting the proxy there; the deployment guides cover where its key lives on each cloud. ## Brokered credentials A **connector** describes a service: the hosts it lives on, the header that carries its credential, and the operations an agent may perform, as HTTP method and path patterns or as GraphQL operations. engrams ships two dozen and you can add your own. When a profile grants a connector, the credential stays sealed in the org secret store. At session start the coordinator unseals it and hands it to the host's proxy along with the policy. Each matching request is rewritten on the way out: the proxy strips any header of the same name the agent supplied and inserts the real one. A request to a connector's host whose shape matches none of its operations is refused. Inside the VM, a connector's CLI runs with a placeholder token that the proxy replaces; the agent is told not to log in. A **profile secret** works one of two ways. Literal puts the value in the session's environment. Broker puts a placeholder there and substitutes the value at the proxy, only on the hosts that secret is allowed to reach; a placeholder that appears in a request to any other host drops the connection. Credentials that expire, such as OAuth tokens and the GitHub App's installation tokens, are refreshed by the proxy itself before they go stale. ### Whose credential A profile grant can name the organization's connection or the launching person's own. With the second, a session started by a person who has connected their Slack, GitHub, Linear, Sentry, or Cortex account runs those integrations as them, and a session by someone who has not gets those integrations switched off, never the org credential. Sessions started by a schedule or a webhook always use the organization's. A disconnected personal account stops working in live sessions within a day. ## What you can see The host logs every brokered request: the session, the host, the method, the path without its query string, and whether it was allowed, never the credential or the body. Side effects on connected services surface in the session's transcript as integration events, so a pull request or a Slack message an agent created is visible where the conversation is. ## Capture VMs The VM that runs an image's warm hook gets a policy of its own, set with the hook: no network by default, an allow-list, or open egress for a development image where no agent runs. It never gets brokered credentials; the warm capture env is its only secret-bearing input. ## Custom connectors Settings → Integrations → Add a custom connector takes a provider slug, a category and an icon, the hosts it opens, one or more credential headers with their templates and the org secret each one reads, the operations as method and path patterns or GraphQL operations, and optionally a CLI binary to stage into sessions that grant it. The token is sealed as an org secret and injected at the proxy like the built-ins. A custom connector cannot replace a built-in one. --- # Production deployment > One Kubernetes cluster, two Helm releases, and the node-pool rules that are not negotiable. Source: https://engramsfactory.com/docs/guides/deploy-overview/ A production deployment is one Kubernetes cluster with two Helm releases. Terraform quickstarts for GCP and AWS create everything around the cluster in one apply and render the Helm values you need. This page is the shape; [Deploy on GCP](https://engramsfactory.com/docs/guides/deploy-gcp/) and [Deploy on AWS](https://engramsfactory.com/docs/guides/deploy-aws/) are the step-by-step bring-ups. ## The two releases **The `engram` release is the control plane.** It runs the coordinator as a stateless Deployment with as many replicas as you like, the orchestrator, and nginx serving the dashboard. The coordinator talks to Postgres (Cloud SQL or RDS), the blob store (GCS or S3), and the cloud's secret manager. It never owns a VM and has no public address. The orchestrator is the login wall: the web Ingress in front of it is the only public surface of the deployment. **The `engram-host-fleet` release is the Firecracker hosts.** It runs the host agent as a privileged DaemonSet on a dedicated node pool with nested virtualization, in a namespace that enforces the privileged pod security level. A node-prep DaemonSet builds the session-disk pool, sets the sysctls, and mounts the memory substrate; an init container stages Firecracker, the guest kernel, and the session bundles on each node. The same release runs the fleet operator, which rolls hosts one at a time after draining them and scales the node pool from the coordinator's queue. The DaemonSet's update strategy is `OnDelete` on purpose. Kubernetes never rolls these pods; the operator does, node by node, and a roll reattaches to running VMs rather than killing them. Host agents register with the coordinator's in-cluster Service over HTTP. There is no inbound connection to a host and no internal load balancer. ## The node pool The KVM node pool has rules that come from incidents, not taste. - **Intel only.** Nested virtualization is Intel-only on every managed provider, set when the pool is created, and incompatible with node auto-provisioning. GKE: the C3 family, on a Standard cluster. EKS: m8i, or bare metal. - **One CPU platform per fleet.** A base snapshot captured on a newer CPU never restores on an older one. The quickstarts pin one platform per cloud; moving a fleet to an older platform means re-enabling every image. - **The operator owns the pool's size.** Terraform seeds it and then ignores it. Never attach a cluster autoscaler to the KVM pool. - **The pool's label and taint, the privileged namespace, and auto-upgrade off** are invariants the charts and modules assume. ## Blob store, secrets, and the master key The blob store is a GCS bucket or an S3 bucket, provisioned by Terraform and named in the Helm values. Firecracker memory snapshots are multiple gigabytes and stream through without being held in RAM. Secrets that sessions use come from the cloud's secret manager, resolved when a session is created, with the coordinator's identity (Workload Identity on GKE, IRSA on EKS). There are no key files. The coordinator envelope-encrypts registry credentials and per-session secret bundles under a master key. On GCP that key is 32 random bytes kept in Secret Manager and relayed into the coordinator's Secret; on AWS it is a KMS key and no key material ever reaches a pod. A missing or wrong master key fails the coordinator at boot, on purpose: running without one would write rows nobody can decrypt. The choice of provider is made when a deployment is created and cannot be flipped later. ## The egress proxy Every host runs a proxy that intercepts each VM's TLS on port 443 and its DNS, and enforces the allow-list from the session's profile. It is mandatory. Every host loads the same certificate authority so a session that migrates keeps trusting its new host; the [configuration reference](https://engramsfactory.com/docs/reference/configuration/) covers how each cloud delivers the CA pair to hosts, which differs because host-agent pods share the node's network. One transport-layer bypass exists by construction: if you allow a DNS-over-HTTPS endpoint, guests can resolve names through it. Do not allow-list one. ## Health The coordinator serves `/healthz`, which is 200 whenever the process is up, and `/readyz`, which is 200 only when Postgres answers. Wire the liveness probe to the first and the readiness probe to the second, so a coordinator that lost its database leaves the load balancer instead of serving errors. The charts do this. The dashboard's Settings › Fleet page is the view for whoever runs the fleet: each host's status, disk, memory, CPU, and sandboxes, and a Drain button that moves its sessions elsewhere. Settings › Storage shows snapshot durability per sandbox. When a host drains or goes offline, the Fleet row in the Settings rail says so from any page. (Image: The Fleet page: two hosts with disk, memory, and CPU bars and a Drain button each) --- # Deploy on GCP > A fresh GCP project to a working engrams deployment on GKE, command by command. Source: https://engramsfactory.com/docs/guides/deploy-gcp/ This page takes a fresh GCP project to a working deployment. Every command is meant to run as written. If a step needs something this page does not tell you, that is a bug in this page; please file it. **Before you start** - A GCP project with billing, and Owner on it. - `gcloud`, `terraform` 1.5 or later, `helm` 3.10 or later, `kubectl`, and `openssl`. - A domain you control. You will create one A record. - An OAuth client for sign-in. People sign in with Google, and only accounts of your Google Workspace domain get in. In the Google Cloud console, open APIs & Services → Credentials, create an OAuth client ID of type "Web application", and add the authorized redirect URI `https://$DOMAIN/api/auth/oauth2/callback/sso`. If the console asks for a consent screen first, user type "Internal" limits the client to your organization. Keep the client ID and the client secret. - C3 quota. The KVM pool is two `c3-standard-22` nodes by default, which is 44 vCPUs. Check `gcloud compute regions describe ` for `C3_CPUS` headroom, and that the region offers C3 at all, before you apply. A quota request can take a day. Throughout, `PROJECT`, `REGION`, `DOMAIN` (for example `engrams.example.com`), `ADMIN_EMAIL`, `EMAIL_DOMAIN` (the Workspace domain whose accounts may sign in, for example `example.com`), `OAUTH_CLIENT_ID`, and `OAUTH_CLIENT_SECRET` are yours. Run every command from a checkout of the newest release. The charts in a release install the images of that release; a checkout of `main` can name a version that is not released. ```sh git clone https://github.com/cortexapps/engrams.git && cd engrams git checkout "$(git tag --list 'v*' --sort=-v:refname | head -n 1)" ``` To move to a later release afterwards, see [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade/). ## 1. Enable the APIs ```sh gcloud services enable --project=$PROJECT \ container.googleapis.com compute.googleapis.com \ sqladmin.googleapis.com servicenetworking.googleapis.com \ secretmanager.googleapis.com storage.googleapis.com \ iam.googleapis.com dns.googleapis.com ``` ## 2. Terraform, one apply ```sh cd deploy/terraform/gcp/quickstart terraform init terraform apply \ -var project_id=$PROJECT \ -var region=$REGION \ -var domain=$DOMAIN \ -var admin_email=$ADMIN_EMAIL \ -var oauth_client_id=$OAUTH_CLIENT_ID \ -var "oauth_allowed_domains=[\"$EMAIL_DOMAIN\"]" ``` If you manage the domain in Cloud DNS, add `-var dns_zone_name=` and Terraform creates the A record too; otherwise step 4 does it by hand. This creates the VPC, the chunks bucket, the GKE cluster with its KVM pool, Cloud SQL with both databases, the secret shells, the four identities with their Workload Identity bindings, both namespaces, the External Secrets relay, and the web static IP with a managed certificate. Expect about 20 minutes; the cluster and the database are most of it. Fetch cluster credentials for the later steps: ```sh gcloud container clusters get-credentials \ "$(terraform output -raw cluster_name)" \ --region $REGION --project $PROJECT ``` ## 3. Populate the secret shells Secret material never enters Terraform state, so the shells are created empty and filled here. **Do this before the Helm installs.** Until the shells have versions, the External Secrets relay leaves the in-cluster Secrets unsynced and the pods crash-loop waiting for them. ```sh # The machine bearer allow-list (one token to start). echo -n "$(openssl rand -hex 32)" | \ gcloud secrets versions add engram-auth-tokens --data-file=- --project=$PROJECT # The 32-byte master key. openssl rand -base64 32 | \ gcloud secrets versions add engram-kek-master --data-file=- --project=$PROJECT # The orchestrator's session-signing secret. openssl rand -base64 48 | \ gcloud secrets versions add engram-better-auth-secret --data-file=- --project=$PROJECT # The OAuth client secret. echo -n "$OAUTH_CLIENT_SECRET" | \ gcloud secrets versions add engram-oauth-client-secret --data-file=- --project=$PROJECT # The egress-proxy CA pair (fleet-wide, ten-year cert). openssl req -x509 -newkey rsa:4096 -nodes \ -keyout /tmp/ca.key -out /tmp/ca.pem -days 3650 \ -subj "/CN=Engram Egress Proxy CA" gcloud secrets versions add engram-egress-ca-cert --data-file=/tmp/ca.pem --project=$PROJECT gcloud secrets versions add engram-egress-ca-key --data-file=/tmp/ca.key --project=$PROJECT rm /tmp/ca.key /tmp/ca.pem ``` Check that the relay synced. Give it up to a minute, or delete the `external-secrets` pods to force a resync: ```sh kubectl get externalsecret -A # every row: STATUS SecretSynced, READY True ``` ## 4. DNS If you passed `dns_zone_name`, skip this. Otherwise create one A record for `$DOMAIN` pointing at: ```sh terraform output -raw web_static_ip ``` The managed certificate provisions only after both the DNS record resolves and the Ingress exists, and the Ingress is created by the Helm install in the next step. Until then the certificate sits in `Provisioning` however long you wait; that is expected, not stuck. After step 5, expect 15 to 40 minutes. `kubectl describe managedcertificate -n engrams engram-web-cert` shows `Active` when it is done. ## 5. Helm, two releases Render the values overlays Terraform derived, copy the static examples, and install: ```sh cd deploy/terraform/gcp/quickstart terraform output -raw engram_values > /tmp/engram.tfvalues.yaml terraform output -raw host_fleet_values > /tmp/host-fleet.tfvalues.yaml cd ../../../.. cp deploy/helm/engram/values-gcp.yaml.example /tmp/engram-values.yaml cp deploy/helm/engram-host-fleet/values-gcp.yaml.example /tmp/fleet-values.yaml # The tfvalues overlays fill in every REPLACE_* the Terraform layer knows. # Edit the /tmp copies only for taste: replica counts, resources. helm install engram deploy/helm/engram \ -n engrams -f /tmp/engram-values.yaml -f /tmp/engram.tfvalues.yaml helm install hf deploy/helm/engram-host-fleet \ -n engrams-hosts -f /tmp/fleet-values.yaml -f /tmp/host-fleet.tfvalues.yaml ``` The engrams images are public, so the install needs no pull secret. If you mirror them into a private registry, create a pull secret in both namespaces first and name it under `imagePullSecrets` in each values file. The release names matter. The fleet values dial `engram-coordinator.engrams`, and the quickstart's Workload Identity bindings expect the `hf-*` ServiceAccount names. If you use different names, pass the matching `-var coordinator_ksa`, `host_fleet_ksa`, and `operator_ksa` back in step 2. Watch it come up: ```sh kubectl get pods -n engrams # coordinator, web, orchestrator Running kubectl get pods -n engrams-hosts # node-prep and host-agent per KVM node, plus the operator kubectl logs -n engrams deploy/engram-coordinator | grep -i "host registered" ``` ## 6. First login Open `https://$DOMAIN` once the certificate is Active and choose **Continue with Google**. Sign in as `$ADMIN_EMAIL`; the bootstrap allow-list promotes that account to admin on its first sign-in. Every other account of `$EMAIL_DOMAIN` can sign in as a member, and no other account can. There is no password sign-up. There is no identity proxy in this posture: the orchestrator's login wall is the door. The `orchestrator.auth` block of the chart holds every sign-in setting in one place: - **Another identity provider.** Any provider with an OIDC discovery document works, such as Okta, Auth0, Keycloak, or Cognito. Pass `-var oauth_issuer=` in step 2. The provider must return a verified email. - **Who may sign in.** `oauth.allowedDomains` and `oauth.allowedEmails`. The check runs on every sign-in, so an account that leaves the list loses access at its next sign-in. - **IAP instead.** `mode: iap`, with `deploy/helm/engram/values-iap.yaml.example`. It splits the app host from the machine surface (RPC, SSE, WebSockets) onto a second hostname, so plan on one more A record at the same IP and a second managed certificate. - **Email and password.** `mode: password`. An address is not verified at sign-up, so anyone who can reach the page can register any address. **Do not** use it on a deployment the internet can reach. ## 7. Enable a first image Sessions need an enabled image. From Settings → Images, or with the CLI, register your registry if it is private and enable an image. `eclipse-temurin:21-jre` is a good first pick. Use a glibc-based image; the built-in harnesses do not run on Alpine, and a session on a musl image hangs at "delivering". The enable pipeline materializes the image, boots a capture VM on the KVM pool, and takes the base snapshot. The harness also needs model credentials. Add your Claude Code token under Settings before the first session, or connect OpenRouter under Settings → Model routers. When the image shows **ready**, create a session against it. The agent's first reply is the end-to-end proof. ## Teardown ```sh helm uninstall engram -n engrams; helm uninstall hf -n engrams-hosts cd deploy/terraform/gcp/quickstart && terraform destroy -var ... # the same vars as apply ``` `terraform destroy` refuses to remove the bucket unless it is empty; `force_destroy` is off on purpose. `gsutil -m rm -r gs:///*` first if you mean it. ## When something does not come up | Symptom | Likely cause | |---|---| | Pods crash-loop on missing Secrets | Step 3 was skipped or the shells are empty. `kubectl get externalsecret -A` shows the sync state. | | Host-agent pods Pending | The KVM pool is not up (C3 quota?), or the namespace lost its `pod-security.kubernetes.io/enforce=privileged` label. | | Host-agent crash-loops on the egress CA | The CA shells are empty, or the `engram-host-egress-ca` Secret has not synced into `engrams-hosts`. | | Certificate stuck in `Provisioning` | DNS does not resolve to the static IP yet; managed certificates wait for it. | | Google shows `redirect_uri_mismatch` | The OAuth client's authorized redirect URI is not exactly `https://$DOMAIN/api/auth/oauth2/callback/sso`. | | The login page says the account does not have access | The account is not of an allowed domain. For Google the domain is the Workspace organization of the account, so a personal Google account with an address at your domain is refused. | | Orchestrator `CreateContainerConfigError`, `secret "engram-oauth-client" not found` | The `engram-oauth-client-secret` shell is empty. Fill it (step 3) and wait for the relay. | | `no capacity`, sessions queued forever | Hosts never registered. Check the host-agent logs for the coordinator endpoint and the bearer token, which must be an `engram-auth-tokens` entry. | --- # Deploy on AWS > A fresh AWS account to a working engrams deployment on EKS, command by command. Source: https://engramsfactory.com/docs/guides/deploy-aws/ This page takes a fresh AWS account to a working deployment on EKS. Every command is meant to run as written. If a step needs something this page does not tell you, that is a bug in this page; please file it. The GCP twin is [Deploy on GCP](https://engramsfactory.com/docs/guides/deploy-gcp/); the places where AWS differs on purpose are marked ⚡. **Read this first: cost and quota** - The KVM fleet defaults to two `m8i.8xlarge` instances (32 vCPUs each, nested virtualization), the nearest shape above the GCP quickstart's `c3-standard-22`, at roughly $3.40 an hour for the pair (us-west-2 on-demand). Tear it down when you are not using it. - Check that your "Running On-Demand Standard instances" vCPU quota covers the 64 fleet vCPUs plus the control-plane nodes; a fresh account's default may not. Request the increase under Service Quotas → EC2 before you apply. Grants can take hours to days. - KVM needs Intel hardware: an 8th-generation Xeon 6 virtual shape (C8i, M8i, R8i, or their flex variants; the only families EC2 enables nested virtualization on, and only as a launch-time flag the quickstart sets) or bare metal (`*.metal`). No AMD, no Graviton, and no 7th-generation virtual shapes. - ⚡ The CPU platform is a one-way door. m8i is Granite Rapids; the GCP quickstart's C3 is Sapphire Rapids. Images enabled on the default AWS fleet never restore on a C3 fleet, because newer silicon never restores on older. If you run both clouds and want one enable to serve them, set `kvm_instance_type = "m7i.metal-24xl"` (Sapphire Rapids; metal, because EC2 does not enable nested virtualization on 7th-generation virtual shapes). That path is about $10 an hour for the pair and needs a metal quota ticket for 192 vCPUs. **Before you start** - An AWS account with admin credentials configured; `aws sts get-caller-identity` works. - `aws`, `terraform` 1.5.7 or later, `helm` 3.10 or later, `kubectl`, `openssl`, `jq`, and `dig`. - A domain you control. You will create one validation CNAME and one final CNAME. - An OAuth client for sign-in, from an identity provider with an OIDC discovery document: Google, Cognito, Okta, Auth0, or Keycloak. Register a web client with the redirect URI `https://$DOMAIN/api/auth/oauth2/callback/sso`, and keep the client ID and the client secret. The provider must return a verified email. Throughout, `REGION`, `DOMAIN`, `ADMIN_EMAIL`, `EMAIL_DOMAIN` (the domain whose accounts may sign in, for example `example.com`), `OAUTH_CLIENT_ID`, and `OAUTH_CLIENT_SECRET` are yours. Run every command from a checkout of the newest release. The charts in a release install the images of that release; a checkout of `main` can name a version that is not released. ```sh git clone https://github.com/cortexapps/engrams.git && cd engrams git checkout "$(git tag --list 'v*' --sort=-v:refname | head -n 1)" ``` To move to a later release afterwards, see [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade/). ## 1. Quota check ```sh aws service-quotas get-service-quota --region $REGION \ --service-code ec2 --quota-code L-1216C47A \ --query 'Quota.Value' # Running On-Demand Standard instances (vCPUs) ``` You need at least 64 for the default fleet plus the small control-plane nodes, or at least 192 if you chose the metal parity shape. Request more before you continue if you are short. ## 2. Terraform, one apply Write the inputs to `terraform.tfvars` once. The file is gitignored, and every later `terraform` command reads it, so a fresh shell with `$REGION` unset can never apply an empty region. The inputs are also validated non-empty. ```sh cd deploy/terraform/aws/quickstart cat > terraform.tfvars < /tmp/engram.tfvalues.yaml terraform output -raw host_fleet_values > /tmp/host-fleet.tfvalues.yaml cd ../../../.. cp deploy/helm/engram/values-aws.yaml.example /tmp/engram-values.yaml cp deploy/helm/engram-host-fleet/values-aws.yaml.example /tmp/fleet-values.yaml # The tfvalues overlays fill in every REPLACE_* the Terraform layer knows. helm install engram deploy/helm/engram \ -n engrams -f /tmp/engram-values.yaml -f /tmp/engram.tfvalues.yaml helm install hf deploy/helm/engram-host-fleet \ -n engrams-hosts -f /tmp/fleet-values.yaml -f /tmp/host-fleet.tfvalues.yaml ``` The engrams images are public, so the install needs no pull secret. If you mirror them into a private registry, create a pull secret in both namespaces first and name it under `imagePullSecrets` in each values file. Release names matter here as on GCP: the fleet dials `engram-coordinator.engrams`, and the IRSA trust policies name the `hf-*` ServiceAccounts. Different names mean re-applying step 2 with the matching `*_ksa` values in `terraform.tfvars`. Watch it come up: ```sh kubectl get nodes -l engram.io/kvm=true # the KVM instances, 2 Ready kubectl get pods -n engrams kubectl get pods -n engrams-hosts # hf-operator + one hf-host-agent per KVM node kubectl logs -n engrams deploy/engram-coordinator | grep -i "host registered" ``` ## 6. The final CNAME ⚡ The load balancer's hostname exists only after the web Ingress reconciles, so it is the one value Terraform cannot print up front: ```sh kubectl get ingress -n engrams engram-web \ -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` CNAME `$DOMAIN` to that hostname. `https://$DOMAIN` then serves the app. The ALB carries the ACM certificate and the 3600-second idle timeout the overlay sets; the 60-second default would cut every quiet SSE and WebSocket connection. ## 7. First login and first image Open `https://$DOMAIN` and choose the **Continue with** button. Sign in as `$ADMIN_EMAIL`; the bootstrap allow-list promotes it to admin. Every other account of `$EMAIL_DOMAIN` can sign in as a member, and no other account can. There is no password sign-up. The `orchestrator.auth` block of the chart holds every sign-in setting, the allowlist included. ⚡ Do not put ALB OIDC or Cognito authentication in front of the app: it breaks CORS preflights and WebSockets. The orchestrator's login wall is the door; point `orchestrator.auth.oauth` at the Cognito user pool instead. Enable a first image. `eclipse-temurin:21-jre` is a good first pick; use a glibc-based image, because the built-in harnesses do not run on Alpine. Add your model credentials under Settings, or connect OpenRouter under Settings → Model routers, and create a session against the image. The agent's first reply is the end-to-end proof. ⚡ If you are reusing images enabled on a GCP fleet, the default platforms do not match (m8i is Granite Rapids, C3 is Sapphire Rapids); enable them fresh on this fleet. Cross-cloud reuse works only on the `m7i.metal-24xl` parity shape. ## Teardown The fleet bills while it idles, so tear it down promptly: ```sh helm uninstall engram -n engrams; helm uninstall hf -n engrams-hosts # Delete any load balancers the controller created before destroying the VPC: kubectl delete ingress -n engrams --all cd deploy/terraform/aws/quickstart && terraform destroy # reads terraform.tfvars ``` The bucket refuses to be destroyed unless it is empty; `aws s3 rm s3:// --recursive` first. ## When something does not come up | Symptom | Likely cause | |---|---| | KVM auto-scaling group stuck at 0 of 2 healthy | vCPU quota (step 1), or the chosen shape is not offered in a chosen availability zone; m8i and metal availability varies by zone. Check the group's activity history. | | Instances are InService but `kubectl get nodes -l engram.io/kvm=true` is empty and the DaemonSet shows 0 desired | The kubelets cannot authenticate. The node role needs an EKS access entry, which the kvm-nodegroup module creates; `aws eks list-access-entries --cluster-name ` must list `-node`. Nodes join on their own once it exists, without a relaunch. | | `terraform apply` fails on a Helm release with `no endpoints available for service "aws-load-balancer-webhook-service"` | The AWS Load Balancer Controller registers a fail-closed webhook on every Service before its pods are ready. The quickstart installs External Secrets after the controller, so this means the controller itself is unhealthy (`kubectl get pods -n kube-system`). Fix that, then run `apply` again. | | Pods crash-loop on missing Secrets | Step 3 was skipped. `kubectl get externalsecret -A` shows the sync state. | | Orchestrator `CreateContainerConfigError`, `secret "engram-oauth-client" not found` | The `engram/oauth-client-secret` shell is empty. Fill it (step 3) and wait for the relay. | | The provider shows a redirect URI error | The client's redirect URI is not exactly `https://$DOMAIN/api/auth/oauth2/callback/sso`. | | The login page says the account does not have access | The account is not of an allowed domain, or the provider did not return a verified email. | | Orchestrator `CreateContainerConfigError`, `couldn't find key ENGRAM_KEK_MASTER_KEY` | The `engram/kek-master` shell is empty, or the relay has not re-synced since you filled it. Run `kubectl annotate externalsecret -n engrams engram-orchestrator-secrets force-sync=$(date +%s)`. | | Host-agent crash-loops on the egress CA | The CA shells are empty, or the fleet's IRSA role cannot read them; it is scoped to exactly those two ARNs. | | Ingress has no load balancer hostname | The AWS Load Balancer Controller is not healthy (`kubectl get pods -n kube-system`), or the ACM certificate is not Issued yet. | | ACM certificate stays `PENDING_VALIDATION` | The validation CNAME is missing or misnamed, usually a dropped label when the console appended the zone. Query it against the zone's authoritative nameserver (step 4) and fix the name; ACM re-checks on its own. | | `no capacity`, sessions queued forever | Hosts never registered. Check the host-agent logs for the coordinator endpoint and the bearer token. | | Enabling an image fails with `Error creating KVM object: No such file or directory` | `/dev/kvm` is missing on the host: the instance was launched without nested virtualization (a launch template from before the flag, or a 7th-generation shape). `kubectl exec -n engrams-hosts -- grep -c vmx /proc/cpuinfo` prints 0. The flag is launch-time only: run `terraform apply`, then replace each instance with `aws autoscaling terminate-instance-in-auto-scaling-group --instance-id --no-should-decrement-desired-capacity`. | --- # Authoring a warm hook > Run a command once at enable time so every session starts with caches filled and daemons running. Source: https://engramsfactory.com/docs/guides/warm-hooks/ An image's warm capture hook is a command that runs inside the capture VM, once the in-guest daemon is ready and just before the base snapshot is frozen. Whatever the command leaves behind is in the snapshot, so every session of that image starts with it. The classic case is a build daemon: `gradle --daemon help` starts the Gradle daemon as a separate process and returns, the daemon is captured live, and every restored session inherits a warm, cache-hot daemon with no cold start. You set it in the Warm capture hook section of the image's config, under Settings → Images. This page is the contract for writing one. (Image: The Warm capture hook section of the image config: warm command, timeout, workdir, and the capture env) | Field | Meaning | |---|---| | Warm command | The command, as space-separated arguments. It runs inside the capture VM once the in-guest daemon is ready and before the snapshot is frozen. It must exit; anything it leaves running is captured live. Empty means no hook. | | Timeout secs | The global deadline, 600 seconds by default. The in-guest daemon kills the command at this point and the capture fails. | | Warm workdir | The command's working directory. Defaults to the image's workdir. | | Warm capture env | Capture-time environment entries. Each is a literal value or a reference to an org secret by name. References are resolved at capture through the same store sessions use and are never stored resolved; an unresolvable reference fails the capture. | | Warm network | The capture VM's network while the command runs: no network (the default), deny by default with an allow-list of hosts and host patterns such as `*.githubusercontent.com`, or allow all. | Everything in this section is captured into the base snapshot, so any change to it means a recapture, and the dialog asks you to confirm. ## What a hook may assume **A ready guest.** The in-guest daemon has come up, and the image's effective environment, the image env over the Dockerfile's `ENV`, is merged with the warm capture env and injected into the hook's environment. **Egress per the warm network setting.** By default the capture VM has no network at all: no policy is registered, so the proxy denies everything. A hook that needs the network opts in, either with allow-all for a development image where no agent runs at capture, or with deny-by-default plus allowed hosts and host patterns. Changing the network setting, like anything in the warm hook, means a recapture. **No per-session secrets.** The capture VM never gets a session, so it never gets a session's secrets. The warm capture env is the only secret-bearing input a hook gets; its values may be literals or secret references resolved against the same store a session uses, and an unresolvable reference fails the capture. Everything the hook writes is frozen into the base snapshot, so treat the snapshot as secret-bearing storage if the hook used a secret. **No TTY.** The hook runs as a plain exec, not an interactive shell. **A fresh VM per attempt.** Every capture attempt, including a retry, boots a new VM from a fresh pull of the image, so the hook runs from scratch each time. Any side effect it has outside the VM, such as a webhook call or a registration, must be safe to repeat. **It must exit.** A hook that starts a daemon and returns is the intended shape. A hook that runs forever is killed at the global timeout and the capture fails. ## It fails loud A non-zero exit, a stall, a blown stage deadline, or the global timeout all abort the capture and the enable. engrams never ships a "cold" base snapshot that a hook claimed to warm, and there is no partial credit: fix the hook and retry the enable job. ## Three deadlines Three budgets apply and the tightest wins. - **The stage deadline**, `deadline_secs` on a stage's `start` line, fires on wall-clock time since that stage started, regardless of output. A stage that is chatty but stuck still dies on its budget. It applies only if the stage declares one. - **The stall budget**, `ENGRAM_WARM_STALL_SECS` on the host with a default of 120 seconds, fires when no output and no progress line has arrived for that long. It arms only once the hook has emitted its first valid progress line; a hook that never emits one gets only the global timeout. Any stage that waits, on a health check or a poll loop, must emit heartbeats, or the platform cannot tell slow from wedged. - **The global timeout**, the hook's timeout field with a default of 600 seconds, is the backstop. The in-guest daemon kills the hook at this deadline no matter what the other two would allow. ## The progress protocol A hook reports progress by printing lines with a sentinel prefix on stdout. Tokens are space-separated `key=value` pairs; `msg=` runs to the end of the line, so it comes last; unknown keys are ignored; a line that does not parse is ordinary output, which resets the stall clock but is not a stage transition. ```text ::engram-warm:: event=start stage= [deadline_secs=] [msg=] ::engram-warm:: event=heartbeat [stage=] [msg=] ::engram-warm:: event=done stage= ``` A `start` closes the previous stage on its own, so you do not need a `done` before the next `start`. A `heartbeat` resets the stall clock but not the stage deadline. A `done` closes the current stage explicitly. stderr is captured into the output tail and resets the stall clock like any output, but it is not parsed for progress lines. ```sh #!/bin/sh set -e echo "::engram-warm:: event=start stage=deps-up deadline_secs=120" ./install-deps.sh echo "::engram-warm:: event=done stage=deps-up" echo "::engram-warm:: event=start stage=migrations deadline_secs=60" ./run-migrations.sh echo "::engram-warm:: event=done stage=migrations" echo "::engram-warm:: event=start stage=wait-ready deadline_secs=300" until curl -fsS localhost:8080/healthz >/dev/null 2>&1; do echo "::engram-warm:: event=heartbeat stage=wait-ready msg=still waiting on healthz" sleep 5 done echo "::engram-warm:: event=done stage=wait-ready" # Start the long-lived process detached, then exit. It is captured live. nohup ./run-server.sh >/var/log/server.log 2>&1 & disown exit 0 ``` ## What you get for it While a capture runs, the enable job shows the current phase and stage, updated at least every 30 seconds even through a healthy silent wait; `engrams image job ` prints them. When a capture fails, whether on exit code, stall, stage deadline, or the global timeout, the job keeps the failing stage's name and the hook's last 16 KiB of combined output, so you can diagnose it from the dashboard or the CLI without host access. The watchdog runs above the sandbox backend, so stall detection, stage deadlines, and the output tail behave the same on every backend that captures. --- # Upgrade engrams > Move a deployment from one release to the next, and what happens to running sessions while you do. Source: https://engramsfactory.com/docs/guides/upgrade/ A release of engrams is a git tag, `v0.10.0` for example, and a set of container images with the same version as their tag. The two charts in a checkout of that tag install those images by default: an image tag you do not set falls back to the chart's `appVersion`. To upgrade, check out the newer tag and run `helm upgrade` on both releases. engrams is a 0.x project, so any release can change a wire format, a database schema, or a Terraform module. The [release notes](https://github.com/cortexapps/engrams/releases) say which. Read them before you start. ## Before you upgrade - **Back up both databases.** The coordinator and the orchestrator apply their schema migrations during the upgrade, and the migrations only go forward. A backup is the one way back to the older release. - **Keep your values files.** You need the two files you passed to `helm install`, and the Terraform variables you applied with. ## 1. Check out the release ```sh git fetch --tags git checkout v0.10.0 ``` Use the tag of the release you are moving to. `git tag --list 'v*' --sort=-v:refname` lists the releases, newest first. ## 2. Apply Terraform and render the values again A release can add a secret, an identity, or a value that the charts expect. Apply the quickstart with the variables you used the first time, then write the two overlays again. On GCP: ```sh cd deploy/terraform/gcp/quickstart terraform init terraform apply # with your -var flags or your .tfvars file terraform output -raw engram_values > /tmp/engram.tfvalues.yaml terraform output -raw host_fleet_values > /tmp/host-fleet.tfvalues.yaml cd ../../../.. ``` On AWS the directory is `deploy/terraform/aws/quickstart`. Read the plan before you approve it: a release should not replace the cluster, the database, or the bucket, and a plan that says it will is a reason to stop. Then compare your two values files with the examples in the new checkout, `deploy/helm/engram/values-.yaml.example` and `deploy/helm/engram-host-fleet/values-.yaml.example`, and copy over any key that is new. If your files set an image tag, remove it, or the upgrade keeps the old images. ## 3. Upgrade the control plane ```sh helm upgrade engram deploy/helm/engram \ -n engrams -f /tmp/engram-values.yaml -f /tmp/engram.tfvalues.yaml ``` Helm first runs a job that migrates the orchestrator's database, and stops the upgrade if the job fails. The coordinator migrates its own database when its new pods start. Then the three Deployments roll. Sessions run on the hosts, so a control-plane roll does not touch them; the dashboard reconnects on its own. `kubectl get pods -n engrams` should show the coordinator, web, and orchestrator pods `Running` on the new image. ## 4. Upgrade the host fleet Helm installs a custom resource definition once and never updates it, so apply the new one by hand before the chart: ```sh kubectl apply -f deploy/helm/engram-host-fleet/crds/ helm upgrade hf deploy/helm/engram-host-fleet \ -n engrams-hosts -f /tmp/fleet-values.yaml -f /tmp/host-fleet.tfvalues.yaml ``` This command returns at once and no host pod restarts yet. The operator sees the new images and replaces the host pods one node at a time: it cordons the node, deletes the pod, waits until the new pod is ready, and moves to the next. The VMs on the node keep running while the pod is replaced, and the new pod reattaches to them. Watch the roll with `kubectl get pods -n engrams-hosts -w`, or on the dashboard's Settings › Fleet page. Do steps 3 and 4 together. The coordinator and the host agents share a wire version and refuse to talk across a mismatch, so after a release that changes it, new sessions queue until the first host is on the new version. ## When a release changes how hosts run VMs Most releases roll the host pods in place, and the new pod reattaches to the running VMs. Some releases change how a host serves a VM's disk or memory, so the new host agent cannot adopt the VMs the old one started. The charts handle that release for you, and both `helm upgrade` commands stay the same: 1. Before the upgrade changes anything, a job compares the new host agent with every host. If a host runs VMs the new build cannot adopt, the job cordons it and evicts each session on it to a checkpoint. A session that never had a checkpoint gets one first; a paused session is resumed so it can be evicted. Both charts run this job, so either can go first. 2. If the job cannot evict a session within `upgradeDrain.timeoutSeconds` (an hour by default), it fails and the upgrade stops before any change. The release notes and the job's log name the sessions. 3. After the host fleet chart upgrades, a second job replaces the drained host pods so they start the new build; with the operator enabled, the operator does it. When the new build's files would leave the disk nearly full, node-prep clears the chunk cache first; it refills from the chunk store. 4. Each host comes back on the new build, and the coordinator lifts the job's cordon. A session resumes from its checkpoint the next time someone uses it. Every running session sees one eviction and one resume, not a live move. An upgrade like this also lifts any cordon you placed by hand on the hosts it drains. ## Run a build that is not a release Set the image tags to the full commit SHA of a commit on `main`; every build is published under that tag. The control-plane chart takes `image.tag`, `web.image.tag`, and `orchestrator.image.tag`, and the fleet chart takes `image.tag`, `operator.image.tag`, and `nodeAssets.image.tag`. Use the charts from the same commit. **Do not** deploy the `main` tag. It moves, and the charts pull with `IfNotPresent`, so a node that already has `main` keeps the build it has while a new node pulls a newer one. --- # Session telemetry > Export every session's turns, model calls, and tool calls as OpenTelemetry spans to Langfuse or any collector. Source: https://engramsfactory.com/docs/guides/telemetry/ engrams can export traces of agent sessions, with a span for each turn, each model call with its tokens and cost, and each tool call, to a Langfuse you host or to any OpenTelemetry collector. The feature is off by default and costs nothing while it is off. ``` guest (claude, codex, or a custom harness) ──native TLS──▶ model provider (unchanged) │ harness events over vsock ▼ host agent ──▶ coordinator ──▶ Postgres session_events (the durable, replayable log) │ orchestrator listener → exporter, one per sink │ OpenTelemetry GenAI spans, OTLP/HTTP JSON ▼ Langfuse, an OpenTelemetry collector, or both ``` Four properties follow from that shape. **It is harness-agnostic.** The exporter reads the normalized session-event log, not any agent's native output. Every harness gets session, turn, and tool spans; a harness whose adapter reports generations and cost, which Claude Code and Codex do, also gets model, token, and cost data. **It never gates the workload.** The exporter is a listener strictly downstream of the persisted log, with its own durable cursor per sink. A slow or dead sink stalls only that sink's export position, never the session, the dashboard's stream, or another sink. **It is at-least-once, with stable ids.** Trace and span ids are derived from the task, session, run, and tool ids, so a replay after a restart re-posts byte-identical spans and Langfuse upserts them. A plain collector pipeline without id-based dedup can show duplicate spans after an orchestrator restart mid-turn; that is the documented trade for never losing one. **There is no pricing table.** Cost is passthrough: the Claude Code harness reports its own per-turn cost in micro-dollars, and Codex reports none. Backends that price from model and token counts, like Langfuse, work either way. Token counts carry each provider's own accounting; Anthropic excludes cache reads from `input_tokens` and OpenAI includes them, and the cache counts ride as separate attributes. ## Configuration One environment variable on the orchestrator, `ENGRAM_TELEMETRY_SINKS`, holds a JSON array of sinks. Unset or empty means off. ```json [ { "name": "langfuse", "endpoint": "https://langfuse.example.com/api/public/otel/v1/traces", "headers": { "Authorization": "Basic " }, "captureContent": false, "serviceName": "engrams" }, { "name": "collector", "endpoint": "http://otel-collector:4318/v1/traces" } ] ``` | Field | Required | Meaning | |---|---|---| | `name` | yes | Unique and stable. It keys the sink's durable per-session cursor, so renaming a sink restarts its export position from the beginning. | | `endpoint` | yes | The full OTLP/HTTP traces URL. For Langfuse: `/api/public/otel/v1/traces`. | | `headers` | no | Extra request headers, which is where auth goes. Values are secrets and are never logged; source the whole variable from a Kubernetes Secret. | | `captureContent` | no, default `false` | When `true`, spans also carry prompt summaries, assistant text, and tool argument and result summaries. The default is metadata only: model, tokens, cost, latency, tool names, ok or error. Decide this per sink; content leaving for a third party is a different consent from token counts. | | `serviceName` | no, default `engrams` | The OpenTelemetry resource `service.name`. | Langfuse authenticates with `Authorization: Basic ` using a project's API keys. ## The span model | Span | Emitted from | Key attributes | |---|---|---| | `agent_session` (the trace root) | the task's lifetime, at its end | `session.id`, `user.id`, `engrams.task.id`, `engrams.harness`, `engrams.profile_id`, the outcome; ERROR when the task failed | | `agent_turn` | a run's start to its completion or interruption | `gen_ai.operation.name=invoke_agent`, `engrams.prompt_id`, `engrams.cost_usd` when the harness reports cost; ERROR on failure or interrupt | | `chat ` | a generation event, one per API call for Claude Code and one per turn for Codex | `gen_ai.conversation.id` (the session), `gen_ai.request.model`, `gen_ai.usage.input_tokens` (all input tokens, cached tokens included), `output_tokens`, `cache_read.input_tokens`, `cache_creation.input_tokens`, `gen_ai.response.id` | | `execute_tool ` | a tool call's completion, with its start derived from the harness's own duration | `gen_ai.conversation.id`, `gen_ai.tool.name`, `gen_ai.tool.call.id`; ERROR when the tool reported an error | The trace id derives from the root task, so a tree of sub-sessions shares one trace. Timestamps are stamped by the coordinator and include the transit from the VM, so treat differences under 100 ms as noise. ## Try it against a local Langfuse Run Langfuse locally. Its compose file bundles Postgres, ClickHouse, MinIO, and Redis, so pick host ports that do not collide with the dev stack, which uses 5435 for Postgres: ```sh git clone https://github.com/langfuse/langfuse.git /tmp/langfuse cd /tmp/langfuse && docker compose up -d # The UI is on http://localhost:3000. Create an org, a project, and API keys. ``` Point the dev orchestrator at it from `.env`: ```sh ENGRAM_TELEMETRY_SINKS='[{"name":"langfuse-local","endpoint":"http://localhost:3000/api/public/otel/v1/traces","headers":{"Authorization":"Basic "},"captureContent":true}]' ``` Start the stack with `just dev` and run one session to completion with at least one tool call. In Langfuse you should see one trace for the task with the session, turn, generation, and tool spans nested; model and token columns on the generations; and, if you turn `captureContent` off and run again, no prompt or message text anywhere in the attributes. ## Troubleshooting **No traces at all.** A malformed `ENGRAM_TELEMETRY_SINKS` is a startup error, so check the orchestrator's log for it. Sessions that do not belong to a task export nothing. **A sink stopped advancing.** The exporter retries each event with backoff up to eight times, then drops that flush and moves on, with a warning in the log. Check the sink's availability. **Cost is missing.** Only the Claude Code harness reports cost. --- # Google Cloud connections > Give sessions short-lived Google Cloud credentials through Workload Identity Federation, with no keys anywhere. Source: https://engramsfactory.com/docs/guides/google-cloud-connections/ A Google Cloud connection lets an agent call Google APIs as a service account you choose, with credentials that are minted per request and never enter the VM. engrams uses Workload Identity Federation for this. It does not accept a service-account key, and it does not use the identity of the machine it runs on. ## Requirements - `ORCHESTRATOR_PUBLIC_URL` must be a public HTTPS origin. Google reads its OpenID discovery and JWKS endpoints from there. - `ENGRAM_DEPLOYMENT_ID` names this deployment in the token's organization claim. It defaults to the public hostname. The federation setup pins it in an attribute condition, so treat it as immutable once a project has applied the setup. - Sessions that use a connection need a Firecracker or Apple Virtualization host with the egress proxy. The process backend refuses them, because it cannot intercept the metadata endpoint. - One Google service account per set of privileges. A connection always targets one service account. - The Security Token Service API and the IAM Service Account Credentials API enabled in the project. - Every Google API hostname a session may call, listed as an exact endpoint on the connection. Do not add the STS or OAuth endpoints; they are always denied from the guest. Common endpoints are `compute.googleapis.com`, `logging.googleapis.com`, `cloudtrace.googleapis.com`, and `container.googleapis.com`. ## Set up a connection 1. Open **Settings → Integrations → Google Cloud** and select **Add connection**. 2. Enter a name, the numeric project number, and the target service account's email, and select the Google APIs sessions may reach. engrams generates the connection alias and the federation provider resource; the pool and provider ids are under **Advanced settings**. 3. Create the connection. It starts disabled, and engrams opens its setup page. 4. Apply the generated Terraform or `gcloud` configuration from that page. It fixes the allowed audience, the claim mapping, the connection condition, and the `roles/iam.workloadIdentityUser` binding. 5. Select **Test**. engrams performs the token exchange and the service-account impersonation. 6. Enable the connection once the test passes, and add its operations to a profile. Prefer the curated operations when one covers the call. Cloud Logging, Cloud Trace list and detail, Cloud Monitoring metric descriptors and time series, Compute Engine instance reads, and GKE cluster metadata each have one. `api.call` is for APIs without a curated operation; it permits calls to every configured `*.googleapis.com` endpoint, subject to the service account's IAM policy. Disabling, editing, or deleting a connection affects new sessions. A running session keeps the connection snapshot it launched with and can refresh from it until it ends; to cut it off, revoke the Google-side binding or end the session. Editing a connection disables it, so test again before you re-enable it. ## Resource constraints Google IAM on the target service account is the primary boundary. A profile can add a second, proxy-enforced boundary as full Google API path patterns, where `*` matches one path segment and never spans a `/`: ```text /compute/v1/projects/acme-prod/zones/us-central1-a/instances/my-instance/start ``` `logging.entries.list` puts resource names in the request body, where the proxy cannot see them, so engrams rejects path constraints for that operation. Use IAM and a dedicated service account there instead. ## Audit The credential broker records the user, session, the immutable profile snapshot, the connection, the service account, and whether the mint succeeded. The egress proxy records the session, the credential source, the target host, the HTTP method, the path without its query string, and the policy outcome. Correlate the two by session and connection. engrams never records tokens, authorization headers, query strings, or request bodies. In Google Cloud, enable Data Access audit logs for the Security Token Service, IAM Service Account Credentials, and each data API the connection can call. The federation subject and the connection attribute in a Google audit entry match the engrams session and connection fields. Google's [federation guide for products](https://docs.cloud.google.com/iam/docs/use-workload-identity-federation-to-let-customers-access-their-cloud-resources) and [security guidance](https://docs.cloud.google.com/iam/docs/best-practices-for-using-workload-identity-federation) cover the Google side. ## Signing-key rotation The orchestrator signs each subject token with an RSA key it keeps in its database and publishes through JWKS. It creates the active key at startup, retires a key after 90 days, and keeps the retiring key published for a further 7 days. That overlap is what makes rotation safe: a token minted just before the change is still in flight when the new key becomes active, and Google resolves it by key id. Nothing changes on the Google side; the pool reads JWKS at validation time. To rotate at once, after a suspected compromise, call `POST /api/v1/admin/integrations/oidc/rotate`. The same overlap applies. ## What the guest sees Google tools inside the VM use metadata-style Application Default Credentials. The host serves a session-local metadata endpoint that returns only an opaque placeholder. The egress proxy strips the guest's authorization, checks the session's policy, method, path, and endpoint, adds the real short-lived token, binds the HTTP authority to the validated TLS server name, and forwards the request. If an upstream response echoes the credential, the proxy redacts it. Do not run `gcloud auth login`, create a credentials file, or copy a key into a session. The session bundle adds `gcloud` only; Kubernetes clients, SSH clients, and sync tools are outside this integration. --- # Bring your own harness > Run an agent runtime that is not Claude Code or Codex inside engrams sessions. Source: https://engramsfactory.com/docs/guides/custom-harness/ engrams does not know what agent is running inside a session. It knows a harness: a read-only bundle that the host mounts into the VM at boot and starts through a small, fixed contract. Claude Code and Codex ship as harnesses. Yours can too, and it appears in the same picker, with its own models, modes, and effort levels, and with the same credential handling. A harness is three things: a descriptor, an entry binary, and whatever that binary needs next to it. This page is the contract for all three. It assumes you can write a small Rust program. ## The bundle A harness bundle is a directory tree. At its root: | Path | Required | What it is | |---|---|---| | `harness.toml` | yes | The descriptor: name, models, modes, credentials, egress. | | `harness` | yes | The entry binary, or whatever `exec` in the descriptor names. It must be executable. | | anything else | no | Sidecars: your agent's own binary, its runtime, its assets. The entry binary finds them relative to its own path. | Inside the VM the tree is mounted read-only at `/opt/engram/dyn/0/`, so the entry binary runs as `/opt/engram/dyn/0/harness`. Build the entry binary as a static musl executable for the guest architecture, because the image is anything with `/bin/sh` and may be glibc or musl. If your agent is a glibc binary, ship a musl build beside it and pick at startup; the Claude Code harness does exactly this for Alpine images. You publish the tree as an OCI artifact. The artifact carries one layer of media type `application/vnd.engram.harness.tar.v1+gzip`, a gzipped tar of the tree, and a config of type `application/vnd.engram.harness.v1+json` whose body is `{"kind":"engram-harness-v1"}`. Push it to any registry the coordinator can pull from, then register it under Settings → Harnesses with its name and OCI reference. engrams pulls the artifact, validates the descriptor, checks that the entry binary exists, packs the tree into a squashfs, stores it in the blob store, and lists it in the catalog. Hosts fetch the squashfs on demand. Names are 1 to 64 characters of lowercase letters, digits, hyphens, and underscores, and may not collide with `claude` or `codex`. Deleting a harness removes it from the catalog; sessions already running it finish. ## The descriptor ```toml name = "goose" label = "Goose" description = "Block's Goose agent. Needs a GOOSE_API_KEY org secret for programmatic runs." exec = "harness" router_protocols = ["openai_responses"] [egress] allow_hosts = ["telemetry.example.com"] [native_egress] allow_hosts = ["api.openai.com"] [auth] org_env = "GOOSE_API_KEY" org_env_hint = "An admin sets an org secret named GOOSE_API_KEY." user_env = "GOOSE_USER_TOKEN" user_env_hint = "Paste the token from `goose auth token`." [[models]] id = "gpt-5.5" label = "GPT-5.5" default = true env = { GOOSE_MODEL = "gpt-5.5" } [[modes]] id = "default" label = "Build" default = true [[modes]] id = "plan" label = "Plan" [[effort]] id = "medium" label = "Medium" default = true env = { GOOSE_REASONING = "medium" } ``` Every table rejects unknown keys, so a typo is a parse error, not a silent default. | Field | Meaning | |---|---| | `name` | The stable id. Must match the name you register and the name a session selects. | | `label`, `description` | Shown in the picker and on the Harnesses page. | | `exec` | The entry binary, relative to the tree root. Default `harness`. No leading slash, no `..`. | | `args` | Extra arguments appended after the ones engrams passes. | | `router_protocols` | Which model-router protocols the harness can consume: `anthropic_messages`, `openai_responses`, both, or neither. | | `[egress]` | Hosts the harness must reach on every launch, such as telemetry. | | `[native_egress]` | The model provider's hosts, granted only on a direct launch. A routed launch gets the router's hosts instead. | | `[auth] org_env` | The environment variable that carries the organization's credential for programmatic runs. engrams resolves it from an org secret of the same name. | | `[auth] user_env` | The variable that carries a person's own credential for sessions they start. Stored per user under Settings → Credentials. | | `[auth.user_oauth]` | Instead of `user_env`: a managed OAuth connection, as Codex uses for ChatGPT. The two are mutually exclusive. | | `[[models]]`, `[[effort]]` | Options with an `id`, a `label`, at most one `default`, and an `env` map applied to the harness's environment. | | `[[modes]]` | Options with no `env`. The selected mode arrives with each prompt, and the harness decides what it means. | An option's `env` may not set the user credential variable, may not set the org credential variable to anything but the empty string, and may not reference secrets. Model and effort are pure environment: the descriptor is the whole mechanism, and the Claude Code harness has no code for either. ## The launch The in-guest daemon starts the entry binary with two flags and, in development, one alternative: ``` /opt/engram/dyn/0/harness --port 1026 --session-id # Firecracker and Apple Virtualization /opt/engram/dyn/0/harness --connect host:port --session-id # the process backend ``` `--vsock-host` is accepted as an alias of `--port`. Exactly one of the two dial flags is present. The working directory is the image's `workdir`, or `/`. Standard input is closed and standard output and error go to `/var/log/engram/harness.log`; never write to the inherited console, because in a restored VM nothing drains it and the write blocks forever. The environment holds the session's image env and profile secrets, the model and effort env from the descriptor, the credential variable the descriptor named, `ENGRAM_SESSION_ID`, `ENGRAM_SANDBOX_ID`, `ENGRAM_BINDING_EPOCH`, the egress proxy's CA in `SSL_CERT_FILE` and its friends, `ENGRAM_TOOLS` with the JSON manifest of platform tools, and on a routed launch `ENGRAM_MODEL_ROUTER_ID`, `_PROTOCOL`, `_BASE_URL`, and `_MODEL`. `ENGRAM_STATE_DIR` names the directory that survives snapshots, `/workspace/.engrams` by default; anything the harness must remember across an idle-evict and resume lives there, not in the process. When a session resumes and the previous harness process is still alive, engrams does not respawn it. It sends `SIGUSR1`, which means "drop your connection and dial again", because a restore rebuilds the vsock device without closing the harness's socket. Handle it. If the previous process exited, engrams starts a fresh one, and your state directory is how it picks up where it left off. ## The wire The harness dials the host, on vsock port 1026 in production or the TCP address in development, and speaks length-prefixed frames: a four-byte big-endian length, then a bincode-encoded message. The message types are Rust types in the `engram-harness-proto` crate, and their variant order is pinned by golden tests, so the only safe evolution is a trailing variant or field. The first frame is `HarnessAttach` with the session id, sandbox id, binding epoch, and a harness version string. The host answers `HarnessAttachAck`. A rejection is one of three: `UnknownBinding` and `SessionMismatch` are transient, so back off and retry; `Superseded` is fatal, because a newer harness generation owns the session. After that, every frame is a `HarnessFrame` carrying either an event from the harness or a command from the host. **Events the harness sends.** `RunStarted` with the prompt id when a turn begins. `AgentMessage` for each assistant message, with optional `AgentMessageChunk` frames before it for streaming. `ToolCallStarted` and `ToolCallCompleted` around each tool call, with a name, an id, and short summaries. `FileChanged` when a tool wrote a file, so the dashboard can show a diff. `Generation` with the model and token counts after each model call, in the provider's own accounting. `RunCost` once per turn if the agent reports cost. `RunCompleted` or `RunInterrupted` when the turn ends. `TitleSuggested` if the agent names the task. `ToolCallRequested` to ask the platform to run a tool from the manifest. After every `RunCompleted` or `RunInterrupted` the harness sends exactly one of `Idle`, `Parked`, or `Busy`. `Idle` means the session may be snapshotted and evicted. `Parked` means the only outstanding work is a deferred tool call, such as a question waiting for a person, and the session may be evicted meanwhile. `Busy` means background work is still running and the idle timer must not start. Nothing else nominates a session for eviction, so a harness that forgets this leaves VMs running forever. **Commands the host sends.** `Prompt` with text, a prompt id, and an optional mode. Every prompt, including the session's first, arrives this way; the harness acknowledges it by sending `RunStarted` with the same id, and the platform retries until it does. If a turn is in flight the harness queues the prompt and reports `PromptQueued`, and may later receive `EditQueued` or `DequeueQueued`. `Interrupt` asks the harness to stop the current turn, by whatever means the agent supports, and end it as `RunInterrupted`. `Shutdown` with a grace period asks for a clean exit. `ToolResult` delivers the answer to a `ToolCallRequested`. `Checkpoint` exists and every shipped harness ignores it. Questions to a person and plan approval ride the tool path. The manifest in `ENGRAM_TOOLS` lists `ask_user_question` and `exit_plan_mode` with their schemas; a harness that wires them into its agent gets the dashboard's question forms and the Slack round-trip for free. A tool marked `deferred` parks the turn until its result arrives. ## The SDK The `engram-harness-sdk` crate owns the failure-prone half. It dials, attaches, retries with backoff, handles `SIGUSR1`, re-sends unacknowledged events after a reconnect, and runs your agent engine in a task that outlives any single connection, so a dropped host link never aborts a turn. It also provides the prompt queue with per-prompt mode, the state directory with named paths for the files a harness keeps, the mode stamp that survives resume, the parked-call store for deferred tools, the question and plan-decision shapes, a stderr drain so a chatty agent cannot deadlock on a full pipe, and a UTF-8-safe truncation for summaries. The SDK and the crates it pulls in (`engram-harness-proto`, `engram-transport`, `engram-ids`) are Apache-2.0. Your harness links them without taking on the AGPL-3.0 terms that cover the rest of engrams. The shape of a harness built on it: ```rust let cfg = ConnectionConfig::from_args(); let ch = Channels::new(); let engine = tokio::spawn(run_agent(ch.command_rx, ch.event_tx.clone())); let code = engram_harness_sdk::serve(cfg, engine, ch.command_tx, ch.event_rx, ch.reattach).await; std::process::exit(code); ``` `run_agent` is yours: it receives commands, drives your agent's process or library, and emits events. The Codex harness in the repository is the reference for an adapter that wraps an external CLI, and the noop harness is the floor, a few hundred lines that speak the protocol with no agent behind them. A harness written in another language is not practical today. The wire has no JSON or protobuf form and no schema file, so the working pattern is a thin Rust entry binary on the SDK that runs your agent as a child process in any language you like. ## What a real adapter handles The Claude Code harness is the honest measure. Beyond the wire it keeps one long-running agent process per session rather than one per prompt, finds turn boundaries in the agent's own output, stores the agent's conversation id in the state directory so a respawn resumes the same conversation, maps the `plan` mode to the agent's read-only permission mode and respawns cleanly when the mode changes, translates `Interrupt` into an in-band request and then a signal, derives `Generation`, `RunCost`, `FileChanged`, and `TitleSuggested` from the agent's stream, reports `Busy` while the agent's subagents work, and exposes the platform tools to the agent through a local tool server it starts before the agent. ## Limits Custom harnesses run on the Firecracker fleet. The macOS and process backends stage bundles from a local directory and do not fetch a registered harness. Registration is in the dashboard only; the CLI selects a harness with `--harness` but does not register one. The router protocols are a closed set of two. The squashfs is packed root-owned without extended attributes, so setuid bits and file ownership do not survive. And because the wire is positional, a change to the protocol in a new engrams release requires a rebuild of your harness against the new crate; the shipped harnesses are rebuilt in the same change. --- # Model routers > Serve models to any harness through OpenRouter, with a per-model policy for who may launch them. Source: https://engramsfactory.com/docs/guides/model-routers/ A model router supplies models independently of the agent harness. The harness still runs the agent loop; the router changes where its model calls go. Claude Code speaks the Anthropic Messages protocol and Codex speaks the OpenAI Responses protocol, and a router that serves both can sit behind either one. OpenRouter is the router that ships, and it serves both. (Image: The Model routers page, with OpenRouter connected and its model catalog) ## Connect OpenRouter You need one thing from OpenRouter: an API key. There is no OAuth application, no callback URL, and no webhook. 1. Open Settings → Model routers. The OpenRouter card says "key required" until a key is saved, and until then the router is invisible everywhere else: no Route option in the task composer or the profile editor, and no catalog refresh. 2. Paste the key and select Save key. It is stored as the org secret `openrouter.api_key`, sealed like every other org secret. 3. Select Refresh catalog. engrams fetches OpenRouter's model list, keeps the models that produce text and support tools, and drops the rest. The catalog refreshes on its own every six hours after that; if a refresh fails, the card shows the error and the last good catalog stays in use. ## Decide who may launch what A fresh catalog is inert: every model arrives disabled. Each row has two switches. | Switch | Who it opens the model to | |---|---| | Enabled | Programmatic runs: Slack, schedules, webhooks, the API. | | Available to users | People, in the task composer's model picker. Requires Enabled. | The table shows each model's capabilities, context window, and price per million tokens, with a search box over name, author, and slug, and a link to the model's page on OpenRouter. A model that OpenRouter has withdrawn stays in the table marked unavailable so you can see what changed, and cannot be launched. ## Use a routed model In the task composer and in a profile, the Route control offers the native provider and every connected router whose protocols overlap the selected harness. Pick OpenRouter and the model list becomes the routed catalog. A profile's route is its default; a task can override it. Switching to a harness that cannot speak the router's protocol clears the route. Three things change on a routed launch, and all of them are enforced before the session boots. - **Egress.** The session may reach `openrouter.ai` and may not reach the provider's own API hosts. A routed Claude Code session cannot call Anthropic directly, and a routed Codex session cannot reach OpenAI or ChatGPT. - **Credentials.** The router key is brokered at the egress proxy for `openrouter.ai` and is never in the VM's environment. The person's own Claude Code token or ChatGPT connection is not injected, so someone with no provider credential of their own can still start a routed session. The organization's `ANTHROPIC_API_KEY` or `CODEX_API_KEY` is not injected either. - **Effort.** If the model does not advertise reasoning support, the effort setting is dropped rather than sent. A launch is refused, with the reason, when the harness has no adapter for the router's protocol, the model is unavailable, the model is not enabled for the caller, or the key is missing. ## What routes today OpenRouter is the only router, and the router list is part of the release, not something an admin can extend. Adding a second router means a change to engrams. --- # Session apps > Give a service running inside a session a stable URL that people and sibling apps can reach, behind the login wall. Source: https://engramsfactory.com/docs/guides/session-apps/ A session app is an HTTP service inside a session, published at its own hostname. An agent that starts a web server on port 3000 can hand you a link; a frontend and an API in the same session can find each other by name; a person can open the running thing instead of reading about it. Every request passes through the orchestrator, which authenticates the visitor and relays the bytes into the VM. ## Declare apps on a profile In Settings → Profiles, a profile's Apps section takes a name and a port per app. Names are 1 to 24 lowercase characters with interior hyphens; ports are 1 to 65535; a profile may not repeat a name or a port. A profile with no apps publishes nothing. Each session draws one random slug, three words like `tidy-swift-otters`, and every app in the session is `-` under the deployment's preview domain: ``` web-tidy-swift-otters.preview.example.com api-tidy-swift-otters.preview.example.com ``` The hostname does not encode the port and is not a secret. Authorization is the wall; the name is only an address. ## What the session sees Every process in the session gets two variables per app, for every app in the session, not only its own: ``` WEB_INGRESS_HOST = web-tidy-swift-otters.preview.example.com WEB_INGRESS_URL = https://web-tidy-swift-otters.preview.example.com API_INGRESS_HOST = api-tidy-swift-otters.preview.example.com API_INGRESS_URL = https://api-tidy-swift-otters.preview.example.com ``` The stem is the app name uppercased, with runs of punctuation collapsed to one underscore. Half of what a service needs is a peer's address, which is why every app gets every name: a CORS allow-list and a post-login redirect live on the API and want the frontend's URL. Map them into the names your code expects with `${…}` in the profile's environment variables: ``` CORS_ALLOWED_ORIGINS = ${WEB_INGRESS_URL} API_BASE_URL = ${API_INGRESS_URL} ``` An unknown reference is left as written, since env values legitimately contain `$`. A reference shaped like an ingress variable that resolves to nothing is reported as a typo or a renamed app. The profile editor previews the resolved values as you type. An app published ad hoc on a running session, from the session's Diagnostics drawer, gets a hostname but no environment variable, because the VM's environment was fixed when the harness started. Declare on the profile anything a sibling must reach. ## Who can open one | Visibility | Who may open the app | |---|---| | `org` (the default) | Any signed-in member of the deployment. | | `private` | The session's owner and admins. | An unauthenticated navigation redirects to the login page and back. An unauthenticated request that is not a navigation, such as a `fetch`, gets a 401 rather than a login page, so a client sees a clean error instead of an HTML parse failure. A credentialed cross-origin request is allowed only from a sibling app of the same session; two sessions are two trust domains even under one owner. A CORS preflight is allowed through without a cookie, because browsers never send one on a preflight and nothing the app could do would fix a refusal. The proxy strips any cookie a guest app tries to set under the orchestrator's own cookie name, so a guest cannot overwrite a visitor's session. A guest app that itself uses the same auth library under its default cookie name will find its login not sticking; rename its cookie. The Diagnostics drawer on a session lists its apps with a liveness dot: serving, no response on the port, or unknown while the session is not running. Revoking an app removes its hostname at once. ## What the deployment needs Session apps are off until the orchestrator has a preview domain. In the control-plane chart, set `orchestrator.preview.baseDomain` to something like `preview.example.com`, and: - add a `*.preview.example.com` host to the web Ingress whose root path targets the orchestrator; - provision a wildcard TLS certificate for `*.preview.example.com` and a wildcard DNS record at the web Ingress's address; - set `orchestrator.sessionCookieDomain` to the domain the app host and the preview domain share, `.example.com` for `app.example.com` and `*.preview.example.com`, so one login covers the dashboard and every app; - put no identity-aware proxy in front of the preview host. The orchestrator is the wall, and an external proxy breaks cross-app calls by rejecting cookieless preflights. For development the default preview domain is `lvh.me` with the orchestrator's port, which resolves to localhost, so apps work over plain HTTP with no DNS or certificate. --- # Connect Slack > Create the Slack app, connect it, and let people start sessions by mentioning it in a thread. Source: https://engramsfactory.com/docs/guides/connect-slack/ Connecting Slack gives you two things: sessions can post to Slack through the organization's connection, and a person can start a session by mentioning the bot in a channel. The second is [Slack threads](https://engramsfactory.com/docs/platform/slack-threads/), a built-in automation that keeps one session per thread and relays the conversation both ways. You bring your own Slack app. The dashboard writes its manifest for you. (Image: The Integrations page, with connected providers and their powers) ## Create the app 1. Open Settings → Integrations → Slack → Connect. The sheet shows the redirect URL and a Copy app manifest button. 2. At api.slack.com/apps, create an app from a manifest and paste what you copied. The manifest names the app `engrams`, requests the bot scopes engrams needs, sets the OAuth redirect URL, subscribes to the mention, message, and reaction events at the events URL, and enables interactivity at the interactivity URL. The three URLs are all under your deployment's public origin: ``` /api/v1/integrations/slack/oauth/callback /api/v1/integrations/slack/events /api/v1/integrations/slack/interactivity ``` 3. From the app's Basic Information page, copy the client ID, the client secret, and the signing secret. The scopes include `users:read.email`, which is how a Slack author is matched to an engrams user. Without a match the bot replies that the person needs to log in to engrams first and starts nothing. ## Connect it Back in the sheet, paste the client ID, the client secret, and the signing secret. The signing secret is optional for the connection itself but required to receive events, so paste it if you want mentions to work. Select Add Slack. engrams seals the three values as org secrets, sends you through Slack's consent screen, and returns to the integration page marked connected. Reconnect from that page at any time forces a fresh consent. ## Turn on Slack threads Mentions do nothing until a channel is mapped to a profile. Open Settings → Automations → Slack threads → Inputs and add the channel to the `channels` map, choosing the profile its sessions run on. A channel that is not in the map is never answered. The other inputs are `default_profile` and the smart routing settings. Then enable the automation. The bot must be a member of a channel to see messages in it. Public channels can be joined by the automation; a private channel needs a person to invite the bot. ## What people get Mention the bot in a channel or a thread. engrams checks that the author is a linked user, starts a session on the channel's profile as that person, with their credentials and git identity, and replies in the thread as the agent works: messages arrive as the agent produces them, questions from the agent become Slack forms, and a reaction marks each turn as in progress and then done. Mention the bot again in the thread to send the next turn to the same session; the replies people wrote in between go with it. The session is kept so someone can pick it up in the dashboard later. ## Direct messages The bot can open a direct message or a group direct message (`slack open`), find a member by email (`slack lookup`), and create a private channel (`slack create private`). A message in a conversation the bot is in, including a direct message, arrives as the `message` event with `event.channel_type` set to `channel`, `group`, `im`, or `mpim`, so an automation can answer inside the conversation it opened. The bot reads a group direct message back with `mpim:history`, which is also the scope the `message.mpim` event needs. An app installed before these scopes existed needs its manifest updated and a Reconnect from the integration page, which runs Slack's consent screen again with the new scopes. ## Personal Slack credentials A profile can be set to act as the person who launched it rather than as the organization. For that, each person connects their own Slack account under Settings → Credentials, which runs the same OAuth flow with user scopes. Sessions started from such a profile post as the person. --- # Connect GitHub > Install a GitHub App so sessions get short-lived, scoped tokens and pull requests get reviewed. Source: https://engramsfactory.com/docs/guides/connect-github/ GitHub is connected through a GitHub App, not OAuth. engrams mints a short-lived installation token for each session, clamped to the permissions that session's profile grants, so no durable GitHub token ever sits in a sandbox. The same App delivers the webhooks that drive pull request review. ## Create the App Settings → Integrations → GitHub walks through four steps. 1. **Register the App.** Either open GitHub's new-app page and fill it in, or copy the manifest from the panel and use GitHub's "register from a manifest" flow. The manifest names the App `engrams`, points its webhook at `/api/v1/integrations/github/events`, and marks it private. 2. **Grant repository permissions.** The minimum is `metadata: read`, `contents: write`, and `pull_requests: write`. The panel lists the optional permissions that enable more of the connector's powers, derived from what the connector can do; a session can never do more than the App is granted. 3. **Add the webhook.** The payload URL is the events URL above. Subscribe to `pull_request`, `pull_request_review`, `pull_request_review_comment`, and `issue_comment`. Set the webhook secret to the value your deployment configured as the org secret `github.webhook_secret`; the Helm value is `forge.github.webhookSecret`. 4. **Install it and copy the credentials.** Install the App on the organization or user that owns the repositories, generate a private key, and paste the numeric App ID and the downloaded key into the connect sheet. The App ID and the key are stored as org secrets; the key is sealed and never returned. ## What sessions get A profile grants GitHub powers, read or write, and each session receives a token minted for exactly those powers, valid for that session. The agent uses it to clone, push, and open pull requests. The token is not the App's key and is not reusable elsewhere. ## Review pull requests Pull request review is the built-in automation named PR review. It listens for pull requests on the repositories you list, runs a finder session and a verifier session on the reviewer profile, settles their findings, and posts them as one GitHub review with an acknowledgment comment that updates with the count. A new push cancels the review in flight and starts over. (Image: The Reviews page, one row per reviewed pull request) To enroll a repository, open Settings → Automations → PR review → Inputs and add it to the `repos` map with a mode: | Mode | When a review runs | |---|---| | `auto` | On every pull request that opens, updates, or leaves draft. | | `on_request` | When a repository owner, member, or collaborator comments `@ review`. | The handle defaults to the App's own login. The other inputs are the reviewer profile, the review categories, and free-text instructions the reviewers read. The Reviews page lists every reviewed pull request with its findings and what was posted. ## Personal GitHub credentials A person can add a fine-grained personal access token under Settings → Credentials. A profile set to act as the launching person uses it instead of the App token, so commits and pull requests carry that person's identity. --- # Connect Linear > Create the Linear OAuth application, connect it, and trigger automations from issues. Source: https://engramsfactory.com/docs/guides/connect-linear/ Connecting Linear lets sessions read and write issues, projects, and comments through Linear's API, and lets automations trigger when an issue or comment is created or updated. ## Create the OAuth application 1. In Linear, open Settings → API → OAuth applications and create one. 2. Set its redirect URI to `/api/v1/integrations/linear/oauth/callback`, where the origin is your deployment's public URL. 3. In the application's webhook settings, set the URL to `/api/v1/integrations/linear/events` and choose a signing secret. Do this before anyone authorizes: Linear provisions the webhook for a workspace at authorization time, and an installation that predates the webhook settings silently has none. If that happens, Reconnect from the integration page provisions it. 4. Copy the client ID and the client secret. ## Connect it Open Settings → Integrations → Linear → Connect, paste the client ID and secret, and select Add Linear. engrams sends you through Linear's consent screen, requesting the `read` and `write` scopes as the application itself, and returns to the integration page marked connected. Add the webhook signing secret as the org secret `linear.webhook_secret` under Settings → Secrets. Webhook deliveries are verified by signature and rejected when their timestamp is more than a minute old. ## What sessions and automations get Sessions on a profile that grants Linear powers can query and mutate issues through the organization's connection; the token is brokered at the egress proxy and never seen by the agent. Automations can trigger on `issue.create`, `issue.update`, and `comment.create`, scoped by team key, and can create issues and comments as actions. ## Personal Linear credentials Under Settings → Credentials a person can connect their own Linear account by OAuth or paste a personal API key. A profile set to act as the launching person then posts as that person rather than as the application. --- # Connect Cortex > Pick the Cortex API host, add a workspace API key, and give sessions the catalog. Source: https://engramsfactory.com/docs/guides/connect-cortex/ Connecting Cortex lets sessions read and update your internal developer portal through Cortex's REST API: catalog entities, scorecards and scores, teams and on-call, custom data, deploys, dependencies, and CQL queries. engrams is built by Cortex, so this integration ships with the product and sits first in the integrations list. ## Pick the API host Cortex Cloud runs in two regions, and some customers run their own instance. Open Settings → Integrations → Cortex → Connect. The first field is the API host: - **Cortex Cloud, US**: `api.getcortexapp.com`. This is the default. - **Cortex Cloud, EU**: `api.eu.cortex.io`. - **Self-hosted**: type the hostname your Cortex API answers on, such as `cortex-api.example.com`. Enter a bare hostname, without a scheme, port, or path. Sessions can reach the host you pick and no other Cortex host. Change it later from the integration page; the change applies to the next session that starts. ## Add a workspace API key 1. In Cortex, open your avatar → Settings → API keys and create a key. Give it only the permissions the sessions need, and set an expiration. 2. Paste the key into the Connect sheet. engrams seals it as the org secret `cortex.api_key` and tests it with one read against the host you picked. The key never enters a sandbox. The egress proxy adds it to each request as a bearer token and removes any token the agent supplies. ## What sessions get A profile grants Cortex powers by area: `catalog:read` covers entities and everything attached to them, and each write is its own power, such as `custom-data:write` or `deploys:write`. The `cortex` command is on the PATH in every session whose profile grants at least one Cortex power. Run `cortex` with no arguments for the command list, or `engrams-integrations` for every connected tool. ```bash cortex search payments cortex entity payments-api cortex scores production-readiness payments-api cortex set-custom-data payments-api last-audit '{"date":"2026-09-21"}' cortex query 'entity.type = "service" AND scorecard("production-readiness").score < 50' ``` Entity and team deletion, bulk deletes, API key management, secrets, the IP allowlist, and the integration-configuration endpoints are not reachable through this connector. ## Personal Cortex tokens Under Settings → Credentials a person can paste a personal access token from their Cortex avatar → Settings → Preferences → My access tokens. A profile set to act as the launching person then calls Cortex with that person's own permissions instead of the workspace key. Personal tokens use the same API host the administrator picked. --- # Connect Vanta > Create Vanta API credentials, connect them, and let sessions run your compliance program. Source: https://engramsfactory.com/docs/guides/connect-vanta/ Connecting Vanta lets sessions read and update your compliance program through the Manage Vanta API: people and their security tasks, automated tests and the entities failing them, controls and frameworks, policies, evidence documents, issues, vendors and their reviews, risk scenarios, vulnerabilities, connected integrations, Trust Center, and customer-trust questionnaires. Vanta webhooks can also start automations. Vanta issues a short-lived token from a client id and a client secret. engrams obtains the token server-side and obtains a new one before it expires, so there is no consent screen and nothing to renew by hand. ## Create the API credentials 1. In Vanta, open Settings → Developer Console and create an application of the Manage Vanta kind. Give it the `vanta-api.all:read` and `vanta-api.all:write` scopes. engrams asks for both; a token request for a scope the application lacks is refused by Vanta. 2. Generate a client secret and copy the client id and the secret. Vanta keeps one active token per application. Use these credentials for engrams alone, or each new token revokes the one the other consumer holds. ## Connect it Open Settings → Integrations → Vanta → Connect, paste the client id and the client secret, and select Add Vanta. engrams seals the two values as the org secrets `vanta.client_id` and `vanta.client_secret`, obtains the token, seals it, and marks the integration connected. Reconnect from the integration page obtains a fresh token from the sealed credentials, for example after you rotate the secret and paste the new value. The token never enters a sandbox. The egress proxy adds it to each request as a bearer token and removes any token the agent supplies. ## What sessions get A profile grants Vanta powers by area, each split into read and write: `people:read` and `people:write`, `tests:read` and `tests:write`, `controls`, `frameworks`, `documents`, `vendors`, `risks`, `vulnerabilities`, `integrations`, `trust-center`, and `customer-trust`. `issues:read`, `policies:read`, and `organization:read` are read-only because the API offers no writes there. `resources:write` lets a session push its own evidence to Vanta as a custom integration. The `vanta` command is on the PATH in every session whose profile grants at least one Vanta power. It is a generic client over the whole API: every resource is reached through `list`, `get`, `create`, `update`, and `delete`, `resources` prints the resource table with the verbs each supports, and `api` reaches any other route, such as the action endpoints. Query fields pass straight through as the API's filters, and `list` follows every page and prints one JSON array. Run `vanta` with no arguments for the command list, or `engrams-integrations` for every connected tool. ```bash vanta list people tasksSummaryStatusMatchesAny=OVERDUE vanta list people taskTypeMatchesAny=ACCEPT_POLICIES,COMPLETE_TRAININGS taskStatusMatchesAny=DUE_SOON vanta list tests statusFilter=NEEDS_ATTENTION vanta list issues statusMatchesAny=NOT_STARTED,IN_PROGRESS dueBeforeDate=2026-11-15T23:59:59Z vanta get people vanta api POST controls//set-owner '{"userId":""}' ``` ## Receive Vanta events Vanta sends webhooks for questionnaires, Trust Center access requests, vendor decisions, and, for auditor accounts, information requests, evidence, and control comments. Vanta sends no webhook when a test fails or a person's task becomes overdue; an automation on a schedule reads those with the commands above. 1. In the Connect sheet, or later under Settings → Secrets, paste the endpoint's signing secret as `vanta.webhook_secret`. The secret starts with `whsec_` and is shown in Vanta under Settings → Webhooks after you add the endpoint. 2. In Vanta, add the endpoint and choose the events you want: ``` /api/v1/integrations/vanta/events ``` Each delivery is verified against the signing secret, and a delivery older than five minutes is refused. The events then appear as triggers under Automations. --- # Connect Rippling > Create a Rippling API token, connect it, and give sessions your org chart and HR records. Source: https://engramsfactory.com/docs/guides/connect-rippling/ Connecting Rippling lets sessions read your HR system through the Rippling REST API: workers and their managers, users, departments, teams, locations, titles and levels, employment types, legal entities, leave, time, devices, worker changes, the activity log, custom objects, and reports, plus the writes Rippling exposes on those records. ## Create an API token Rippling's REST API is part of the Rippling API subscription, and the token is created by an admin in the API Tokens app. If the app shows "Permission denied", your company has no API subscription, the app is not installed, or your admin role lacks the permission to manage tokens; a Rippling account owner resolves that in Rippling. 1. In Rippling, open the API Tokens app (`app.rippling.com/api-tokens`, or search for it from the dashboard) and create a new token. Give it a name, pick the API version, and choose the scopes the sessions need; each read command below names the scope family it uses, such as `workers.read` or `departments.read`. 2. Copy the token; Rippling shows it once. Rippling revokes a token that is unused for 30 days or whose owner leaves, so create it under a service admin where you can. ## Connect it Open Settings → Integrations → Rippling → Connect and paste the token. engrams seals it as the org secret `rippling.api_token` and tests it with one read of the company record. The token never enters a sandbox. The egress proxy adds it to each request as a bearer token and removes any token the agent supplies. Fields the token is not entitled to read come back redacted, listed under `__meta.redacted_fields` in each response. ## What sessions get A profile grants Rippling powers by area, each split into read and write: `workers:read`, `org:read` and `org:write` (departments, teams, locations, titles, levels, job catalog), `hiring`, `compensation`, `payroll`, `leave`, `time`, `devices`, `custom-objects`, `reports`, `files`, `workflows`, `activity-log:read`, and `company:read`. Workers, users, and the activity log are read-only because the API offers no writes there. The `rippling` command is on the PATH in every session whose profile grants at least one Rippling power. It is a generic client over the whole API: every resource is reached through `list`, `get`, `create`, `update`, and `delete`, `resources` prints the resource table with the verbs each supports, and `api` reaches any other route. Query fields pass straight through in Rippling's own `filter`, `expand`, and `order_by` syntax, and `list` follows every page and prints one JSON array. Run `rippling` with no arguments for the command list, or `engrams-integrations` for every connected tool. ```bash rippling list workers "filter=work_email eq 'someone@example.com'" expand=user,manager rippling list workers "filter=manager_id eq ''" expand=user rippling list worker-changes "filter=updated_at gt '2026-10-01T00:00:00Z'" rippling get departments rippling create leave-requests '{"worker_id":"","leave_type_id":"","start_date":"2026-11-02","end_date":"2026-11-03"}' rippling api POST custom-objects//records/query '{"query":"SELECT * FROM ..."}' ``` Rippling sends customer webhooks only for custom-object records, so an automation that reacts to HR changes runs on a schedule and reads `rippling list worker-changes` for the window since its last run. The developer-platform surfaces (apps, functions, packages, sandboxes, listings, and sites) are not reachable through this connector. --- # Connect Google Workspace > Give sessions your Google Workspace directory as the organization, and each member their own Gmail, Calendar, and Drive. Source: https://engramsfactory.com/docs/guides/connect-google-workspace/ Connecting Google Workspace gives sessions two things. The organization connection reads the directory: people and their managers, groups and members, organizational units, domains, and the audit reports. A member's own connection reaches their Gmail, Calendar, Drive, Docs, Sheets, Slides, and contacts as them. The organization connection is a Google service account with domain-wide delegation for the directory read scopes only. It acts as one account you name, and Google refuses it a token for anything outside the delegated scopes, so it can never read a mailbox or a drive. engrams signs a short-lived token request with the sealed key and obtains a new token before each one expires; there is no consent screen and nothing to renew by hand. ## Create the service account 1. In the Google Cloud console, create a project (or pick one) and open IAM & Admin → Service accounts. Create a service account; it needs no project roles. 2. Open the service account, go to Keys, and add a JSON key. Keep the downloaded file; you paste it into engrams. 3. Note the service account's numeric client ID, shown on its details page. ## Delegate the directory scopes In the Google Admin console, open Security → Access and data control → API controls → Manage domain-wide delegation, and add the client ID with exactly these scopes: ``` https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly, https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.reports.audit.readonly ``` Delegate nothing else. The account the connection acts as must be able to read the directory; a user with the Groups Reader and User Management Reader admin roles is enough. Google can take some minutes to apply a new delegation. ## Create the OAuth client Members connect their own account through an OAuth client of your organization. 1. In the same Google Cloud project, open APIs & Services → OAuth consent screen and choose the Internal user type. An internal app needs no Google verification. 2. Under Credentials, create an OAuth client ID of the Web application type and add this redirect URI: ``` /api/v1/integrations/google_workspace/oauth/callback ``` 3. Copy the client ID and client secret. 4. Enable the APIs the sessions use under APIs & Services → Library: Admin SDK, Gmail, Google Calendar, Google Drive, Google Docs, Google Sheets, Google Slides, and People. ## Connect it Open Settings → Integrations → Google Workspace → Connect. Paste the service account's JSON key, the email of the account it acts as, and the OAuth client ID and secret, then select Add Google Workspace. engrams seals the values as the org secrets `google_workspace.service_account_key`, `google_workspace.client_id`, and `google_workspace.client_secret`, obtains the organization token, seals it, and marks the integration connected. Reconnect from the integration page obtains a fresh token with the same account. Each member who needs their own Gmail, Calendar, or Drive connects under Settings → Credentials → Google Workspace, which opens Google's consent screen for the scopes the connector asks for. A profile chooses per integration whether a human session uses the member's connection or the organization's. The tokens never enter a sandbox. The egress proxy adds the right one to each request as a bearer token and removes any token the agent supplies. ## What sessions get A profile grants powers by API area. The organization connection serves `directory:read` and `reports:read`. The personal areas are `gmail:read`, `gmail:write`, `calendar:read`, `calendar:write`, `drive:read`, `drive:write`, `docs:read`, `docs:write`, `sheets:read`, `sheets:write`, `slides:read`, `slides:write`, and `contacts:read`. Two commands are on the PATH in every session whose profile grants at least one Google Workspace power. `google` is a generic REST client for the directory and the audit reports; its `list` follows every page and prints one JSON array. `gws`, Google's Workspace CLI, covers Gmail, Calendar, Drive, Docs, Sheets, Slides, and contacts, and takes the same `--params` JSON that each API documents. Run either with `--help`, or `engrams-integrations` for every connected tool. ```bash google list directory/users customer=my_customer google get directory/users/someone@example.com projection=full google list directory/groups/team@example.com/members gws drive files export --params '{"fileId":"","mimeType":"text/plain"}' gws calendar events list --params '{"calendarId":"primary","timeMin":"2026-11-01T00:00:00Z"}' ``` A user's manager is the `relations` entry of type `manager` on the user record. It is filled in only when your HR system writes it to Google; Rippling's Google Workspace integration has a Manager attribute mapping that is off by default. Google sends no plain webhooks, so an automation that reacts to Workspace data runs on a schedule and reads with the commands above. --- # CLI > The engrams command, its authentication model, and every subcommand. Source: https://engramsfactory.com/docs/reference/cli/ `engrams` is the product CLI. It talks to the orchestrator over the same API the dashboard uses, and nothing else; the coordinator and the hosts are internal to a deployment. ## Install The CLI is a single static binary for Linux x86-64, Linux arm64 and macOS arm64. The installer downloads the build for your machine from the GitHub release, checks its checksum, and puts it on your `PATH`: ```sh curl -fsSL https://engramsfactory.com/install.sh | sh ``` With Homebrew: ```sh brew install cortexapps/tap/engrams ``` There are two channels. **stable** is the newest release (`0.11.0`, `0.12.0`, …). **nightly** is a prerelease built from `main` each night, versioned after the release it precedes (`0.12.0-rc.1`, `0.12.0-rc.2`, …). The installer takes `ENGRAMS_CHANNEL=nightly`, or an exact version with `ENGRAMS_VERSION=0.12.0-rc.3`; Homebrew has the formula `engrams-nightly`. To upgrade, run the installer again or `brew upgrade`. The installer puts the binary in `/usr/local/bin` when that is writable, else in `~/.local/bin`; `ENGRAMS_INSTALL_DIR` sets another directory. Each release also lists the binaries and their `SHA256SUMS` on its GitHub page. To build the CLI from the repository: ```sh cargo build --profile cli -p engram-cli # -> target/cli/engrams ``` ## Authentication The CLI follows the `gh` model. The API key comes from, in order: 1. `ENGRAMS_API_KEY` in the environment. For CI and scripts; never written to disk. 2. The key stored for the active host in `~/.config/engrams/hosts.json`, written by `engrams auth login`. `engrams auth login` runs a device-code flow: it prints a one-time code, you approve it in the dashboard, and the CLI stores a durable personal API key under the host's URL. The file is mode 0600 and keyed by host, so one machine can hold credentials for a production deployment and a local stack side by side. `engrams auth logout` revokes the key and forgets it. The host is `--url`, then `ENGRAMS_URL`, then the CLI's built-in default. Set `ENGRAMS_URL` to your deployment's URL; for the local stack it is `http://localhost:8787`. ## Output Every command prints a human-readable table by default. `--json` prints pretty JSON on stdout and nothing else, for `jq` and scripts. Errors go to stderr as `engrams: …` with exit code 1. `session exec` exits with the remote command's exit code. ## Commands Global flags: `--url `, `--json`. ### `auth` | Command | What it does | |---|---| | `auth login` | Authenticate through the browser and store an API key for this host. | | `auth logout` | Revoke the stored key for this host and forget it. | | `auth status` | Show who you are logged in as. | ### `task` Tasks are the product-level unit of work: a profile plus a prompt. | Command | What it does | |---|---| | `task create --profile [--prompt ] [--title ] [--harness ] [--model ] [--effort ] [--mode ]` | Start a task from a profile. Prints the primary session id. The overrides replace the profile's harness, model, and reasoning effort; `--mode plan` starts the first turn in plan mode. | | `task list` | List your tasks. Admins also see sessions that belong to no task. | | `task get ` | Print one task with its sessions. | | `task delete ` | Delete a task and tear down its sessions. | ### `session` | Command | What it does | |---|---| | `session create --image [--harness ] [--prompt ] [--dev-vm]` | Boot a session from a raw image URI with no profile. An admin's escape hatch. `--dev-vm` starts a VM with no harness, for use through `exec`. | | `session list` | List sessions. | | `session get ` | Print one session. | | `session exec [--timeout-secs ]` | Run a shell command in the sandbox, streaming its output, and exit with its exit code. | | `session shell ` | An interactive shell in the sandbox, in your terminal. Exit the shell to return. | | `session logs [--since ]` | Tail the session's event log. `--since N` replays everything after index N first. Ctrl-C to stop. | | `session log [--limit ] [--from-start]` | Print the conversation timeline, newest rows first by default. | | `session resume ` | Resume an idle session from its snapshot. | | `session prompt ` | Send a prompt. Resumes the session first if it is idle. | | `session delete ` | Mark the session completed and tear down its sandbox. | ### `image` | Command | What it does | |---|---| | `image list` | List the enabled images sessions may use. | | `image enable --uri --name --vcpus [--description ] [--workdir ] [--memory-mib ] [--disk-gib ] [--swap-mib ] [--env KEY=VALUE]... [--no-wait]` | Enable an image: materialize it and capture its base snapshot. `--name` and `--vcpus` are required the first time. The warm hook is set in the dashboard. Polls the job to ready unless `--no-wait`. | | `image config --uri ` | Print an enabled image's stored config as JSON. | | `image update --uri [the same flags] [--allow-recapture] [--no-wait]` | Change an image's config; flags you do not pass keep their stored values. Edits that change the base snapshot need `--allow-recapture`. | | `image disable --uri ` | Disable an image. The registry artifact is untouched. | | `image refresh --uri [--recapture]` | Re-fetch a tag that moved, and optionally force a new capture. | | `image jobs` | List recent enable and refresh jobs. | | `image job ` | Print one job, including the warm hook's current stage. | | `image poll-job ` | Poll a job until it is ready or failed. | | `image retry-job [--no-wait]` | Re-queue a failed job. | ### `registry` Registry credentials are envelope-encrypted on the server and never returned. | Command | What it does | |---|---| | `registry add --host [--auth-kind static\|gcp-workload-identity] [--username ] [--password-file ] [--password-stdin] [--impersonate-sa ]` | Add or update the credential for a registry host. | | `registry list` | List registry credentials, with passwords masked. | | `registry rm ` | Remove a credential. | ### `host` Fleet operations, admin only. | Command | What it does | |---|---| | `host list` | List hosts with their capacity. | | `host get ` | Print one host. | | `host drain ` | Mark a host draining; new sessions avoid it. | | `host uncordon ` | Clear a cordon; the host returns to ready. | | `host evacuate ` | Move one session off its host; it resumes on a peer. | | `host delete ` | Deregister a host. Refused while sessions are bound to it. | ### `profile` | Command | What it does | |---|---| | `profile list` | List the profiles you can launch. | | `profile get ` | Print one profile. | Profiles are created and edited in the dashboard. ### `apikey` Global service-account keys, admin only. Your own login key is managed by `auth`. | Command | What it does | |---|---| | `apikey create --name [--role admin\|user] [--expires-at ]` | Mint a key. The plaintext is printed once, alone, on stdout. | | `apikey list` | List keys with a masked preview. | | `apikey revoke ` | Revoke a key. | ### `admin` Explicit triggers for things engrams otherwise does on its own schedule. | Command | What it does | |---|---| | `admin evict-idle ` | Run the idle-eviction pipeline for one session now. The session ends idle. | | `admin gc [--apply] [--grace-secs ]` | Run the blob garbage-collection sweeps. A report only, unless `--apply`. | ### `tui` `engrams tui [session-id] [--no-alt-screen] [--no-mouse] [--ax]` opens a terminal client. With no session id it shows your sessions; with one it attaches to that session. The transcript streams as the agent works, tool calls fold to their first lines (Ctrl+O expands the last one), and questions and plan approvals are answered with the number keys. Code blocks and file changes are syntax highlighted in your terminal's colors. `?` lists the keys. Drag across the transcript to select text: it is copied when you let go, and the footer says how much. `Esc` clears the selection, `Ctrl+C` copies it again. The copy uses your system's clipboard command, or asks the terminal to set its clipboard (OSC 52) over SSH. On the session list, `j`/`k` move, `g`/`G` jump to the top and bottom, `/` filters (Esc returns to the keys), `n` starts a new session and `r` reloads. In any list or popup `Ctrl+N`/`Ctrl+P` and `Ctrl+J`/`Ctrl+K` move as well as the arrows. | Key | What it does | |---|---| | `Enter` | Send the draft. While a run is active it is queued; `Up` pulls it back. | | `Shift+Enter`, `Ctrl+J` | Newline in the draft. | | `Esc` | Interrupt the run. On a draft, twice clears it. | | `Ctrl+C` | Clear the draft; twice quits. | | `Ctrl+D` | On an empty draft, back to the session list; twice quits. | | `Ctrl+P`, `Alt+↑/↓` | Switch session. | | `Ctrl+N` | New session: pick a profile, type the first prompt. | | `Ctrl+\``, `Ctrl+Space` | A shell in the sandbox below the transcript. The same key hands the keys back to the agent. | | `Ctrl+T` | Search the transcript. | | `Ctrl+G` | Edit the draft in `$EDITOR`. | | `PgUp`, `PgDn`, `Ctrl+Home`, `Ctrl+End` | Scroll. Scrolling to the top loads older history. | | `Ctrl+A`/`E`, `Ctrl+B`/`F`, `Alt+B`/`F` | In a draft, the editing keys Codex uses: line start/end, character, word. `Ctrl+D`, `Ctrl+H`, `Alt+D`, `Alt+Backspace`, `Ctrl+W`, `Ctrl+U`, `Ctrl+K` and `Ctrl+Y` delete and yank. | A draft that starts with `/` is a command. Type `/` to list them; Tab completes. | Command | What it does | |---|---| | `/new` | New session (the same as Ctrl+N). | | `/sessions` | Back to the session list. | | `/shell` | The sandbox shell. | | `/interrupt` | Stop the current run. | | `/resume` | Resume an idle session without sending a prompt. | | `/transcript` | Open the loaded transcript as text in `$EDITOR`. | | `/dump` | Write the loaded transcript to the terminal's scrollback, to read after you leave. | | `/help`, `/quit` | The key list; leave. | The TUI tells your terminal what the session needs from you. A terminal that supports the [Program Status Protocol](https://www.superlogical.com/rex/docs/build/program-status) (OSC 7501) gets one status: `working` during a run (with the agent's task list as a percentage), `blocked` when a question, a plan approval or a sign-in waits on you, `done` or `error` when a run ends, and `idle` otherwise. A result stays `done` until you press a key, paste, click or scroll. Other terminals see the state in the window title. When the terminal is not focused, a question, a finished run or a failure also posts a desktop notification (OSC 9) on iTerm2, Ghostty, Kitty, Warp and WezTerm, and rings the bell elsewhere. Beside that status, the terminal gets one entry for each running subagent, for the sandbox while it starts, resumes or moves, and for programs in the shell pane that report their own status. Your other sessions are there too: each one that waits on you, runs, or finished or failed while you were elsewhere. The TUI checks them every 5 seconds while the session list is open and every 15 seconds otherwise while the terminal takes these reports, and a finished entry stays until you open that session. Flags and environment: - `ENGRAMS_PROGRAM_STATUS=1` or `0` turns the status on or off without asking the terminal, for example inside a multiplexer that does not pass the reply through. `0` also turns off the status that `auth login` and `session exec` report while they wait. - `--no-alt-screen` (or `ENGRAMS_TUI_NO_ALT_SCREEN=1`) keeps the terminal's own scrollback. Finished turns are written into it as they complete and only the composer and footer stay live, so your terminal's scroll, search and copy work on the transcript. The mouse is left to the terminal in this mode. History older than the loaded window is not paged in this mode. - `--no-mouse` (or `ENGRAMS_TUI_NO_MOUSE=1`) leaves the mouse to the terminal, for its own text selection. - `--ax` (or `ENGRAMS_TUI_AX=1`) is screen-reader mode: native scrollback, no mouse, and word labels (`you:`, `agent:`, `tool:`) in place of glyphs. - `NO_COLOR` turns color off, syntax highlighting included. State markers carry their meaning without it. - Secondary text (receipts, hints, the `… N more lines` tails) uses your terminal's dim attribute on your own foreground color, never a fixed grey, so it follows your theme. `ENGRAMS_TUI_NO_DIM=1` turns the attribute off when it is still too faint. - The colors the TUI picks itself (inline code, links, headings, diff and status tones) adapt to your terminal. When the terminal reports its background color, the TUI uses the engrams palette for a light or a dark ground and checks each color for WCAG AA text contrast against that background, moving it toward black or white when it falls short. A terminal that does not answer keeps its own ANSI palette. --- # API overview > The Connect RPC surface the dashboard and CLI use, and the few routes that live outside it. Source: https://engramsfactory.com/docs/reference/api/ The orchestrator serves one API, and the dashboard and the CLI are both clients of it. It is [Connect RPC](https://connectrpc.com) over HTTP/1.1, so every method is a POST with a JSON or protobuf body, callable with `curl` and with generated clients in any language Connect supports. ``` POST /rpc/engram.app.v1./ ``` Authenticate with an API key in the `x-api-key` header. Personal keys come from `engrams auth login`; service-account keys are minted by an admin in Settings or with `engrams apikey create`. ```sh curl -s "$ENGRAMS_URL/rpc/engram.app.v1.SessionService/ListSessions" \ -H "x-api-key: $ENGRAMS_API_KEY" \ -H "content-type: application/json" \ -d '{}' ``` ## Services The orchestrator implements some services itself and forwards others to the coordinator. The distinction does not matter to a client; every method is at the same path with the same authentication. The [API reference](https://engramsfactory.com/docs/api/) has one page per service with every method and message, generated from the proto files. | Service | What it covers | |---|---| | `TaskService` | Create, list, get, and delete tasks. | | `SessionService` | Create, list, get, and delete sessions; exec; prompt; resume; snapshot; the conversation log. | | `ProfileService` | List and get profiles. | | `ImageService` | Enable, update, disable, and refresh images; registry credentials; enable jobs. | | `HarnessCatalogService` | The harnesses a deployment offers, with their models, modes, and effort levels. | | `FleetService` | Hosts, capacity, drain, cordon, and evacuation. Admin only. | | `ApiKeyService` | Global API keys. Admin only. | | `IntegrationService` | Connectors, connections, and the integration catalog. | | `OrgSecretService` | Org secrets such as `ANTHROPIC_API_KEY`. Admin only. | | `ModelRouterService` | Model routers such as OpenRouter and their model catalogs. | | `ReviewService` | Pull request reviews and per-repository enrollment. | | `AutomationService`, `AutomationRunService`, `WebhookRegistrationService` | Automations, their runs, and inbound webhooks. | | `ArtifactService` | Documents published from a session. | | `MountCatalogService` | Skills available to profiles. | | `OAuthCredentialService` | Per-user OAuth credentials for Claude Code, ChatGPT, Slack, Linear, and GitHub. | | `PapercutService`, `PrRefService`, `IntegrationOpService`, `MintService` | Friction reports from agents, pull request references, integration operations, and short-lived credential minting. | The service definitions are the `.proto` files under [`crates/engram-protocol/proto/engram/app/v1/`](https://github.com/cortexapps/engrams/tree/main/crates/engram-protocol/proto/engram/app/v1) in the repository. Generate a client with [Buf](https://buf.build) and the Connect plugin for your language; the repository's `buf.gen.yaml` shows how the dashboard and CLI generate theirs. ## Outside the RPC surface A few things are plain HTTP routes because they stream or carry bytes. | Route | What it does | |---|---| | `GET /api/v1/sessions//events` | The session's event stream as server-sent events. Send `Last-Event-ID` to resume after a disconnect. | | file upload and download routes on a session | Move files in and out of a sandbox. `engrams session exec` and the dashboard's file panel use them. | | a WebSocket route per session | The interactive shell relay behind the dashboard's shell tab. | | `/api/auth/*` | Sign-in, the device-code flow that `engrams auth login` uses, and OAuth callbacks. | ## Versioning The API is under `engram.app.v1` and is not yet frozen: methods are added and, less often, changed between releases. A deployment's dashboard, CLI, and orchestrator are built from one commit and move together; a client you write against the proto files should be regenerated when you upgrade. --- # Configuration > The environment variables the coordinator and the host agent run on, and how secrets, the master key, and the egress CA reach them. Source: https://engramsfactory.com/docs/reference/configuration/ The Helm charts set every variable on this page. The tables are the reference for what lands where, for anyone reading a manifest or running a component outside the charts. ## Coordinator | Variable | Purpose | |---|---| | `DATABASE_URL` | Postgres connection string, from the coordinator's Secret. | | `ENGRAM_AUTH_TOKENS` | Comma-separated bearer tokens that hosts and the orchestrator present. | | `ENGRAM_APP_GRPC_TOKENS` | The orchestrator's bearer for the coordinator's private RPC port. Empty means every call is refused. | | `ENGRAM_BLOB_BACKEND` | `gcs`, `s3`, or `local` for development. | | `ENGRAM_GCS_BUCKET` | With `gcs`: the chunks bucket. | | `ENGRAM_S3_BUCKET`, `ENGRAM_S3_REGION`, `ENGRAM_S3_ENDPOINT_URL` | With `s3`: the bucket, the signing region, and an optional endpoint for S3-compatible stores such as MinIO or R2, which switches the client to path-style addressing. | | `ENGRAM_KEK_PROVIDER` | `env-var` or `aws-kms`. | | `ENGRAM_KEK_MASTER_KEY` | With `env-var`: the base64 32-byte master key. | | `ENGRAM_KEK_AWS_KEY_ID` | With `aws-kms`: the KMS key id, ideally the ARN. | | `ENGRAM_SECRETS_BACKEND` | `gcp`, `aws`, or `env` for development. | | `ENGRAM_GCP_PROJECT_ID` | With `gcp`: the Secret Manager project. | | `ENGRAM_CHUNK_GC_INTERVAL_SECS`, `ENGRAM_CHUNK_GC_RETAIN_SECS` | How often chunk garbage collection runs, and how long an unreferenced chunk is kept before deletion. | | `ENGRAM_PLACEMENT_POOL_FLOOR_BYTES` | Free space a node's session-disk pool must keep for the scheduler to place a new session on it; default 16 GiB. A node deletes the checkpoint volumes of evicted sessions it kept for a fast resume when its free space falls under twice this value, so set it on the host agents too. | Cloud credentials are ambient: Workload Identity on GKE, IRSA on EKS, bound to the coordinator's ServiceAccount. There are no key files. ## Host agent | Variable | Purpose | |---|---| | `ENGRAM_COORDINATOR_ENDPOINT` | `http://:8080`. Registration and heartbeats are HTTP POSTs. | | `ENGRAM_COORDINATOR_TOKEN` | Must be one of the coordinator's `ENGRAM_AUTH_TOKENS`. | | `ENGRAM_SANDBOX_BACKEND` | `firecracker` in production. | | `ENGRAM_KERNEL_IMAGE_PATH` | The guest kernel staged on the node. | | `ENGRAM_BLOB_BACKEND` and the bucket variables | Must match the coordinator's. | | `ENGRAM_THIN_POOL` | The name of the node's session-disk pool, as node-prep built it. Required for the Firecracker backend; unset, the macOS and process backends keep volumes as sparse files under the working directory. | | `ENGRAM_FC_UFFD_BASE_DIR` | The tmpfs that holds each image's canonical memory. | | `ENGRAM_FC_VM_CGROUP_PARENT` | A node-level cgroup the VMs move into, so a host-agent pod restart does not kill them. | | `ENGRAM_EGRESS_PROXY_PORT`, `ENGRAM_EGRESS_DNS_PORT`, `ENGRAM_GUEST_GATEWAY_PORT` | The proxy's listeners. Mandatory and non-zero; guest traffic is redirected to them. | | `ENGRAM_EGRESS_CA_SOURCE` | Where the proxy's certificate authority comes from. See below. | | `ENGRAM_WARM_STALL_SECS` | The stall budget for warm hooks during capture; default 120. | ## The master key The coordinator envelope-encrypts registry credentials and per-session secret bundles under a master key. On GCP the provider is `env-var`: a 32-byte key lives in Secret Manager and the External Secrets relay places it in the coordinator's Secret. On AWS the provider is `aws-kms`: the data keys are encrypted and decrypted by KMS under a customer-managed key, and no key material reaches a pod. A missing or wrong master key fails the coordinator at boot, on purpose. Encrypted rows are bound to the provider that wrote them; there is no migration between providers, so the choice is made when a deployment is created. ## Secret references Secrets a session needs are resolved when the session is created, through the configured backend, with the coordinator's ambient identity. | Backend | Reference syntax | Default name when no reference is given | |---|---|---| | `gcp` | `gcp-sm://projects/

/secrets//versions/` | `--` | | `aws` | `aws-sm://[#version-stage]` | `engram//`, so an IAM policy can scope by prefix | ## The egress proxy's certificate authority Every host intercepts guest TLS on port 443 to enforce the allow-list, so every host needs the proxy's CA certificate and key, and every host in a fleet needs the same pair so a migrated session keeps trusting its new host. How the pair reaches a host depends on the cloud, for one reason: the host-agent pod shares the node's network namespace. | `ENGRAM_EGRESS_CA_SOURCE` | When | |---|---| | `env` | GCP production. A pod on the node's network bypasses Workload Identity and runs as the node's scope-limited identity, so a direct Secret Manager read is refused. The External Secrets relay, which does have Workload Identity, syncs the PEMs into a Kubernetes Secret and the DaemonSet injects them as `ENGRAM_EGRESS_CA_CERT_PEM` and `ENGRAM_EGRESS_CA_KEY_PEM`. | | `aws-secrets-manager` | AWS production. IRSA is file-based and works on the node's network, so the host agent reads the two secrets named in `ENGRAM_EGRESS_CA_AWS_CERT_SECRET` and `ENGRAM_EGRESS_CA_AWS_KEY_SECRET` itself. | | `gcp-secret-manager` | Only where Workload Identity is honored, which the fleet's pods are not. | | `local-disk` | Development on a single host. Never for a fleet: a session that migrates would not trust the new host's CA. | Rotating the CA is a rolling redeploy of the host agents. The memory substrate's cache invalidates on its own, because the CA's fingerprint is part of its file names. ## DNS and the one bypass Guest DNS on port 53 is redirected to the proxy, which checks names against the same allow-list as the TLS interception. The one transport-layer bypass is DNS over HTTPS: if a profile allows a DoH endpoint such as `cloudflare-dns.com` or `dns.google`, guests can resolve any name through it on port 443. The mitigation is operator-side. Do not allow-list one. ## Health endpoints The coordinator serves two unauthenticated endpoints on port 8080. `/healthz` returns 200 whenever the process is up. `/readyz` returns 200 only when Postgres answers a `SELECT 1`, and 503 otherwise. Wire the liveness probe to the first and the readiness probe to the second. --- # Helm chart: engram > The control-plane chart, what it deploys and does not, and the values that matter. Source: https://engramsfactory.com/docs/reference/helm-engram/ `deploy/helm/engram` deploys the control plane to any Kubernetes cluster: the coordinator, the orchestrator, and nginx serving the dashboard. The chart is cloud-agnostic; the bindings that differ per cloud, such as Workload Identity, KMS, and load-balancer annotations, live in the `values-gcp.yaml.example` and `values-aws.yaml.example` overlays, and the Terraform quickstarts render a second overlay with every value they know. ## What it deploys **The coordinator.** A stateless Deployment with `replicaCount` replicas, a ClusterIP Service for in-cluster traffic, a ServiceAccount annotated for the cloud's identity binding, and a ConfigMap of non-secret settings. Optionally a HorizontalPodAutoscaler, a PodDisruptionBudget, and a NetworkPolicy. The coordinator's Ingress is off by default and should stay off: the coordinator has no authentication of its own for people. **The web frontend.** With `web.enabled`, an nginx Deployment that serves the dashboard and reverse-proxies API calls, event streams, and WebSockets to the orchestrator, plus the Service the public Ingress targets. The web Ingress is the only public surface of a deployment. **The orchestrator.** With `orchestrator.enabled`, the Deployment that owns sign-in, tasks, profiles, integrations, and the API. Its settings live under the `orchestrator` block. ## Sign-in Every setting for how a person signs in is in `orchestrator.auth`. `mode` selects one door, and only that door is open. | `auth.mode` | The door | Settings | |---|---|---| | `oauth` (default) | A "Continue with" button for one OIDC identity provider: Google, Okta, Auth0, Keycloak, Cognito. | `oauth.issuer`, `oauth.clientId`, `oauth.clientSecret`, and the allowlist `oauth.allowedDomains` and `oauth.allowedEmails`. | | `iap` | GCP Identity-Aware Proxy in front of the app host. | `iap.audiences`. IAP's IAM binding decides who gets in. | | `password` | Email and password. | `password.signup` opens or closes registration. | `auth.adminEmails` names the accounts that become admins on first sign-in, in every mode. An OAuth client admits every account its provider has, so `oauth` mode needs an allowlist and the chart does not render without one. The orchestrator checks it on every sign-in. For Google the domain is the Workspace organization of the account, not the text of the address. `allowedDomains: ["*"]` admits every account the provider authenticates, which is correct for a provider that holds only your own people. `password` mode does not verify an address at sign-up. With `password.signup: true`, anyone who can reach the login page can register any address, an admin address included. Use it for evaluation, or on a network the internet cannot reach. The chart fails the render when the active mode is missing a setting, and it renders only the active mode's settings, so the other two blocks can stay filled in. ## What it does not deploy - **Postgres.** Bring your own: Cloud SQL, RDS, or an in-cluster operator. The connection string comes from a Secret named by `database.existingSecret`. - **The blob bucket.** Provisioned outside the chart, by Terraform, and named in `blob`. - **The host fleet.** That is the [`engram-host-fleet` chart](https://engramsfactory.com/docs/reference/helm-engram-host-fleet/). - **The master key.** A KMS key on AWS, or a base64 key placed in the coordinator's Secret on GCP. - **The managed certificate and load balancer.** Terraform creates them; the chart references them by name in annotations. ## Prerequisites A cluster (GKE 1.28 or later with Workload Identity, EKS 1.28 or later with IRSA, or any conformant cluster with a Secret-based master key for development), a Postgres the pods can reach, and a Secret named by `database.existingSecret` (default `engram-coordinator-secrets`) that carries `DATABASE_URL`, `ENGRAM_AUTH_TOKENS`, and, with the `env-var` master-key provider, `ENGRAM_KEK_MASTER_KEY`. The coordinator runs migrations at boot. ## The values that matter `values.yaml` is annotated line by line; this is the map of its sections. | Section | What it sets | |---|---| | `replicaCount`, `image`, `imagePullSecrets` | Coordinator replicas and image. The defaults point at the published images on GHCR. | | `mode` | `coordinator` for a real deployment. `all` runs a host agent inside the coordinator pod and is for single-binary development only. | | `blob` | `backend` (`gcs`, `s3`, `local`), and the bucket, region, and endpoint for it. The key names match the fleet chart so the two agree. | | `kek` | The master-key provider and its key: `env-var` with `envVarName`, or `aws-kms` with `awsKeyId`. | | `secrets` | The secret backend, `gcp` with `gcpProjectId` or `aws`. | | `database` | The Secret and key that hold `DATABASE_URL`. | | `auth` | The Secret and key that hold the machine bearer tokens. | | `appGrpc` | The coordinator's private RPC port for the orchestrator, and the Secret with its bearer. Required in production; an empty bearer refuses every call. | | `forge` | An optional GitHub App so agents can fetch short-lived git credentials and open pull requests without a durable token in the sandbox. | | `service`, `serviceInternal`, `ingress` | The coordinator's Services and the Ingress that should stay disabled. | | `hpa`, `pdb`, `networkPolicy`, `resources`, `nodeSelector`, `tolerations`, `affinity` | Scheduling and availability. | | `otel` | An OTLP endpoint for the coordinator's own traces. | | `upgradeDrain` | The job that runs before an upgrade whose host agents cannot adopt the VMs running now: whether it runs and its time budget. It runs the coordinator image. See [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade/#when-a-release-changes-how-hosts-run-vms). | | `probes`, `drainSeconds`, `terminationGracePeriodSeconds` | Liveness on `/healthz`, readiness on `/readyz`, and how long a replica drains before it stops. | | `web` | The dashboard: image, Ingress, and the annotations that attach a managed certificate. | | `orchestrator` | The orchestrator: image, its Secret with the session-signing key, `auth` (see [Sign-in](#sign-in)), the public URL, and integration settings. | ## Upgrades The coordinator is stateless, so `helm upgrade` is a rolling restart of whichever Deployment's template changed. Sessions live on the hosts and are untouched by a control-plane roll; dashboard event streams reconnect with `Last-Event-ID`, and hosts re-register when the coordinator comes back. Roll the two charts together when you upgrade engrams: the coordinator and the host agents share a wire version and refuse to talk across a mismatch. When a release's host agents cannot adopt the VMs a host runs now, a job evicts every running session to a checkpoint before the upgrade changes anything. An image tag you leave empty falls back to the chart's `appVersion`, which is the release the checkout is. [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade/) is the procedure from one release to the next. --- # Helm chart: engram-host-fleet > The Firecracker host fleet as a DaemonSet, the operator that rolls and scales it, and the values behind them. Source: https://engramsfactory.com/docs/reference/helm-engram-host-fleet/ `deploy/helm/engram-host-fleet` runs the Firecracker hosts. It deploys the host agent as a privileged DaemonSet on the nodes labeled `engram.io/kvm=true`, a node-prep DaemonSet that readies each node, and an operator that rolls and scales the fleet. Install it in its own namespace with the `privileged` pod security level enforced, because the host agent needs the node's network, the node's PID namespace, `/dev/kvm`, and the cgroup tree. ## The pieces **node-prep** runs once per node before the host agent: it builds the session-disk pool (`thinPool`), sets `vm.unprivileged_userfaultfd` and `net.ipv4.ip_forward`, and mounts the tmpfs that holds each image's canonical memory. On a later boot it checks the pool's metadata and re-activates it; a node whose pool fails the check does not come up. **node-assets** is an init container on the host-agent pod. It stages Firecracker, the guest kernel, and the read-only session bundles (the in-guest daemon, the harnesses, the skills) into a shared directory, because stock Kubernetes nodes do not carry them. **The host agent** is the DaemonSet's main container. It dials the coordinator named in `coordinator.endpoint` with the bearer from `coordinator.tokenSecretName`, and runs the VMs. **The operator**, with `operator.enabled`, owns rollouts and scaling. The DaemonSet's update strategy is `OnDelete`, so Kubernetes never rolls these pods on its own: the operator drains a host, replaces its pod, and moves to the next, and a replaced pod reattaches to the VMs the old one left running. The same operator sizes the node pool from the coordinator's demand signal through a per-cloud scaler, `gke` or `asg`. With the operator off, roll the DaemonSet by hand and drain each host first. ## The values that matter | Section | What it sets | |---|---| | `image`, `imagePullSecrets`, `serviceAccount` | The host-agent image and its ServiceAccount, annotated for Workload Identity or IRSA. | | `nodeSelector`, `tolerations` | Pin the fleet to the KVM pool. The default selector is `engram.io/kvm: "true"`. | | `coordinator` | `endpoint`, the in-cluster coordinator Service, and the Secret that holds the bearer token. | | `blob` | The chunk store, matching the control-plane chart. | | `nodeAssets` | The image that carries Firecracker, the guest kernel, and the bundles. Pin it to a digest in production. | | `firecracker` | Restore modes, the canonical-memory tmpfs and its size, the density knobs, and `vmCgroupParent`, the node-level cgroup VMs move into so a pod restart does not kill them. | | `egress` | The proxy's ports and `caSource`, which is `env` on GKE and `aws-secrets-manager` on EKS. The [configuration reference](https://engramsfactory.com/docs/reference/configuration/) explains why. | | `storage` | The host's working directory on the node, the chunk cache budget, and any dedicated devices. The working directory must be a host path so it survives pod restarts. | | `thinPool` | The session-disk pool every host needs: its `name` and `dir`, `dataSize` (absolute, or a percentage of the filesystem that holds `dir`), `metadataSize`, `blockSizeSectors`, and `lowWaterMarkBlocks`. Every image and session volume on the node lives in it. | | `nodePrep` | The node-prep image and the sysctls it sets. | | `hostAgent` | Ports, resource requests and limits, and `extraEnv` for any `ENGRAM_*` variable not exposed as a value. | | `otel`, `metrics` | Traces and Prometheus metrics from the host agent. | | `updateStrategy` | `OnDelete`. Leave it. | | `operator` | Whether the operator runs, its image, its own ServiceAccount, and `scaler`: `noop`, `gke`, or `asg`. | | `upgradeDrain` | The jobs that run around an upgrade whose host agents cannot adopt the VMs running now: whether they run, the time budget, and the coordinator's RPC address (by default `operator.coordinatorUrl`, else the host of `coordinator.endpoint`). See [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade/#when-a-release-changes-how-hosts-run-vms). | ## The custom resource The chart installs a `HostFleet` custom resource definition and, by default, renders one `HostFleet` for its DaemonSet. The operator reads it for the fleet's desired size and rollout state, and the coordinator's demand signal updates it. Terraform seeds the node pool's size and then ignores it; the operator owns it from there. ## Per-cloud overlays `values-gcp.yaml.example` and `values-aws.yaml.example` carry the identity annotations, the CA source, and the scaler for each cloud, and the Terraform quickstarts render a second overlay with the bucket, endpoint, and Secret names. The bring-up guides show the install with both files. --- # Terraform: GCP > The composable modules and the one-apply quickstart for GKE. Source: https://engramsfactory.com/docs/reference/terraform-gcp/ `deploy/terraform/gcp` is the GCP deployment surface: composable modules plus a quickstart root that wires all of them. Use the quickstart for a fresh project, and compose the modules yourself when you bring your own cluster or database. The step-by-step bring-up, including the manual steps Terraform leaves to you on purpose, is [Deploy on GCP](https://engramsfactory.com/docs/guides/deploy-gcp/). ## What every cloud must provide engrams asks five things of a cloud. 1. **Postgres 14 or later** with `LISTEN/NOTIFY`: Cloud SQL, RDS, or your own. 2. **Object storage** for chunks: GCS, S3, or an S3-compatible store through the endpoint override. 3. **A secret store** for session secrets and the egress CA: Secret Manager or AWS Secrets Manager, or the environment-variable arms plus a relay that lands Kubernetes Secrets. 4. **Linux nodes with KVM** for the hosts. This is the binding constraint: nested virtualization is Intel-only on every managed provider, set when the pool is created, and the CPU platform is a one-way door for snapshots. 5. **Kubernetes** for the control plane and the host DaemonSet. A new cloud implements the contract by mirroring this layout: its own network and storage modules, a KVM node-pool module that honors the invariants above, a scaler for the autoscaling operator, and a quickstart that wires them. The Helm charts are already cloud-agnostic; only a values overlay is per-cloud. ## Layout ``` modules/ network/ VPC, subnet, Cloud NAT, firewall storage/ the GCS chunks bucket fc-host-gsa/ the hosts' Google service account (identity only) gke-cluster/ a regional cluster: Workload Identity, Managed Prometheus, VPC-native, plus the small control-plane pool gke-kvm-pool/ THE nested-virt host pool: Intel-only, operator-owned size, the CPU one-way door. Read its header before touching it. cloudsql/ Postgres 16 on a private IP, both databases, connection strings in Secret Manager secret-shells/ empty Secret Manager shells for the operator-populated secrets: master key, auth tokens, session signing, OAuth client secret, egress CA. Material never enters Terraform state. host-operator-iam/ the autoscaling operator's least-privilege role and account quickstart/ ONE apply from a fresh project to an engrams-ready cluster: all of the above plus namespaces, the External Secrets relay, identity bindings, the web static IP and managed certificate, and rendered Helm values as outputs examples/ minimal/ the bring-your-own-cluster shape: VPC, bucket, KMS, and identities only ``` ## Quickstart ```sh cd deploy/terraform/gcp/quickstart terraform init terraform apply \ -var project_id=my-project \ -var region=us-west2 \ -var domain=engrams.example.com \ -var admin_email=you@example.com ``` Pass `-var dns_zone_name=` to have the A record created in Cloud DNS. The outputs you use next are `secret_shell_ids` (the shells to populate), `web_static_ip` (the A record if you create it by hand), `cluster_name`, and the two rendered values overlays: ```sh terraform output -raw engram_values > engram.tfvalues.yaml terraform output -raw host_fleet_values > host-fleet.tfvalues.yaml ``` Mind the order: the External Secrets relay syncs only after the shells are populated, and a Helm release installed before that crash-loops on missing Secrets until the first sync. ## Bring your own cluster or database Compose the modules directly; each stands alone. `examples/minimal/` is the smallest useful set. Add `gke-kvm-pool` against your existing cluster and `cloudsql`, or any Postgres 14 or later, as needed. The published Google modules for GKE and Cloud SQL compose fine with these; the engrams modules carry the engrams-specific invariants, not a re-rolled cloud. `modules/network`, `modules/storage`, and `modules/fc-host-gsa` are consumed by git reference from other deployments, so their paths and variables are frozen. New modules are additive. --- # Terraform: AWS > The composable modules and the one-apply quickstart for EKS. Source: https://engramsfactory.com/docs/reference/terraform-aws/ `deploy/terraform/aws` is the AWS deployment surface, mirroring the [GCP one](https://engramsfactory.com/docs/reference/terraform-gcp/): composable modules plus a quickstart root. The step-by-step bring-up, including the cost and quota warnings, is [Deploy on AWS](https://engramsfactory.com/docs/guides/deploy-aws/). The cloud contract both implement is on the GCP page. ## Layout ``` modules/ network/ VPC, load-balancer-tagged subnets, one NAT, an S3 gateway endpoint so chunk traffic skips the NAT storage/ the S3 chunks bucket, with the abort-incomplete-multipart rule the streaming backend relies on eks-cluster/ a thin wrapper over the pinned terraform-aws-modules/eks: IRSA plus the small control-plane node group kvm-nodegroup/ THE KVM fleet: a self-managed launch template and auto-scaling group, Intel only, operator-owned size, zone rebalancing suspended. Read its header. rds/ Postgres 16 plus the two connection-string secrets secret-shells/ empty Secrets Manager shells, slash-namespaced. No master-key shell: the master key is a KMS key on AWS. irsa/ an IRSA role factory: OIDC trust plus the caller's policy host-operator-iam/ the auto-scaling-group scaler's least-privilege role, scoped to the fleet's group quickstart/ ONE apply: all of the above plus the master-key KMS key, namespaces, the AWS Load Balancer Controller, the External Secrets relay, the ACM certificate, a one-shot database-create Job, and rendered Helm values as outputs ``` ## Quickstart The default KVM shape is two `m8i.8xlarge` instances, 64 on-demand vCPUs, which a fresh account's quota may not cover. The metal alternative, `m7i.metal-24xl`, exists for CPU parity with a GCP C3 fleet and needs a metal quota ticket. Read the bring-up guide first. ```sh cd deploy/terraform/aws/quickstart terraform init cat > terraform.tfvars < engram.tfvalues.yaml terraform output -raw host_fleet_values > host-fleet.tfvalues.yaml ``` The one thing Terraform cannot print up front is the load balancer's hostname, which exists only after the web Ingress reconciles; the final CNAME comes from `kubectl get ingress`. Mind the order: the External Secrets relay syncs only after the shells are populated, and a Helm release installed before that crash-loops on missing Secrets until the first sync. ## Bring your own cluster or database Compose the modules directly; each stands alone. The KVM node group and the operator IAM carry the engrams-specific invariants. RDS can be any Postgres 14 or later you already run; the rds module documents the TLS mode split between the two databases that the connection strings depend on. --- # API reference > Every Connect RPC service, generated from the proto files. Source: https://engramsfactory.com/docs/api/ One page per service, generated at build time from the proto files in the repository. Every method is `POST /rpc/engram.app.v1./` with a JSON or protobuf body and an `x-api-key` header; the [API overview](https://engramsfactory.com/docs/reference/api/) covers authentication, the routes outside RPC, and client generation. | Service | Methods | |---|---| | [ApiKeyService](https://engramsfactory.com/docs/api/api-key/) | 6 | | [ArtifactService](https://engramsfactory.com/docs/api/artifact/) | 4 | | [AutomationRunService](https://engramsfactory.com/docs/api/automation-run/) | 8 | | [AutomationService](https://engramsfactory.com/docs/api/automation/) | 23 | | [FleetService](https://engramsfactory.com/docs/api/fleet/) | 15 | | [HarnessCatalogService](https://engramsfactory.com/docs/api/harness-catalog/) | 4 | | [ImageService](https://engramsfactory.com/docs/api/image/) | 11 | | [IntegrationOpService](https://engramsfactory.com/docs/api/integration-op/) | 2 | | [IntegrationService](https://engramsfactory.com/docs/api/integration/) | 15 | | [MintService](https://engramsfactory.com/docs/api/mint/) | 1 | | [ModelRouterService](https://engramsfactory.com/docs/api/model-router/) | 4 | | [MountCatalogService](https://engramsfactory.com/docs/api/mount-catalog/) | 4 | | [OAuthCredentialService](https://engramsfactory.com/docs/api/oauth-credential/) | 13 | | [OrgSecretService](https://engramsfactory.com/docs/api/org-secret/) | 3 | | [PapercutService](https://engramsfactory.com/docs/api/papercut/) | 3 | | [PortRelayService](https://engramsfactory.com/docs/api/port-relay/) | 1 | | [ProfileService](https://engramsfactory.com/docs/api/profile/) | 6 | | [PrRefService](https://engramsfactory.com/docs/api/pr-ref/) | 1 | | [RetentionService](https://engramsfactory.com/docs/api/retention/) | 2 | | [ReviewService](https://engramsfactory.com/docs/api/review/) | 3 | | [SessionService](https://engramsfactory.com/docs/api/session/) | 26 | | [ShellRelayService](https://engramsfactory.com/docs/api/shell-relay/) | 1 | | [TaskService](https://engramsfactory.com/docs/api/task/) | 5 | | [WebhookRegistrationService](https://engramsfactory.com/docs/api/webhook-registration/) | 4 | --- # ApiKeyService > The ApiKeyService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/api-key/ Generated from [`api_key.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/api_key.proto). Every method is `POST /rpc/engram.app.v1.ApiKeyService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `CreateApiKey` | [`CreateApiKeyRequest`](#createapikeyrequest) | [`CreateApiKeyResponse`](#createapikeyresponse) | | `ListApiKeys` | [`ListApiKeysRequest`](#listapikeysrequest) | [`ListApiKeysResponse`](#listapikeysresponse) | | `RevokeApiKey` | [`RevokeApiKeyRequest`](#revokeapikeyrequest) | [`RevokeApiKeyResponse`](#revokeapikeyresponse) | | `CreateCliKey` | [`CreateCliKeyRequest`](#createclikeyrequest) | [`CreateCliKeyResponse`](#createclikeyresponse) | | `RevokeCliKey` | [`RevokeCliKeyRequest`](#revokeclikeyrequest) | [`RevokeCliKeyResponse`](#revokeclikeyresponse) | | `WhoAmI` | [`WhoAmIRequest`](#whoamirequest) | [`WhoAmIResponse`](#whoamiresponse) | ## Messages ### ApiKeyMeta | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `role` | `string` | | `start` | `string` | | `created_at` | `string` | | `expires_at` | `string` | | `last_used_at` | `string` | | `owner_email` | `string` | ### CreateApiKeyRequest | Field | Type | |---|---| | `name` | `string` | | `role` | `string` | | `expires_at` | `string` | ### CreateApiKeyResponse | Field | Type | |---|---| | `meta` | [`ApiKeyMeta`](#apikeymeta) | | `key` | `string` | ### CreateCliKeyRequest | Field | Type | |---|---| | `name` | `string` | ### CreateCliKeyResponse | Field | Type | |---|---| | `meta` | [`ApiKeyMeta`](#apikeymeta) | | `key` | `string` | ### ListApiKeysRequest No fields. ### ListApiKeysResponse | Field | Type | |---|---| | `keys` | repeated [`ApiKeyMeta`](#apikeymeta) | ### RevokeApiKeyRequest | Field | Type | |---|---| | `id` | `string` | ### RevokeApiKeyResponse | Field | Type | |---|---| | `revoked` | `bool` | ### RevokeCliKeyRequest | Field | Type | |---|---| | `id` | `string` | ### RevokeCliKeyResponse | Field | Type | |---|---| | `revoked` | `bool` | ### WhoAmIRequest No fields. ### WhoAmIResponse | Field | Type | |---|---| | `user_id` | `string` | | `email` | `string` | | `name` | `string` | | `role` | `string` | | `service_account` | `bool` | --- # ArtifactService > The ArtifactService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/artifact/ Generated from [`artifact.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/artifact.proto). Every method is `POST /rpc/engram.app.v1.ArtifactService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListArtifacts` | [`ListArtifactsRequest`](#listartifactsrequest) | [`ListArtifactsResponse`](#listartifactsresponse) | | `GetArtifactRecord` | [`GetArtifactRecordRequest`](#getartifactrecordrequest) | [`GetArtifactRecordResponse`](#getartifactrecordresponse) | | `SetArtifactVisibility` | [`SetArtifactVisibilityRequest`](#setartifactvisibilityrequest) | [`SetArtifactVisibilityResponse`](#setartifactvisibilityresponse) | | `DeleteArtifact` | [`DeleteArtifactRequest`](#deleteartifactrequest) | [`DeleteArtifactResponse`](#deleteartifactresponse) | ## Messages ### ArtifactRecord | Field | Type | |---|---| | `id` | `string` | | `title` | `string` | | `file_name` | `string` | | `owner_user_id` | `string` (optional) | | `created_by` | `User` (optional) | | `visibility` | `string` | | `current_version` | `int32` | | `media_type` | `string` | | `size_bytes` | `uint64` | | `created_at` | `string` | | `updated_at` | `string` | | `raw_url` | `string` | | `versions` | repeated [`ArtifactVersionRecord`](#artifactversionrecord) | ### ArtifactVersionRecord | Field | Type | |---|---| | `version` | `int32` | | `session_id` | `string` | | `task_id` | `string` (optional) | | `media_type` | `string` | | `size_bytes` | `uint64` | | `created_at` | `string` | ### DeleteArtifactRequest | Field | Type | |---|---| | `id` | `string` | ### DeleteArtifactResponse | Field | Type | |---|---| | `deleted` | `bool` | ### GetArtifactRecordRequest | Field | Type | |---|---| | `id` | `string` | ### GetArtifactRecordResponse | Field | Type | |---|---| | `artifact` | [`ArtifactRecord`](#artifactrecord) | ### ListArtifactsRequest | Field | Type | |---|---| | `scope` | `string` | | `page` | `int32` | | `page_size` | `int32` | ### ListArtifactsResponse | Field | Type | |---|---| | `artifacts` | repeated [`ArtifactRecord`](#artifactrecord) | | `total_count` | `int32` | ### SetArtifactVisibilityRequest | Field | Type | |---|---| | `id` | `string` | | `visibility` | `string` | ### SetArtifactVisibilityResponse | Field | Type | |---|---| | `artifact` | [`ArtifactRecord`](#artifactrecord) | --- # AutomationRunService > The AutomationRunService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/automation-run/ Generated from [`automation.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/automation.proto). Every method is `POST /rpc/engram.app.v1.AutomationRunService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListRuns` | [`ListRunsRequest`](#listrunsrequest) | [`ListRunsResponse`](#listrunsresponse) | | `ListInstances` | [`ListInstancesRequest`](#listinstancesrequest) | [`ListInstancesResponse`](#listinstancesresponse) | | `GetInstance` | [`GetInstanceRequest`](#getinstancerequest) | [`GetInstanceResponse`](#getinstanceresponse) | | `CloseInstance` | [`CloseInstanceRequest`](#closeinstancerequest) | [`CloseInstanceResponse`](#closeinstanceresponse) | | `ListRecentDrops` | [`ListRecentDropsRequest`](#listrecentdropsrequest) | [`ListRecentDropsResponse`](#listrecentdropsresponse) | | `GetRun` | [`GetRunRequest`](#getrunrequest) | [`GetRunResponse`](#getrunresponse) | | `StopRun` | [`StopRunRequest`](#stoprunrequest) | [`StopRunResponse`](#stoprunresponse) | | `RetryRun` | [`RetryRunRequest`](#retryrunrequest) | [`RetryRunResponse`](#retryrunresponse) | ## Messages ### AutomationDropBrief | Field | Type | |---|---| | `entrypoint_id` | `string` | | `event_key` | `string` | | `reason` | `string` | | `detail` | `string` | | `dropped_at` | `string` | ### AutomationInstance | Field | Type | |---|---| | `id` | `string` | | `automation_id` | `string` | | `key` | `string` | | `status` | `string` | | `inputs_json` | `string` | | `opened_by` | `string` | | `opened_at` | `string` | | `closed_at` | `string` (optional) | | `close_reason` | `string` (optional) | | `label` | `string` (optional) | ### AutomationRun | Field | Type | |---|---| | `brief` | [`AutomationRunBrief`](#automationrunbrief) | | `trigger_json` | `string` | | `steps` | repeated [`AutomationStepRun`](#automationsteprun) | | `session_ids` | repeated `string` | ### AutomationRunBrief | Field | Type | |---|---| | `id` | `string` | | `automation_id` | `string` | | `version` | `int32` | | `status` | `string` | | `error` | `string` (optional) | | `trigger_source` | `string` | | `event_key` | `string` (optional) | | `delivery_key` | `string` (optional) | | `dry_run` | `bool` | | `started_at` | `string` (optional) | | `ended_at` | `string` (optional) | | `created_at` | `string` | | `instance_id` | `string` | | `entrypoint_id` | `string` | ### AutomationStepRun | Field | Type | |---|---| | `block_id` | `string` | | `attempt` | `int32` | | `status` | `string` | | `inputs_json` | `string` | | `outputs_json` | `string` | | `error` | `string` (optional) | | `session_id` | `string` (optional) | | `started_at` | `string` | | `ended_at` | `string` (optional) | ### CloseInstanceRequest | Field | Type | |---|---| | `id` | `string` | | `reason` | `string` (optional) | ### CloseInstanceResponse | Field | Type | |---|---| | `closed` | `bool` | ### FilteredWindow | Field | Type | |---|---| | `count` | `int32` | | `first_at` | `string` | | `last_at` | `string` | | `before_run_id` | `string` | ### GetInstanceRequest | Field | Type | |---|---| | `id` | `string` | ### GetInstanceResponse | Field | Type | |---|---| | `instance` | [`AutomationInstance`](#automationinstance) | | `handles` | repeated [`InstanceHandle`](#instancehandle) | ### GetRunRequest | Field | Type | |---|---| | `run_id` | `string` | ### GetRunResponse | Field | Type | |---|---| | `run` | [`AutomationRun`](#automationrun) | ### InstanceHandle | Field | Type | |---|---| | `handle` | `string` | | `written_by` | `string` | | `created_at` | `string` | ### ListInstancesRequest | Field | Type | |---|---| | `automation_id` | `string` | | `include_closed` | `bool` | | `limit` | `int32` | ### ListInstancesResponse | Field | Type | |---|---| | `instances` | repeated [`AutomationInstance`](#automationinstance) | ### ListRecentDropsRequest | Field | Type | |---|---| | `automation_id` | `string` | | `limit` | `int32` | ### ListRecentDropsResponse | Field | Type | |---|---| | `drops` | repeated [`AutomationDropBrief`](#automationdropbrief) | ### ListRunsRequest | Field | Type | |---|---| | `automation_id` | `string` | | `limit` | `int32` | | `include_filtered` | `bool` | | `instance_id` | `string` (optional) | ### ListRunsResponse | Field | Type | |---|---| | `runs` | repeated [`AutomationRunBrief`](#automationrunbrief) | | `filtered` | repeated [`FilteredWindow`](#filteredwindow) | ### RetryRunRequest | Field | Type | |---|---| | `run_id` | `string` | | `from_step_id` | `string` (optional) | ### RetryRunResponse | Field | Type | |---|---| | `run_id` | `string` | ### StopRunRequest | Field | Type | |---|---| | `run_id` | `string` | | `reason` | `string` (optional) | ### StopRunResponse | Field | Type | |---|---| | `sent` | `bool` | --- # AutomationService > The AutomationService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/automation/ Generated from [`automation.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/automation.proto). Every method is `POST /rpc/engram.app.v1.AutomationService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListAutomations` | [`ListAutomationsRequest`](#listautomationsrequest) | [`ListAutomationsResponse`](#listautomationsresponse) | | `GetAutomation` | [`GetAutomationRequest`](#getautomationrequest) | [`GetAutomationResponse`](#getautomationresponse) | | `CreateAutomation` | [`CreateAutomationRequest`](#createautomationrequest) | [`CreateAutomationResponse`](#createautomationresponse) | | `DraftAutomation` | [`DraftAutomationRequest`](#draftautomationrequest) | [`DraftAutomationResponse`](#draftautomationresponse) | | `SaveVersion` | [`SaveVersionRequest`](#saveversionrequest) | [`SaveVersionResponse`](#saveversionresponse) | | `ListVersions` | [`ListVersionsRequest`](#listversionsrequest) | [`ListVersionsResponse`](#listversionsresponse) | | `SetAutomationEnabled` | [`SetAutomationEnabledRequest`](#setautomationenabledrequest) | [`SetAutomationEnabledResponse`](#setautomationenabledresponse) | | `UpdateAutomationMeta` | [`UpdateAutomationMetaRequest`](#updateautomationmetarequest) | [`UpdateAutomationMetaResponse`](#updateautomationmetaresponse) | | `SetInputs` | [`SetInputsRequest`](#setinputsrequest) | [`SetInputsResponse`](#setinputsresponse) | | `SetMapInputEntry` | [`SetMapInputEntryRequest`](#setmapinputentryrequest) | [`SetMapInputEntryResponse`](#setmapinputentryresponse) | | `SetInputValue` | [`SetInputValueRequest`](#setinputvaluerequest) | [`SetInputValueResponse`](#setinputvalueresponse) | | `SetBlockOverrides` | [`SetBlockOverridesRequest`](#setblockoverridesrequest) | [`SetBlockOverridesResponse`](#setblockoverridesresponse) | | `DuplicateAutomation` | [`DuplicateAutomationRequest`](#duplicateautomationrequest) | [`DuplicateAutomationResponse`](#duplicateautomationresponse) | | `ArchiveAutomation` | [`ArchiveAutomationRequest`](#archiveautomationrequest) | [`ArchiveAutomationResponse`](#archiveautomationresponse) | | `TestRender` | [`TestRenderRequest`](#testrenderrequest) | [`TestRenderResponse`](#testrenderresponse) | | `DryRun` | [`DryRunRequest`](#dryrunrequest) | [`DryRunResponse`](#dryrunresponse) | | `EvalCode` | [`EvalCodeRequest`](#evalcoderequest) | [`EvalCodeResponse`](#evalcoderesponse) | | `RunNow` | [`RunNowRequest`](#runnowrequest) | [`RunNowResponse`](#runnowresponse) | | `ListEventSamples` | [`ListEventSamplesRequest`](#listeventsamplesrequest) | [`ListEventSamplesResponse`](#listeventsamplesresponse) | | `ListInputKeyOptions` | [`ListInputKeyOptionsRequest`](#listinputkeyoptionsrequest) | [`ListInputKeyOptionsResponse`](#listinputkeyoptionsresponse) | | `DescribeInputKeys` | [`DescribeInputKeysRequest`](#describeinputkeysrequest) | [`DescribeInputKeysResponse`](#describeinputkeysresponse) | | `ListEventCatalog` | [`ListEventCatalogRequest`](#listeventcatalogrequest) | [`ListEventCatalogResponse`](#listeventcatalogresponse) | | `ListActionCatalog` | [`ListActionCatalogRequest`](#listactioncatalogrequest) | [`ListActionCatalogResponse`](#listactioncatalogresponse) | ## Messages ### ActionCatalogEntry | Field | Type | |---|---| | `id` | `string` | | `label` | `string` | | `description` | `string` | | `input_schema_json` | `string` | ### ArchiveAutomationRequest | Field | Type | |---|---| | `id` | `string` | ### ArchiveAutomationResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### Automation | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `description` | `string` | | `kind` | `string` | | `builtin_key` | `string` (optional) | | `enabled` | `bool` | | `current_version` | `int32` | | `inputs_json` | `string` | | `block_overrides_json` | `string` | | `archived` | `bool` | | `created_by_user_id` | `string` (optional) | | `next_fire_at` | `string` (optional) | | `last_fired_at` | `string` (optional) | | `draft_session_id` | `string` (optional) | | `created_at` | `string` | | `updated_at` | `string` | | `version` | [`AutomationVersion`](#automationversion) | ### AutomationRunBrief | Field | Type | |---|---| | `id` | `string` | | `automation_id` | `string` | | `version` | `int32` | | `status` | `string` | | `error` | `string` (optional) | | `trigger_source` | `string` | | `event_key` | `string` (optional) | | `delivery_key` | `string` (optional) | | `dry_run` | `bool` | | `started_at` | `string` (optional) | | `ended_at` | `string` (optional) | | `created_at` | `string` | | `instance_id` | `string` | | `entrypoint_id` | `string` | ### AutomationSummary | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | | `trigger_summary` | `string` | | `last_run` | [`AutomationRunBrief`](#automationrunbrief) (optional) | | `runs_7d` | repeated [`DayRunCount`](#dayruncount) | ### AutomationVersion | Field | Type | |---|---| | `automation_id` | `string` | | `number` | `int32` | | `definition_json` | `string` | | `created_by_user_id` | `string` (optional) | | `created_at` | `string` | ### BlockError | Field | Type | |---|---| | `block_id` | `string` | | `field` | `string` | | `code` | `string` | | `message` | `string` | ### BlockRender | Field | Type | |---|---| | `block_id` | `string` | | `block_type` | `string` | | `rendered_json` | `string` | | `filter_pass` | `bool` (optional) | | `scope_json` | `string` | ### CreateAutomationRequest | Field | Type | |---|---| | `name` | `string` | | `description` | `string` | | `enabled` | `bool` | | `definition_json` | `string` | | `inputs_json` | `string` | ### CreateAutomationResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### DayRunCount | Field | Type | |---|---| | `day` | `string` | | `completed` | `int32` | | `failed` | `int32` | | `filtered` | `int32` | | `other` | `int32` | ### DescribeInputKeysRequest | Field | Type | |---|---| | `noun` | `string` | | `keys` | repeated `string` | | `connection_id` | `string` (optional) | ### DescribeInputKeysResponse | Field | Type | |---|---| | `options` | repeated [`InputKeyOption`](#inputkeyoption) | ### DraftAutomationRequest | Field | Type | |---|---| | `prompt` | `string` | | `profile_id` | `string` | | `idempotency_key` | `string` | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `model_router` | `string` (optional) | | `effort` | `string` (optional) | | `harness_mode` | `string` (optional) | ### DraftAutomationResponse | Field | Type | |---|---| | `automation_id` | `string` | | `session_id` | `string` | | `created` | `bool` | ### DryRunRequest | Field | Type | |---|---| | `automation_id` | `string` | | `sample_id` | `string` (one of sample) | | `payload_json` | `string` (one of sample) | | `entrypoint_id` | `string` (optional) | ### DryRunResponse | Field | Type | |---|---| | `run_id` | `string` | ### DuplicateAutomationRequest | Field | Type | |---|---| | `automation_id` | `string` | | `name` | `string` (optional) | ### DuplicateAutomationResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### EvalCodeRequest | Field | Type | |---|---| | `source` | `string` | | `mode` | `string` | | `input_json` | `string` | ### EvalCodeResponse | Field | Type | |---|---| | `value_json` | `string` (optional) | | `error_name` | `string` (optional) | | `error_message` | `string` (optional) | | `error_line` | `int32` (optional) | | `logs` | repeated `string` | | `duration_ms` | `int64` | ### EventCatalogEntry | Field | Type | |---|---| | `key` | `string` | | `label` | `string` | | `description` | `string` | | `schema_json` | `string` | | `sample_json` | `string` | | `observed` | `bool` | | `hidden` | `bool` | ### EventCatalogScope | Field | Type | |---|---| | `key` | `string` | | `label` | `string` | ### EventSample | Field | Type | |---|---| | `id` | `string` | | `event_key` | `string` | | `payload_json` | `string` | | `received_at` | `string` | ### GetAutomationRequest | Field | Type | |---|---| | `id` | `string` (one of lookup) | | `builtin_key` | `string` (one of lookup) | ### GetAutomationResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### InputKeyOption | Field | Type | |---|---| | `key` | `string` | | `label` | `string` | ### ListActionCatalogRequest | Field | Type | |---|---| | `provider` | `string` | ### ListActionCatalogResponse | Field | Type | |---|---| | `actions` | repeated [`ActionCatalogEntry`](#actioncatalogentry) | ### ListAutomationsRequest | Field | Type | |---|---| | `include_archived` | `bool` | ### ListAutomationsResponse | Field | Type | |---|---| | `automations` | repeated [`AutomationSummary`](#automationsummary) | ### ListEventCatalogRequest | Field | Type | |---|---| | `provider` | `string` | ### ListEventCatalogResponse | Field | Type | |---|---| | `events` | repeated [`EventCatalogEntry`](#eventcatalogentry) | | `scope` | [`EventCatalogScope`](#eventcatalogscope) (optional) | | `variables` | repeated [`WebhookVariable`](#webhookvariable) | | `default_connection_id` | `string` | ### ListEventSamplesRequest | Field | Type | |---|---| | `automation_id` | `string` | | `event_key` | `string` (optional) | | `limit` | `int32` | ### ListEventSamplesResponse | Field | Type | |---|---| | `samples` | repeated [`EventSample`](#eventsample) | ### ListInputKeyOptionsRequest | Field | Type | |---|---| | `noun` | `string` | | `connection_id` | `string` (optional) | ### ListInputKeyOptionsResponse | Field | Type | |---|---| | `options` | repeated [`InputKeyOption`](#inputkeyoption) | ### ListVersionsRequest | Field | Type | |---|---| | `automation_id` | `string` | ### ListVersionsResponse | Field | Type | |---|---| | `versions` | repeated [`AutomationVersion`](#automationversion) | ### RunNowRequest | Field | Type | |---|---| | `automation_id` | `string` | | `inputs_json` | `string` (optional) | | `payload_json` | `string` (optional) | | `entrypoint_id` | `string` (optional) | | `instance_key` | `string` (optional) | | `instance_inputs_json` | `string` (optional) | ### RunNowResponse | Field | Type | |---|---| | `run_id` | `string` | ### SaveVersionRequest | Field | Type | |---|---| | `automation_id` | `string` | | `definition_json` | `string` | ### SaveVersionResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### SetAutomationEnabledRequest | Field | Type | |---|---| | `id` | `string` | | `enabled` | `bool` | ### SetAutomationEnabledResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### SetBlockOverridesRequest | Field | Type | |---|---| | `automation_id` | `string` | | `overrides_json` | `string` | ### SetBlockOverridesResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### SetInputsRequest | Field | Type | |---|---| | `automation_id` | `string` | | `inputs_json` | `string` | ### SetInputsResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### SetInputValueRequest | Field | Type | |---|---| | `automation_id` | `string` | | `input_key` | `string` | | `value_json` | `string` | ### SetInputValueResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### SetMapInputEntryRequest | Field | Type | |---|---| | `automation_id` | `string` | | `input_key` | `string` | | `entry_key` | `string` | | `value_json` | `string` (optional) | | `enable` | `bool` | ### SetMapInputEntryResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### TestRenderRequest | Field | Type | |---|---| | `automation_id` | `string` | | `draft_definition_json` | `string` (optional) | | `inputs_json` | `string` (optional) | | `sample_id` | `string` (one of sample) | | `payload_json` | `string` (one of sample) | | `scheduled_for` | `string` (optional) | | `entrypoint_id` | `string` (optional) | ### TestRenderResponse | Field | Type | |---|---| | `blocks` | repeated [`BlockRender`](#blockrender) | | `errors` | repeated [`BlockError`](#blockerror) | ### UpdateAutomationMetaRequest | Field | Type | |---|---| | `id` | `string` | | `name` | `string` (optional) | | `description` | `string` (optional) | | `settings_json` | `string` (optional) | ### UpdateAutomationMetaResponse | Field | Type | |---|---| | `automation` | [`Automation`](#automation) | ### WebhookVariable | Field | Type | |---|---| | `path` | `string` | | `alias` | `string` | --- # FleetService > The FleetService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/fleet/ Generated from [`fleet.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/fleet.proto). Every method is `POST /rpc/engram.app.v1.FleetService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListHosts` | [`ListHostsRequest`](#listhostsrequest) | [`ListHostsResponse`](#listhostsresponse) | | `GetHost` | [`GetHostRequest`](#gethostrequest) | [`GetHostResponse`](#gethostresponse) | | `RetireHost` | [`RetireHostRequest`](#retirehostrequest) | [`RetireHostResponse`](#retirehostresponse) | | `DrainHost` | [`DrainHostRequest`](#drainhostrequest) | [`DrainHostResponse`](#drainhostresponse) | | `AdminDrainHost` | [`AdminDrainHostRequest`](#admindrainhostrequest) | [`AdminDrainHostResponse`](#admindrainhostresponse) | | `CordonHost` | [`CordonHostRequest`](#cordonhostrequest) | [`CordonHostResponse`](#cordonhostresponse) | | `BeginHostHandoff` | [`BeginHostHandoffRequest`](#beginhosthandoffrequest) | [`BeginHostHandoffResponse`](#beginhosthandoffresponse) | | `UncordonHost` | [`UncordonHostRequest`](#uncordonhostrequest) | [`UncordonHostResponse`](#uncordonhostresponse) | | `DeleteHost` | [`DeleteHostRequest`](#deletehostrequest) | [`DeleteHostResponse`](#deletehostresponse) | | `GetStorageSummary` | [`GetStorageSummaryRequest`](#getstoragesummaryrequest) | [`GetStorageSummaryResponse`](#getstoragesummaryresponse) | | `TeleportSession` | [`TeleportSessionRequest`](#teleportsessionrequest) | [`TeleportSessionResponse`](#teleportsessionresponse) | | `ChunkGc` | [`ChunkGcRequest`](#chunkgcrequest) | [`ChunkGcResponse`](#chunkgcresponse) | | `BundleGc` | [`BundleGcRequest`](#bundlegcrequest) | [`BundleGcResponse`](#bundlegcresponse) | | `SnapshotBlobGc` | [`SnapshotBlobGcRequest`](#snapshotblobgcrequest) | [`SnapshotBlobGcResponse`](#snapshotblobgcresponse) | | `GetFleetDemand` | [`GetFleetDemandRequest`](#getfleetdemandrequest) | [`GetFleetDemandResponse`](#getfleetdemandresponse) | ## Messages ### AdminDrainHostRequest | Field | Type | |---|---| | `host_id` | `string` | ### AdminDrainHostResponse | Field | Type | |---|---| | `host_id` | `string` | | `planned` | repeated `string` | | `descended` | repeated `string` | | `skipped` | `uint32` | ### BeginHostHandoffRequest | Field | Type | |---|---| | `host_id` | `string` | | `ttl_secs` | `uint64` | ### BeginHostHandoffResponse | Field | Type | |---|---| | `host_id` | `string` | | `accepted` | `bool` | ### BundleGcRequest | Field | Type | |---|---| | `dry_run` | `bool` | | `grace_secs` | `uint64` (optional) | ### BundleGcResponse | Field | Type | |---|---| | `listed` | `uint64` | | `pin_set_size` | `uint64` | | `candidates_marked` | `uint64` | | `promoted_deletes` | `uint64` | | `promote_delete_errors` | `uint64` | | `restart_count` | `uint32` | | `promote_repinned_skips` | `uint64` | ### ChunkGcRequest | Field | Type | |---|---| | `dry_run` | `bool` | | `grace_secs` | `uint64` (optional) | ### ChunkGcResponse | Field | Type | |---|---| | `listed_chunks` | `uint64` | | `malformed_keys` | `uint64` | | `pin_set_size` | `uint64` | | `candidates_marked` | `uint64` | | `promoted_deletes` | `uint64` | | `promote_delete_errors` | `uint64` | | `grace_secs` | `uint64` | | `generation_moved` | `bool` | | `mark_error` | `string` (optional) | ### CordonHostRequest | Field | Type | |---|---| | `host_id` | `string` | | `owner` | `string` | ### CordonHostResponse | Field | Type | |---|---| | `host_id` | `string` | | `status` | `string` | ### DeleteHostRequest | Field | Type | |---|---| | `host_id` | `string` | ### DeleteHostResponse No fields. ### DrainHostRequest | Field | Type | |---|---| | `host_id` | `string` | ### DrainHostResponse No fields. ### GetFleetDemandRequest No fields. ### GetFleetDemandResponse | Field | Type | |---|---| | `ready_hosts` | `uint32` | | `schedulable_hosts` | `uint32` | | `free_mib` | `uint64` | | `total_mib` | `uint64` | | `free_vcpus` | `uint64` | | `total_vcpus` | `uint64` | | `cordoned_hosts` | `uint32` | | `queued_sessions` | `uint64` | | `queued_mib` | `uint64` | | `queued_vcpus` | `uint64` | ### GetHostRequest | Field | Type | |---|---| | `host_id` | `string` | ### GetHostResponse | Field | Type | |---|---| | `host` | [`HostView`](#hostview) | ### GetStorageSummaryRequest No fields. ### GetStorageSummaryResponse | Field | Type | |---|---| | `snapshots` | `uint64` | | `snapshot_bytes` | `uint64` | | `gc_pending` | `uint64` | | `gc_pending_exact` | `bool` | ### HostRetirement | Field | Type | |---|---| | `requested_at` | `string` | | `retired_at` | `string` | | `blockers` | repeated [`RetirementBlocker`](#retirementblocker) | ### HostView | Field | Type | |---|---| | `id` | `string` | | `hostname` | `string` | | `status` | `string` | | `capacity_total_mib` | `uint64` | | `capacity_used_mib` | `uint64` | | `running_sandboxes` | `uint32` | | `ready_images` | `uint64` | | `ready_image_digests` | repeated `string` | | `util_disk_total_mib` | `uint64` | | `util_disk_used_mib` | `uint64` | | `util_mem_total_mib` | `uint64` | | `util_mem_used_mib` | `uint64` | | `util_cpu_pct` | `float` | | `last_heartbeat_at` | `string` | | `cordoned` | `bool` | | `allocatable_mib` | `uint64` | | `reserved_mib` | `uint64` | | `free_mib` | `uint64` | | `total_vcpus` | `uint32` | | `cpu_budget_vcpus` | `uint64` | | `reserved_vcpus` | `uint64` | | `free_vcpus` | `uint64` | | `util_base_shm_mib` | `uint64` | | `util_parked_pss_mib` | `uint64` | | `util_running_pss_mib` | `uint64` | | `failing_capabilities` | repeated `string` | | `fc_snapshot_version` | `string` | | `capabilities_schema` | `uint32` | | `live_materializes` | `uint32` | | `live_capture_jobs` | `uint32` | | `cordon_owner` | `string` | | `retirement` | [`HostRetirement`](#hostretirement) | | `pool_data_free_mib` | `uint64` | | `pool_data_total_mib` | `uint64` | | `pool_metadata_free_mib` | `uint64` | | `pool_metadata_total_mib` | `uint64` | | `reattach_generation` | `uint32` | ### ListHostsRequest No fields. ### ListHostsResponse | Field | Type | |---|---| | `hosts` | repeated [`HostView`](#hostview) | ### RetireHostRequest | Field | Type | |---|---| | `host_id` | `string` | | `owner` | `string` | | `reason` | `string` | ### RetireHostResponse | Field | Type | |---|---| | `host_id` | `string` | | `retirement` | [`HostRetirement`](#hostretirement) | | `teleports_planned` | `uint32` | ### RetirementBlocker | Field | Type | |---|---| | `kind` | `string` | | `count` | `uint64` | ### SnapshotBlobGcRequest | Field | Type | |---|---| | `dry_run` | `bool` | | `grace_secs` | `uint64` (optional) | ### SnapshotBlobGcResponse | Field | Type | |---|---| | `listed` | `uint64` | | `malformed` | `uint64` | | `pin_set_size` | `uint64` | | `candidates_marked` | `uint64` | | `promoted_deletes` | `uint64` | | `promote_repinned_skips` | `uint64` | | `promote_delete_errors` | `uint64` | | `restart_count` | `uint32` | ### TeleportSessionRequest | Field | Type | |---|---| | `session_id` | `string` | | `target_host` | `string` (optional) | ### TeleportSessionResponse | Field | Type | |---|---| | `teleport_id` | `string` | | `kind` | `string` | | `dest_host_id` | `string` | ### UncordonHostRequest | Field | Type | |---|---| | `host_id` | `string` | | `owner` | `string` | ### UncordonHostResponse | Field | Type | |---|---| | `host_id` | `string` | | `status` | `string` | --- # HarnessCatalogService > The HarnessCatalogService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/harness-catalog/ Generated from [`harness.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/harness.proto). Every method is `POST /rpc/engram.app.v1.HarnessCatalogService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `RegisterHarness` | [`RegisterHarnessRequest`](#registerharnessrequest) | [`RegisterHarnessResponse`](#registerharnessresponse) | | `ListHarnesses` | [`ListHarnessesRequest`](#listharnessesrequest) | [`ListHarnessesResponse`](#listharnessesresponse) | | `GetHarness` | [`GetHarnessRequest`](#getharnessrequest) | [`GetHarnessResponse`](#getharnessresponse) | | `DeleteHarness` | [`DeleteHarnessRequest`](#deleteharnessrequest) | [`DeleteHarnessResponse`](#deleteharnessresponse) | ## Messages ### DeleteHarnessRequest | Field | Type | |---|---| | `name` | `string` | ### DeleteHarnessResponse | Field | Type | |---|---| | `deleted` | `bool` | ### GetHarnessRequest | Field | Type | |---|---| | `name` | `string` | ### GetHarnessResponse | Field | Type | |---|---| | `harness` | [`HarnessSummary`](#harnesssummary) | ### HarnessAuth | Field | Type | |---|---| | `org_env` | `string` (optional) | | `user_env` | `string` (optional) | | `org_env_hint` | `string` (optional) | | `user_env_hint` | `string` (optional) | | `user_oauth` | [`HarnessOAuth`](#harnessoauth) | ### HarnessDescriptor | Field | Type | |---|---| | `name` | `string` | | `label` | `string` (optional) | | `auth` | [`HarnessAuth`](#harnessauth) | | `models` | repeated [`HarnessOption`](#harnessoption) | | `effort` | repeated [`HarnessOption`](#harnessoption) | | `description` | `string` (optional) | | `egress` | [`HarnessEgress`](#harnessegress) | | `modes` | repeated [`HarnessMode`](#harnessmode) | | `router_protocols` | repeated `string` | | `native_egress` | [`HarnessEgress`](#harnessegress) | ### HarnessEgress | Field | Type | |---|---| | `allow_hosts` | repeated `string` | | `allow_host_patterns` | repeated `string` | ### HarnessMode | Field | Type | |---|---| | `id` | `string` | | `label` | `string` (optional) | | `default` | `bool` | ### HarnessOAuth | Field | Type | |---|---| | `provider` | `string` | | `delivery` | [`OauthDelivery`](#oauthdelivery) | ### HarnessOption | Field | Type | |---|---| | `id` | `string` | | `label` | `string` (optional) | | `default` | `bool` | | `env` | `map` | ### HarnessSummary | Field | Type | |---|---| | `name` | `string` | | `descriptor` | [`HarnessDescriptor`](#harnessdescriptor) | | `built_in` | `bool` | ### ListHarnessesRequest No fields. ### ListHarnessesResponse | Field | Type | |---|---| | `harnesses` | repeated [`HarnessSummary`](#harnesssummary) | ### RegisterHarnessRequest | Field | Type | |---|---| | `name` | `string` | | `oci_ref` | `string` | | `owner` | `string` | ### RegisterHarnessResponse | Field | Type | |---|---| | `harness` | [`HarnessSummary`](#harnesssummary) | ## Enums ### OauthDelivery | Value | Number | |---|---| | `OAUTH_DELIVERY_UNSPECIFIED` | 0 | | `OAUTH_DELIVERY_OPAQUE_BUNDLE` | 1 | --- # ImageService > The ImageService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/image/ Generated from [`image.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/image.proto). Every method is `POST /rpc/engram.app.v1.ImageService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListEnabledImages` | [`ListEnabledImagesRequest`](#listenabledimagesrequest) | [`ListEnabledImagesResponse`](#listenabledimagesresponse) | | `EnableImage` | [`EnableImageRequest`](#enableimagerequest) | [`EnableImageResponse`](#enableimageresponse) | | `UpdateImage` | [`UpdateImageRequest`](#updateimagerequest) | [`UpdateImageResponse`](#updateimageresponse) | | `DisableImage` | [`DisableImageRequest`](#disableimagerequest) | [`DisableImageResponse`](#disableimageresponse) | | `RefreshImage` | [`RefreshImageRequest`](#refreshimagerequest) | [`RefreshImageResponse`](#refreshimageresponse) | | `ListEnableJobs` | [`ListEnableJobsRequest`](#listenablejobsrequest) | [`ListEnableJobsResponse`](#listenablejobsresponse) | | `GetEnableJob` | [`GetEnableJobRequest`](#getenablejobrequest) | [`GetEnableJobResponse`](#getenablejobresponse) | | `RetryEnableJob` | [`RetryEnableJobRequest`](#retryenablejobrequest) | [`RetryEnableJobResponse`](#retryenablejobresponse) | | `ListRegistries` | [`ListRegistriesRequest`](#listregistriesrequest) | [`ListRegistriesResponse`](#listregistriesresponse) | | `AddRegistry` | [`AddRegistryRequest`](#addregistryrequest) | [`AddRegistryResponse`](#addregistryresponse) | | `DeleteRegistry` | [`DeleteRegistryRequest`](#deleteregistryrequest) | [`DeleteRegistryResponse`](#deleteregistryresponse) | ## Messages ### AddRegistryRequest | Field | Type | |---|---| | `host` | `string` | | `static` | [`StaticRegistryAuth`](#staticregistryauth) (one of auth) | | `gcp_workload_identity` | [`GcpWorkloadIdentityRegistryAuth`](#gcpworkloadidentityregistryauth) (one of auth) | | `anonymous` | [`AnonymousRegistryAuth`](#anonymousregistryauth) (one of auth) | | `aws_ecr` | [`AwsEcrRegistryAuth`](#awsecrregistryauth) (one of auth) | ### AddRegistryResponse | Field | Type | |---|---| | `id` | `string` | | `host` | `string` | | `auth_kind` | `string` | | `auth_principal` | `string` (optional) | ### AnonymousRegistryAuth No fields. ### AwsEcrRegistryAuth | Field | Type | |---|---| | `assume_role_arn` | `string` (optional) | ### CaptureEnvEntry | Field | Type | |---|---| | `name` | `string` | | `literal` | `string` (one of value) | | `secret_ref` | `string` (one of value) | ### DeleteRegistryRequest | Field | Type | |---|---| | `host` | `string` | ### DeleteRegistryResponse No fields. ### DisableImageRequest | Field | Type | |---|---| | `image_uri` | `string` | ### DisableImageResponse No fields. ### EnabledImageSummary | Field | Type | |---|---| | `id` | `string` | | `image_uri` | `string` | | `manifest_digest` | `string` | | `last_refreshed_at` | `string` | | `created_at` | `string` | | `config` | [`ImageConfig`](#imageconfig) | ### EnableImageRequest | Field | Type | |---|---| | `image_uri` | `string` | | `config` | [`ImageConfig`](#imageconfig) (optional) | ### EnableImageResponse | Field | Type | |---|---| | `job` | [`EnableJob`](#enablejob) | ### EnableJob | Field | Type | |---|---| | `id` | `string` | | `image_uri` | `string` | | `manifest_digest` | `string` (optional) | | `state` | `string` | | `chunks_total` | `uint32` (optional) | | `chunks_done` | `uint32` | | `attempts` | `uint32` | | `error` | `string` (optional) | | `created_at` | `string` | | `updated_at` | `string` | | `capture_phase` | `string` (optional) | | `warm_stage` | `string` (optional) | | `warm_stage_started_at` | `string` (optional) | | `output_tail` | `string` (optional) | | `prestage_hosts` | `string` | | `warm_stages` | `string` | | `materialize_stages` | `string` | | `materialize_host_id` | `string` (optional) | ### GcpWorkloadIdentityRegistryAuth | Field | Type | |---|---| | `impersonate_sa` | `string` (optional) | ### GetEnableJobRequest | Field | Type | |---|---| | `job_id` | `string` | ### GetEnableJobResponse | Field | Type | |---|---| | `job` | [`EnableJob`](#enablejob) | ### ImageConfig | Field | Type | |---|---| | `name` | `string` | | `description` | `string` (optional) | | `env` | `map` | | `workdir` | `string` (optional) | | `resources` | [`ImageResources`](#imageresources) | | `warm` | [`ImageWarmConfig`](#imagewarmconfig) (optional) | ### ImageResources | Field | Type | |---|---| | `suggested_memory_mib` | `uint32` (optional) | | `suggested_vcpus` | `uint32` (optional) | | `suggested_disk_gib` | `uint32` (optional) | | `suggested_swap_mib` | `uint32` (optional) | ### ImageWarmConfig | Field | Type | |---|---| | `command` | repeated `string` | | `timeout_secs` | `uint64` (optional) | | `workdir` | `string` (optional) | | `env` | repeated [`CaptureEnvEntry`](#captureenventry) | | `network` | `ProfileNetwork` (optional) | ### ListEnabledImagesRequest No fields. ### ListEnabledImagesResponse | Field | Type | |---|---| | `images` | repeated [`EnabledImageSummary`](#enabledimagesummary) | ### ListEnableJobsRequest No fields. ### ListEnableJobsResponse | Field | Type | |---|---| | `jobs` | repeated [`EnableJob`](#enablejob) | ### ListRegistriesRequest No fields. ### ListRegistriesResponse | Field | Type | |---|---| | `registries` | repeated [`RegistryCredentialSummary`](#registrycredentialsummary) | ### RefreshImageRequest | Field | Type | |---|---| | `image_uri` | `string` | | `force_recapture` | `bool` | ### RefreshImageResponse | Field | Type | |---|---| | `job` | [`EnableJob`](#enablejob) | ### RegistryCredentialSummary | Field | Type | |---|---| | `id` | `string` | | `registry_host` | `string` | | `auth_kind` | `string` | | `auth_principal` | `string` (optional) | | `created_at` | `string` | | `updated_at` | `string` (optional) | ### RetryEnableJobRequest | Field | Type | |---|---| | `job_id` | `string` | ### RetryEnableJobResponse | Field | Type | |---|---| | `job` | [`EnableJob`](#enablejob) | ### StaticRegistryAuth | Field | Type | |---|---| | `username` | `string` | | `password` | `string` | ### UpdateImageRequest | Field | Type | |---|---| | `image_uri` | `string` | | `config` | [`ImageConfig`](#imageconfig) | | `allow_recapture` | `bool` | ### UpdateImageResponse | Field | Type | |---|---| | `job` | [`EnableJob`](#enablejob) (optional) | --- # IntegrationOpService > The IntegrationOpService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/integration-op/ Generated from [`integration_op.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/integration_op.proto). Every method is `POST /rpc/engram.app.v1.IntegrationOpService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `RunIntegrationOp` | [`RunIntegrationOpRequest`](#runintegrationoprequest) | [`RunIntegrationOpResponse`](#runintegrationopresponse) | | `ResolveIntegrationCredential` | [`ResolveIntegrationCredentialRequest`](#resolveintegrationcredentialrequest) | [`ResolveIntegrationCredentialResponse`](#resolveintegrationcredentialresponse) | ## Messages ### AwsStsCred | Field | Type | |---|---| | `access_key_id` | `string` | | `secret_access_key` | `string` | | `session_token` | `string` | ### BasicCred | Field | Type | |---|---| | `username` | `string` | | `password` | `string` | ### BearerCred | Field | Type | |---|---| | `token` | `string` | ### CredentialSpec | Field | Type | |---|---| | `source` | `string` | | `injects` | repeated [`OpInject`](#opinject) | | `mint_provider` | `string` | | `oauth_connection_id` | `string` | | `mint_kind` | `string` | | `mint_draft_fields` | `map` | ### HeadersCred | Field | Type | |---|---| | `values` | `map` | ### OpInject | Field | Type | |---|---| | `header` | `string` | | `template` | `string` | | `secret_ref` | `string` | | `draft_secret` | `string` | ### ResolvedCredential | Field | Type | |---|---| | `bearer` | [`BearerCred`](#bearercred) (one of cred) | | `basic` | [`BasicCred`](#basiccred) (one of cred) | | `headers` | [`HeadersCred`](#headerscred) (one of cred) | | `aws_sts` | [`AwsStsCred`](#awsstscred) (one of cred) | | `expires_at` | `string` | ### ResolveIntegrationCredentialRequest | Field | Type | |---|---| | `provider` | `string` | | `credential` | [`CredentialSpec`](#credentialspec) | ### ResolveIntegrationCredentialResponse | Field | Type | |---|---| | `credential` | [`ResolvedCredential`](#resolvedcredential) | ### RunIntegrationOpRequest | Field | Type | |---|---| | `provider` | `string` | | `host` | `string` | | `method` | `string` | | `path` | `string` | | `body` | `bytes` | | `content_type` | `string` | | `credential` | [`CredentialSpec`](#credentialspec) | ### RunIntegrationOpResponse | Field | Type | |---|---| | `status` | `uint32` | | `body` | `bytes` | | `content_type` | `string` | | `truncated` | `bool` | --- # IntegrationService > The IntegrationService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/integration/ Generated from [`integration.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/integration.proto). Every method is `POST /rpc/engram.app.v1.IntegrationService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListConnectors` | [`ListConnectorsRequest`](#listconnectorsrequest) | [`ListConnectorsResponse`](#listconnectorsresponse) | | `UpsertConnector` | [`UpsertConnectorRequest`](#upsertconnectorrequest) | [`UpsertConnectorResponse`](#upsertconnectorresponse) | | `DeleteConnector` | [`DeleteConnectorRequest`](#deleteconnectorrequest) | [`DeleteConnectorResponse`](#deleteconnectorresponse) | | `GetIntegrationCatalog` | [`GetIntegrationCatalogRequest`](#getintegrationcatalogrequest) | [`GetIntegrationCatalogResponse`](#getintegrationcatalogresponse) | | `SetMintCredential` | [`SetMintCredentialRequest`](#setmintcredentialrequest) | [`SetMintCredentialResponse`](#setmintcredentialresponse) | | `UploadConnectorLogo` | [`UploadConnectorLogoRequest`](#uploadconnectorlogorequest) | [`UploadConnectorLogoResponse`](#uploadconnectorlogoresponse) | | `TestConnector` | [`TestConnectorRequest`](#testconnectorrequest) | [`TestConnectorResponse`](#testconnectorresponse) | | `SetConnectorSettings` | [`SetConnectorSettingsRequest`](#setconnectorsettingsrequest) | [`SetConnectorSettingsResponse`](#setconnectorsettingsresponse) | | `ListConnections` | [`ListConnectionsRequest`](#listconnectionsrequest) | [`ListConnectionsResponse`](#listconnectionsresponse) | | `CreateConnection` | [`CreateConnectionRequest`](#createconnectionrequest) | [`CreateConnectionResponse`](#createconnectionresponse) | | `UpdateConnection` | [`UpdateConnectionRequest`](#updateconnectionrequest) | [`UpdateConnectionResponse`](#updateconnectionresponse) | | `DeleteConnection` | [`DeleteConnectionRequest`](#deleteconnectionrequest) | [`DeleteConnectionResponse`](#deleteconnectionresponse) | | `TestConnection` | [`TestConnectionRequest`](#testconnectionrequest) | [`TestConnectionResponse`](#testconnectionresponse) | | `SetConnectionEnabled` | [`SetConnectionEnabledRequest`](#setconnectionenabledrequest) | [`SetConnectionEnabledResponse`](#setconnectionenabledresponse) | | `GetGoogleCloudSetup` | [`GetGoogleCloudSetupRequest`](#getgooglecloudsetuprequest) | [`GetGoogleCloudSetupResponse`](#getgooglecloudsetupresponse) | ## Messages ### CatalogCapability | Field | Type | |---|---| | `action` | `string` | | `access` | `string` | | `asset` | `string` | | `label` | `string` | | `host` | `string` | | `endpoint_rule` | `string` | ### Connector | Field | Type | |---|---| | `provider` | `string` | | `config_json` | `string` | | `builtin` | `bool` | | `created_at` | `string` | | `updated_at` | `string` | | `status` | `string` | | `settings` | `map` | ### ConnectorDisplay | Field | Type | |---|---| | `name` | `string` | | `category` | `string` | | `blurb` | `string` | | `icon` | [`ConnectorIcon`](#connectoricon) | | `featured` | `bool` | ### ConnectorIcon | Field | Type | |---|---| | `mono` | `string` | | `color` | `string` | | `logo` | `string` | ### CreateConnectionRequest | Field | Type | |---|---| | `alias` | `string` | | `provider` | `string` | | `display_name` | `string` | | `google_cloud` | [`GoogleCloudConnectionConfig`](#googlecloudconnectionconfig) | ### CreateConnectionResponse | Field | Type | |---|---| | `connection` | [`IntegrationConnection`](#integrationconnection) | ### DeleteConnectionRequest | Field | Type | |---|---| | `id` | `string` | ### DeleteConnectionResponse | Field | Type | |---|---| | `deleted` | `bool` | ### DeleteConnectorRequest | Field | Type | |---|---| | `provider` | `string` | ### DeleteConnectorResponse | Field | Type | |---|---| | `deleted` | `bool` | ### GetGoogleCloudSetupRequest | Field | Type | |---|---| | `id` | `string` | ### GetGoogleCloudSetupResponse | Field | Type | |---|---| | `issuer` | `string` | | `audience` | `string` | | `subject_attribute` | `string` | | `connection_attribute` | `string` | | `gcloud_script` | `string` | | `terraform` | `string` | ### GetIntegrationCatalogRequest No fields. ### GetIntegrationCatalogResponse | Field | Type | |---|---| | `providers` | repeated [`ProviderCatalogEntry`](#providercatalogentry) | ### GoogleCloudConnectionConfig | Field | Type | |---|---| | `workload_identity_provider` | `string` | | `service_account_email` | `string` | | `endpoints` | repeated `string` | | `cloud_sql_postgres_instance` | `string` | ### IntegrationConnection | Field | Type | |---|---| | `id` | `string` | | `alias` | `string` | | `provider` | `string` | | `display_name` | `string` | | `enabled` | `bool` | | `tested_at` | `string` | | `created_at` | `string` | | `updated_at` | `string` | | `google_cloud` | [`GoogleCloudConnectionConfig`](#googlecloudconnectionconfig) | | `is_default` | `bool` | ### ListConnectionsRequest No fields. ### ListConnectionsResponse | Field | Type | |---|---| | `connections` | repeated [`IntegrationConnection`](#integrationconnection) | ### ListConnectorsRequest No fields. ### ListConnectorsResponse | Field | Type | |---|---| | `connectors` | repeated [`Connector`](#connector) | ### ProviderCatalogEntry | Field | Type | |---|---| | `provider` | `string` | | `display` | [`ConnectorDisplay`](#connectordisplay) | | `credential_source` | `string` | | `hosts` | repeated `string` | | `capabilities` | repeated [`CatalogCapability`](#catalogcapability) | | `default_connection_id` | `string` | | `connection_model` | `string` | | `user_credential` | [`UserCredentialSupport`](#usercredentialsupport) | ### SetConnectionEnabledRequest | Field | Type | |---|---| | `id` | `string` | | `enabled` | `bool` | ### SetConnectionEnabledResponse | Field | Type | |---|---| | `connection` | [`IntegrationConnection`](#integrationconnection) | ### SetConnectorSettingsRequest | Field | Type | |---|---| | `provider` | `string` | | `settings` | `map` | ### SetConnectorSettingsResponse | Field | Type | |---|---| | `connector` | [`Connector`](#connector) | ### SetMintCredentialRequest | Field | Type | |---|---| | `provider` | `string` | | `kind` | `string` | | `values` | `map` | ### SetMintCredentialResponse | Field | Type | |---|---| | `secret_names` | repeated `string` | ### TestConnectionRequest | Field | Type | |---|---| | `id` | `string` | ### TestConnectionResponse | Field | Type | |---|---| | `ok` | `bool` | | `message` | `string` | ### TestConnectorRequest | Field | Type | |---|---| | `provider` | `string` | | `draft_values` | `map` | | `draft_settings` | `map` | ### TestConnectorResponse | Field | Type | |---|---| | `ok` | `bool` | | `message` | `string` | ### UpdateConnectionRequest | Field | Type | |---|---| | `id` | `string` | | `alias` | `string` | | `display_name` | `string` | | `google_cloud` | [`GoogleCloudConnectionConfig`](#googlecloudconnectionconfig) | ### UpdateConnectionResponse | Field | Type | |---|---| | `connection` | [`IntegrationConnection`](#integrationconnection) | ### UploadConnectorLogoRequest | Field | Type | |---|---| | `provider` | `string` | | `data` | `bytes` | | `media_type` | `string` | ### UploadConnectorLogoResponse | Field | Type | |---|---| | `logo_url` | `string` | ### UpsertConnectorRequest | Field | Type | |---|---| | `config_json` | `string` | ### UpsertConnectorResponse | Field | Type | |---|---| | `connector` | [`Connector`](#connector) | ### UserCredentialSupport | Field | Type | |---|---| | `oauth` | `bool` | | `token` | `bool` | | `token_hint` | `string` | --- # MintService > The MintService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/mint/ Generated from [`mint.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/mint.proto). Every method is `POST /rpc/engram.app.v1.MintService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListMintKinds` | [`ListMintKindsRequest`](#listmintkindsrequest) | [`ListMintKindsResponse`](#listmintkindsresponse) | ## Messages ### ListMintKindsRequest No fields. ### ListMintKindsResponse | Field | Type | |---|---| | `mint_kinds` | repeated [`MintKind`](#mintkind) | ### MintFieldDescriptor | Field | Type | |---|---| | `name` | `string` | | `label` | `string` | | `field_kind` | [`MintFieldKind`](#mintfieldkind) | | `required` | `bool` | ### MintKind | Field | Type | |---|---| | `kind` | `string` | | `provider` | `string` | | `display_name` | `string` | | `fields` | repeated [`MintFieldDescriptor`](#mintfielddescriptor) | ## Enums ### MintFieldKind | Value | Number | |---|---| | `MINT_FIELD_KIND_UNSPECIFIED` | 0 | | `MINT_FIELD_KIND_CONFIG` | 1 | | `MINT_FIELD_KIND_SEALED_SECRET` | 2 | --- # ModelRouterService > The ModelRouterService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/model-router/ Generated from [`model_router.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/model_router.proto). Every method is `POST /rpc/engram.app.v1.ModelRouterService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListModelRouters` | [`ListModelRoutersRequest`](#listmodelroutersrequest) | [`ListModelRoutersResponse`](#listmodelroutersresponse) | | `ListRouterModels` | [`ListRouterModelsRequest`](#listroutermodelsrequest) | [`ListRouterModelsResponse`](#listroutermodelsresponse) | | `RefreshRouterModels` | [`RefreshRouterModelsRequest`](#refreshroutermodelsrequest) | [`RefreshRouterModelsResponse`](#refreshroutermodelsresponse) | | `UpdateRouterModelPolicy` | [`UpdateRouterModelPolicyRequest`](#updateroutermodelpolicyrequest) | [`UpdateRouterModelPolicyResponse`](#updateroutermodelpolicyresponse) | ## Messages ### ListModelRoutersRequest No fields. ### ListModelRoutersResponse | Field | Type | |---|---| | `routers` | repeated [`ModelRouter`](#modelrouter) | ### ListRouterModelsRequest | Field | Type | |---|---| | `router_id` | `string` | | `audience` | [`RouterModelAudience`](#routermodelaudience) | | `search` | `string` | ### ListRouterModelsResponse | Field | Type | |---|---| | `models` | repeated [`RouterModel`](#routermodel) | ### ModelRouter | Field | Type | |---|---| | `id` | `string` | | `label` | `string` | | `description` | `string` | | `protocols` | repeated `string` | | `credential_secret` | `string` | | `egress_hosts` | repeated `string` | | `credential_configured` | `bool` | | `last_successful_sync_at` | `string` (optional) | | `last_sync_error` | `string` (optional) | | `model_count` | `uint32` | | `available_model_count` | `uint32` | | `enabled_model_count` | `uint32` | | `default_model` | `string` | ### RefreshRouterModelsRequest | Field | Type | |---|---| | `router_id` | `string` | ### RefreshRouterModelsResponse | Field | Type | |---|---| | `discovered` | `uint32` | | `available` | `uint32` | | `marked_unavailable` | `uint32` | ### RouterModel | Field | Type | |---|---| | `router_id` | `string` | | `id` | `string` | | `canonical_slug` | `string` | | `name` | `string` | | `author` | `string` (optional) | | `description` | `string` (optional) | | `context_length` | `uint64` | | `prompt_price` | `string` (optional) | | `completion_price` | `string` (optional) | | `input_modalities` | repeated `string` | | `output_modalities` | repeated `string` | | `supported_parameters` | repeated `string` | | `hugging_face_id` | `string` (optional) | | `available` | `bool` | | `enabled` | `bool` | | `user_enabled` | `bool` | | `upstream_url` | `string` | | `updated_at` | `string` | | `supports_reasoning` | `bool` | ### UpdateRouterModelPolicyRequest | Field | Type | |---|---| | `router_id` | `string` | | `model_id` | `string` | | `enabled` | `bool` | | `user_enabled` | `bool` | ### UpdateRouterModelPolicyResponse | Field | Type | |---|---| | `model` | [`RouterModel`](#routermodel) | ## Enums ### RouterModelAudience | Value | Number | |---|---| | `ROUTER_MODEL_AUDIENCE_UNSPECIFIED` | 0 | | `ROUTER_MODEL_AUDIENCE_USER` | 1 | | `ROUTER_MODEL_AUDIENCE_PROGRAMMATIC` | 2 | | `ROUTER_MODEL_AUDIENCE_ADMIN_CATALOG` | 3 | --- # MountCatalogService > The MountCatalogService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/mount-catalog/ Generated from [`mount_catalog.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/mount_catalog.proto). Every method is `POST /rpc/engram.app.v1.MountCatalogService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `RegisterSkill` | [`RegisterSkillRequest`](#registerskillrequest) | [`RegisterSkillResponse`](#registerskillresponse) | | `ListSkills` | [`ListSkillsRequest`](#listskillsrequest) | [`ListSkillsResponse`](#listskillsresponse) | | `GetSkill` | [`GetSkillRequest`](#getskillrequest) | [`GetSkillResponse`](#getskillresponse) | | `DeleteSkill` | [`DeleteSkillRequest`](#deleteskillrequest) | [`DeleteSkillResponse`](#deleteskillresponse) | ## Messages ### CatalogSkill | Field | Type | |---|---| | `id` | `string` | | `owner` | `string` | | `name` | `string` | | `description` | `string` | | `sha256` | `string` | | `size_bytes` | `int64` | | `created_at` | `string` | ### DeleteSkillRequest | Field | Type | |---|---| | `name` | `string` | ### DeleteSkillResponse | Field | Type | |---|---| | `deleted` | `bool` | ### GetSkillRequest | Field | Type | |---|---| | `name` | `string` | ### GetSkillResponse | Field | Type | |---|---| | `skill` | [`CatalogSkill`](#catalogskill) | ### ListSkillsRequest No fields. ### ListSkillsResponse | Field | Type | |---|---| | `skills` | repeated [`CatalogSkill`](#catalogskill) | ### RegisterSkillRequest | Field | Type | |---|---| | `name` | `string` | | `description` | `string` | | `owner` | `string` | | `payload_tar` | `bytes` | | `bins` | repeated `string` | ### RegisterSkillResponse | Field | Type | |---|---| | `skill` | [`CatalogSkill`](#catalogskill) | --- # OAuthCredentialService > The OAuthCredentialService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/oauth-credential/ Generated from [`oauth.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/oauth.proto). Every method is `POST /rpc/engram.app.v1.OAuthCredentialService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `BeginFlow` | [`BeginFlowRequest`](#beginflowrequest) | [`BeginFlowResponse`](#beginflowresponse) | | `GetFlow` | [`GetFlowRequest`](#getflowrequest) | [`GetFlowResponse`](#getflowresponse) | | `CancelFlow` | [`CancelFlowRequest`](#cancelflowrequest) | [`CancelFlowResponse`](#cancelflowresponse) | | `ListCredentials` | [`ListCredentialsRequest`](#listcredentialsrequest) | [`ListCredentialsResponse`](#listcredentialsresponse) | | `Disconnect` | [`DisconnectRequest`](#disconnectrequest) | [`DisconnectResponse`](#disconnectresponse) | | `PutCredential` | [`PutCredentialRequest`](#putcredentialrequest) | [`PutCredentialResponse`](#putcredentialresponse) | | `LookupRedirectFlow` | [`LookupRedirectFlowRequest`](#lookupredirectflowrequest) | [`LookupRedirectFlowResponse`](#lookupredirectflowresponse) | | `BeginRedirectFlow` | [`BeginRedirectFlowRequest`](#beginredirectflowrequest) | [`BeginRedirectFlowResponse`](#beginredirectflowresponse) | | `CompleteRedirectFlow` | [`CompleteRedirectFlowRequest`](#completeredirectflowrequest) | [`CompleteRedirectFlowResponse`](#completeredirectflowresponse) | | `GrantClientCredentials` | [`GrantClientCredentialsRequest`](#grantclientcredentialsrequest) | [`GrantClientCredentialsResponse`](#grantclientcredentialsresponse) | | `GrantServiceAccount` | [`GrantServiceAccountRequest`](#grantserviceaccountrequest) | [`GrantServiceAccountResponse`](#grantserviceaccountresponse) | | `FetchSessionCredential` | [`FetchSessionCredentialRequest`](#fetchsessioncredentialrequest) | [`FetchSessionCredentialResponse`](#fetchsessioncredentialresponse) | | `UpdateSessionCredential` | [`UpdateSessionCredentialRequest`](#updatesessioncredentialrequest) | [`UpdateSessionCredentialResponse`](#updatesessioncredentialresponse) | ## Messages ### BeginFlowRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | ### BeginFlowResponse | Field | Type | |---|---| | `flow` | [`OAuthFlow`](#oauthflow) | | `verification_url` | `string` | | `user_code` | `string` | ### BeginRedirectFlowRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `spec` | [`RedirectOauthSpec`](#redirectoauthspec) | | `redirect_uri` | `string` | ### BeginRedirectFlowResponse | Field | Type | |---|---| | `flow` | [`OAuthFlow`](#oauthflow) | | `authorize_url` | `string` | ### CancelFlowRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `flow_id` | `string` | ### CancelFlowResponse | Field | Type | |---|---| | `flow` | [`OAuthFlow`](#oauthflow) | ### ClientCredentialsSpec | Field | Type | |---|---| | `token_url` | `string` | | `scopes` | repeated `string` | | `scope_delimiter` | `string` | | `client_id_ref` | `string` | | `client_secret_ref` | `string` | | `token_request_body` | `string` | | `metadata` | [`RedirectMetadataSpec`](#redirectmetadataspec) | ### CompleteRedirectFlowRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `flow_id` | `string` | | `code` | `string` | | `redirect_uri` | `string` | | `spec` | [`RedirectOauthSpec`](#redirectoauthspec) | ### CompleteRedirectFlowResponse | Field | Type | |---|---| | `credential` | [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### DisconnectRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `expected_version` | `int64` | ### DisconnectResponse | Field | Type | |---|---| | `credential` | [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### FetchSessionCredentialRequest | Field | Type | |---|---| | `session_id` | `string` | | `broker_token` | `string` | ### FetchSessionCredentialResponse | Field | Type | |---|---| | `provider` | `string` | | `version` | `int64` | | `opaque_bundle` | `bytes` | ### GetFlowRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `flow_id` | `string` | ### GetFlowResponse | Field | Type | |---|---| | `flow` | [`OAuthFlow`](#oauthflow) | ### GrantClientCredentialsRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `spec` | [`ClientCredentialsSpec`](#clientcredentialsspec) | ### GrantClientCredentialsResponse | Field | Type | |---|---| | `credential` | [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### GrantServiceAccountRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `spec` | [`ServiceAccountSpec`](#serviceaccountspec) | ### GrantServiceAccountResponse | Field | Type | |---|---| | `credential` | [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### ListCredentialsRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | ### ListCredentialsResponse | Field | Type | |---|---| | `credentials` | repeated [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### LookupRedirectFlowRequest | Field | Type | |---|---| | `flow_id` | `string` | ### LookupRedirectFlowResponse | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `status` | `string` | ### OAuthAccountMetadata | Field | Type | |---|---| | `display_name` | `string` (optional) | | `plan_type` | `string` (optional) | | `workspace_id` | `string` (optional) | | `workspace_name` | `string` (optional) | ### OAuthCredentialMeta | Field | Type | |---|---| | `provider` | `string` | | `version` | `int64` | | `connected` | `bool` | | `account` | [`OAuthAccountMetadata`](#oauthaccountmetadata) | | `created_at` | `string` | | `updated_at` | `string` | | `status` | `string` | | `expires_at` | `string` | | `subject_id` | `string` | ### OAuthFlow | Field | Type | |---|---| | `id` | `string` | | `provider` | `string` | | `status` | `string` | | `error_code` | `string` (optional) | | `expires_at` | `string` | | `updated_at` | `string` | ### OAuthSubject | Field | Type | |---|---| | `kind` | [`OauthSubjectKind`](#oauthsubjectkind) | | `id` | `string` | ### PutCredentialRequest | Field | Type | |---|---| | `subject` | [`OAuthSubject`](#oauthsubject) | | `provider` | `string` | | `secret` | `string` | | `identity` | [`RedirectMetadataProbe`](#redirectmetadataprobe) | ### PutCredentialResponse | Field | Type | |---|---| | `credential` | [`OAuthCredentialMeta`](#oauthcredentialmeta) | ### RedirectMetadataProbe | Field | Type | |---|---| | `method` | `string` | | `host` | `string` | | `path` | `string` | | `body` | `string` | | `map` | `map` | ### RedirectMetadataSpec | Field | Type | |---|---| | `from_token_response` | `map` | | `probe` | [`RedirectMetadataProbe`](#redirectmetadataprobe) | ### RedirectOauthSpec | Field | Type | |---|---| | `authorize_url` | `string` | | `token_url` | `string` | | `scopes` | repeated `string` | | `scope_delimiter` | `string` | | `extra_authorize_params` | `map` | | `client_id_ref` | `string` | | `client_secret_ref` | `string` | | `pkce` | `bool` | | `metadata` | [`RedirectMetadataSpec`](#redirectmetadataspec) | | `scopes_param` | `string` | | `grant_path` | `string` | ### ServiceAccountSpec | Field | Type | |---|---| | `token_url` | `string` | | `scopes` | repeated `string` | | `scope_delimiter` | `string` | | `key_ref` | `string` | | `subject` | `string` | | `metadata` | [`RedirectMetadataSpec`](#redirectmetadataspec) | ### UpdateSessionCredentialRequest | Field | Type | |---|---| | `session_id` | `string` | | `broker_token` | `string` | | `expected_version` | `int64` | | `opaque_bundle` | `bytes` | ### UpdateSessionCredentialResponse | Field | Type | |---|---| | `provider` | `string` | | `version` | `int64` | | `opaque_bundle` | `bytes` | ## Enums ### OauthSubjectKind | Value | Number | |---|---| | `OAUTH_SUBJECT_KIND_UNSPECIFIED` | 0 | | `OAUTH_SUBJECT_KIND_USER` | 1 | | `OAUTH_SUBJECT_KIND_CONNECTOR` | 2 | | `OAUTH_SUBJECT_KIND_MCP` | 3 | | `OAUTH_SUBJECT_KIND_USER_CONNECTOR` | 4 | --- # OrgSecretService > The OrgSecretService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/org-secret/ Generated from [`org_secret.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/org_secret.proto). Every method is `POST /rpc/engram.app.v1.OrgSecretService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `PutSecret` | [`PutSecretRequest`](#putsecretrequest) | [`PutSecretResponse`](#putsecretresponse) | | `ListSecrets` | [`ListSecretsRequest`](#listsecretsrequest) | [`ListSecretsResponse`](#listsecretsresponse) | | `DeleteSecret` | [`DeleteSecretRequest`](#deletesecretrequest) | [`DeleteSecretResponse`](#deletesecretresponse) | ## Messages ### DeleteSecretRequest | Field | Type | |---|---| | `name` | `string` | ### DeleteSecretResponse | Field | Type | |---|---| | `deleted` | `bool` | ### ListSecretsRequest No fields. ### ListSecretsResponse | Field | Type | |---|---| | `secrets` | repeated [`OrgSecretMeta`](#orgsecretmeta) | ### OrgSecretMeta | Field | Type | |---|---| | `name` | `string` | | `key_id` | `string` | | `created_at` | `string` | | `updated_at` | `string` | ### PutSecretRequest | Field | Type | |---|---| | `name` | `string` | | `value` | `string` | ### PutSecretResponse | Field | Type | |---|---| | `secret` | [`OrgSecretMeta`](#orgsecretmeta) | --- # PapercutService > The PapercutService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/papercut/ Generated from [`papercut.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/papercut.proto). Every method is `POST /rpc/engram.app.v1.PapercutService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListPapercuts` | [`ListPapercutsRequest`](#listpapercutsrequest) | [`ListPapercutsResponse`](#listpapercutsresponse) | | `ArchivePapercut` | [`ArchivePapercutRequest`](#archivepapercutrequest) | [`ArchivePapercutResponse`](#archivepapercutresponse) | | `UnarchivePapercut` | [`UnarchivePapercutRequest`](#unarchivepapercutrequest) | [`UnarchivePapercutResponse`](#unarchivepapercutresponse) | ## Messages ### ArchivePapercutRequest | Field | Type | |---|---| | `id` | `string` | ### ArchivePapercutResponse | Field | Type | |---|---| | `papercut` | [`Papercut`](#papercut) | ### ListPapercutsRequest | Field | Type | |---|---| | `include_archived` | `bool` | ### ListPapercutsResponse | Field | Type | |---|---| | `papercuts` | repeated [`Papercut`](#papercut) | ### Papercut | Field | Type | |---|---| | `id` | `string` | | `summary` | `string` | | `description` | `string` | | `category` | `string` | | `severity` | `string` | | `tags` | repeated `string` | | `session_id` | `string` | | `task_id` | `string` | | `archived` | `bool` | | `created_at` | `google.protobuf.Timestamp` | | `profile` | `ProfileSnapshot` | ### UnarchivePapercutRequest | Field | Type | |---|---| | `id` | `string` | ### UnarchivePapercutResponse | Field | Type | |---|---| | `papercut` | [`Papercut`](#papercut) | --- # PortRelayService > The PortRelayService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/port-relay/ Generated from [`session.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/session.proto). Every method is `POST /rpc/engram.app.v1.PortRelayService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `Relay` | [`RelayPortRequest`](#relayportrequest) (stream) | [`RelayPortResponse`](#relayportresponse) (stream) | ## Messages ### PortClose No fields. ### PortOpen | Field | Type | |---|---| | `session_id` | `string` | | `port` | `uint32` | ### RelayPortRequest | Field | Type | |---|---| | `open` | [`PortOpen`](#portopen) (one of frame) | | `data` | `bytes` (one of frame) | | `close` | [`PortClose`](#portclose) (one of frame) | ### RelayPortResponse | Field | Type | |---|---| | `data` | `bytes` (one of frame) | | `close` | [`PortClose`](#portclose) (one of frame) | --- # ProfileService > The ProfileService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/profile/ Generated from [`profile.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/profile.proto). Every method is `POST /rpc/engram.app.v1.ProfileService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListProfiles` | [`ListProfilesRequest`](#listprofilesrequest) | [`ListProfilesResponse`](#listprofilesresponse) | | `GetProfile` | [`GetProfileRequest`](#getprofilerequest) | [`GetProfileResponse`](#getprofileresponse) | | `CreateProfile` | [`CreateProfileRequest`](#createprofilerequest) | [`CreateProfileResponse`](#createprofileresponse) | | `UpdateProfile` | [`UpdateProfileRequest`](#updateprofilerequest) | [`UpdateProfileResponse`](#updateprofileresponse) | | `DiscoverProfileRepos` | [`DiscoverProfileReposRequest`](#discoverprofilereposrequest) | [`DiscoverProfileReposResponse`](#discoverprofilereposresponse) | | `DeleteProfile` | [`DeleteProfileRequest`](#deleteprofilerequest) | [`DeleteProfileResponse`](#deleteprofileresponse) | ## Messages ### CreateProfileRequest | Field | Type | |---|---| | `name` | `string` | | `description` | `string` | | `icon` | `string` | | `image_id` | `string` | | `include_user_tokens` | `bool` | | `env_vars` | `map` | | `skills` | repeated `string` | | `network` | [`ProfileNetwork`](#profilenetwork) | | `secrets` | repeated [`ProfileSecret`](#profilesecret) | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `effort` | `string` (optional) | | `integration_grants` | repeated [`ProfileIntegrationGrant`](#profileintegrationgrant) | | `repos` | repeated [`ProfileRepo`](#profilerepo) | | `model_router` | `string` (optional) | | `apps` | repeated [`SessionApp`](#sessionapp) | | `programmatic_only` | `bool` | ### CreateProfileResponse | Field | Type | |---|---| | `profile` | [`Profile`](#profile) | ### DeleteProfileRequest | Field | Type | |---|---| | `id` | `string` | ### DeleteProfileResponse No fields. ### DiscoveredRemote | Field | Type | |---|---| | `name` | `string` | | `url` | `string` | | `parsed` | [`ProfileRepoRemote`](#profilereporemote) (optional) | ### DiscoveredRepo | Field | Type | |---|---| | `path` | `string` | | `remotes` | repeated [`DiscoveredRemote`](#discoveredremote) | ### DiscoverProfileReposRequest | Field | Type | |---|---| | `profile_id` | `string` | ### DiscoverProfileReposResponse | Field | Type | |---|---| | `repos` | repeated [`DiscoveredRepo`](#discoveredrepo) | ### GetProfileRequest | Field | Type | |---|---| | `id` | `string` | ### GetProfileResponse | Field | Type | |---|---| | `profile` | [`Profile`](#profile) | ### ListProfilesRequest | Field | Type | |---|---| | `include_archived` | `bool` | | `for_session_picker` | `bool` | ### ListProfilesResponse | Field | Type | |---|---| | `profiles` | repeated [`Profile`](#profile) | ### Profile | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `description` | `string` | | `icon` | `string` | | `image_id` | `string` | | `include_user_tokens` | `bool` | | `env_vars` | `map` | | `archived` | `bool` | | `created_at` | `string` | | `updated_at` | `string` | | `skills` | repeated `string` | | `network` | [`ProfileNetwork`](#profilenetwork) | | `secrets` | repeated [`ProfileSecret`](#profilesecret) | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `effort` | `string` (optional) | | `integration_grants` | repeated [`ProfileIntegrationGrant`](#profileintegrationgrant) | | `repos` | repeated [`ProfileRepo`](#profilerepo) | | `model_router` | `string` (optional) | | `apps` | repeated [`SessionApp`](#sessionapp) | | `programmatic_only` | `bool` | ### ProfileIntegrationGrant | Field | Type | |---|---| | `connection_id` | `string` | | `operation` | `string` | | `resource_constraints` | repeated `string` | | `credential_scope` | `string` | ### ProfileNetwork | Field | Type | |---|---| | `default` | `string` | | `allow_hosts` | repeated `string` | | `allow_host_patterns` | repeated `string` | ### ProfileRepo | Field | Type | |---|---| | `path` | `string` | | `remote_url` | `string` | | `remote` | [`ProfileRepoRemote`](#profilereporemote) (optional) | ### ProfileRepoRemote | Field | Type | |---|---| | `host` | `string` | | `owner` | `string` | | `name` | `string` | ### ProfileSecret | Field | Type | |---|---| | `ref` | `string` | | `env_var` | `string` | | `mode` | `string` | | `allow_hosts` | repeated `string` | | `allow_host_patterns` | repeated `string` | ### SessionApp | Field | Type | |---|---| | `name` | `string` | | `port` | `uint32` | ### UpdateProfileRequest | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `description` | `string` | | `icon` | `string` | | `image_id` | `string` | | `include_user_tokens` | `bool` | | `env_vars` | `map` | | `skills` | repeated `string` | | `network` | [`ProfileNetwork`](#profilenetwork) | | `secrets` | repeated [`ProfileSecret`](#profilesecret) | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `effort` | `string` (optional) | | `integration_grants` | repeated [`ProfileIntegrationGrant`](#profileintegrationgrant) | | `repos` | repeated [`ProfileRepo`](#profilerepo) | | `model_router` | `string` (optional) | | `apps` | repeated [`SessionApp`](#sessionapp) | | `programmatic_only` | `bool` (optional) | ### UpdateProfileResponse | Field | Type | |---|---| | `profile` | [`Profile`](#profile) | --- # PrRefService > The PrRefService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/pr-ref/ Generated from [`pr_ref.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/pr_ref.proto). Every method is `POST /rpc/engram.app.v1.PrRefService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListPrRefs` | [`ListPrRefsRequest`](#listprrefsrequest) | [`ListPrRefsResponse`](#listprrefsresponse) | ## Messages ### ListPrRefsRequest | Field | Type | |---|---| | `task_id` | `string` (optional) | | `session_id` | `string` (optional) | ### ListPrRefsResponse | Field | Type | |---|---| | `pr_refs` | repeated [`PrRef`](#prref) | ### PrRef | Field | Type | |---|---| | `id` | `string` | | `repo` | `string` | | `pr_number` | `int32` | | `authoring_task_id` | `string` (optional) | | `session_id` | `string` | | `title` | `string` | | `url` | `string` | | `head_branch` | `string` | | `base_branch` | `string` | | `observed_at` | `google.protobuf.Timestamp` | --- # RetentionService > The RetentionService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/retention/ Generated from [`retention.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/retention.proto). Every method is `POST /rpc/engram.app.v1.RetentionService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `GetRetentionPolicy` | [`GetRetentionPolicyRequest`](#getretentionpolicyrequest) | [`GetRetentionPolicyResponse`](#getretentionpolicyresponse) | | `SetRetentionPolicy` | [`SetRetentionPolicyRequest`](#setretentionpolicyrequest) | [`SetRetentionPolicyResponse`](#setretentionpolicyresponse) | ## Messages ### GetRetentionPolicyRequest No fields. ### GetRetentionPolicyResponse | Field | Type | |---|---| | `policy` | [`RetentionPolicy`](#retentionpolicy) | ### RetentionPolicy | Field | Type | |---|---| | `run_detail_days` | `int32` | ### SetRetentionPolicyRequest | Field | Type | |---|---| | `policy` | [`RetentionPolicy`](#retentionpolicy) | ### SetRetentionPolicyResponse | Field | Type | |---|---| | `policy` | [`RetentionPolicy`](#retentionpolicy) | --- # ReviewService > The ReviewService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/review/ Generated from [`review.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/review.proto). Every method is `POST /rpc/engram.app.v1.ReviewService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListReviews` | [`ListReviewsRequest`](#listreviewsrequest) | [`ListReviewsResponse`](#listreviewsresponse) | | `GetReview` | [`GetReviewRequest`](#getreviewrequest) | [`GetReviewResponse`](#getreviewresponse) | | `RetryReview` | [`RetryReviewRequest`](#retryreviewrequest) | [`RetryReviewResponse`](#retryreviewresponse) | ## Messages ### FindingCounts | Field | Type | |---|---| | `critical` | `int32` | | `high` | `int32` | | `medium` | `int32` | | `low` | `int32` | | `total` | `int32` | ### GetReviewRequest | Field | Type | |---|---| | `id` | `string` | ### GetReviewResponse | Field | Type | |---|---| | `review` | [`Review`](#review) | | `findings` | repeated [`ReviewFinding`](#reviewfinding) | | `verdicts` | repeated [`ReviewVerdict`](#reviewverdict) | | `passes` | repeated [`Review`](#review) | | `events` | repeated [`ReviewEvent`](#reviewevent) | ### ListReviewsRequest | Field | Type | |---|---| | `repos` | repeated `string` | | `search` | `string` | | `authors` | repeated `string` | | `pr_states` | repeated `string` | | `statuses` | repeated `string` | | `severities` | repeated `string` | | `page` | `int32` | | `page_size` | `int32` | ### ListReviewsResponse | Field | Type | |---|---| | `reviews` | repeated [`Review`](#review) | | `total_count` | `int32` | | `facets` | [`ReviewFacets`](#reviewfacets) | ### RetryReviewRequest | Field | Type | |---|---| | `id` | `string` | ### RetryReviewResponse | Field | Type | |---|---| | `workflow_id` | `string` | | `review_id` | `string` (optional) | ### Review | Field | Type | |---|---| | `id` | `string` | | `repo` | `string` | | `pr_number` | `int32` | | `task_id` | `string` | | `head_sha` | `string` | | `base_sha` | `string` | | `trigger` | `string` | | `status` | `string` | | `github_review_id` | `string` (optional) | | `summary_md` | `string` (optional) | | `created_at` | `google.protobuf.Timestamp` | | `updated_at` | `google.protobuf.Timestamp` | | `finding_counts` | [`FindingCounts`](#findingcounts) | | `finder_session_id` | `string` (optional) | | `verifier_session_id` | `string` (optional) | | `pr_title` | `string` (optional) | | `pr_author` | `string` (optional) | | `head_branch` | `string` (optional) | | `base_branch` | `string` (optional) | | `pr_state` | `string` (optional) | | `additions` | `int32` (optional) | | `deletions` | `int32` (optional) | | `changed_files` | `int32` (optional) | | `target_id` | `string` | | `provider` | `string` | | `provider_id` | `string` (optional) | | `pr_url` | `string` (optional) | | `active` | `bool` | | `human_trigger` | `bool` | | `automation_run_id` | `string` (optional) | ### ReviewEvent | Field | Type | |---|---| | `id` | `string` | | `review_id` | `string` | | `kind` | `string` | | `detail` | `string` (optional) | | `created_at` | `google.protobuf.Timestamp` | ### ReviewFacets | Field | Type | |---|---| | `repos` | repeated `string` | | `authors` | repeated `string` | | `pr_states` | repeated `string` | | `statuses` | repeated `string` | ### ReviewFinding | Field | Type | |---|---| | `id` | `string` | | `review_id` | `string` | | `path` | `string` | | `start_line` | `int32` (optional) | | `end_line` | `int32` (optional) | | `side` | `string` (optional) | | `category` | `string` | | `severity` | `string` | | `confidence` | `string` | | `title` | `string` | | `body_md` | `string` | | `suggested_fix` | `string` (optional) | | `evidence` | repeated `string` | | `state` | `string` | | `verdict_reason` | `string` (optional) | | `github_thread_id` | `string` (optional) | | `resolution` | `string` (optional) | | `session_id` | `string` | | `created_at` | `google.protobuf.Timestamp` | ### ReviewVerdict | Field | Type | |---|---| | `finding_id` | `string` | | `verdict` | `string` | | `confidence` | `string` | | `reasoning` | `string` | | `session_id` | `string` | --- # SessionService > The SessionService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/session/ Generated from [`session.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/session.proto). Every method is `POST /rpc/engram.app.v1.SessionService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `ListSessions` | [`ListSessionsRequest`](#listsessionsrequest) | [`ListSessionsResponse`](#listsessionsresponse) | | `CreateSession` | [`CreateSessionRequest`](#createsessionrequest) | [`CreateSessionResponse`](#createsessionresponse) | | `GetSession` | [`GetSessionRequest`](#getsessionrequest) | [`GetSessionResponse`](#getsessionresponse) | | `DeleteSession` | [`DeleteSessionRequest`](#deletesessionrequest) | [`DeleteSessionResponse`](#deletesessionresponse) | | `SendPrompt` | [`SendPromptRequest`](#sendpromptrequest) | [`SendPromptResponse`](#sendpromptresponse) | | `Interrupt` | [`InterruptRequest`](#interruptrequest) | [`InterruptResponse`](#interruptresponse) | | `EditQueuedPrompt` | [`EditQueuedPromptRequest`](#editqueuedpromptrequest) | [`EditQueuedPromptResponse`](#editqueuedpromptresponse) | | `DequeueQueuedPrompt` | [`DequeueQueuedPromptRequest`](#dequeuequeuedpromptrequest) | [`DequeueQueuedPromptResponse`](#dequeuequeuedpromptresponse) | | `CompleteToolCall` | [`CompleteToolCallRequest`](#completetoolcallrequest) | [`CompleteToolCallResponse`](#completetoolcallresponse) | | `StreamEvents` | [`StreamEventsRequest`](#streameventsrequest) | [`SessionEvent`](#sessionevent) (stream) | | `ListSessionEvents` | [`ListSessionEventsRequest`](#listsessioneventsrequest) | [`ListSessionEventsResponse`](#listsessioneventsresponse) | | `Exec` | [`ExecRequest`](#execrequest) | [`ExecOutput`](#execoutput) (stream) | | `CancelExec` | [`CancelExecRequest`](#cancelexecrequest) | [`CancelExecResponse`](#cancelexecresponse) | | `WriteFile` | [`WriteFileRequest`](#writefilerequest) (stream) | [`WriteFileResponse`](#writefileresponse) | | `ReadFile` | [`ReadFileRequest`](#readfilerequest) | [`ReadFileResponse`](#readfileresponse) (stream) | | `CopyFiles` | [`CopyFilesRequest`](#copyfilesrequest) | [`CopyFilesResponse`](#copyfilesresponse) | | `GetLog` | [`GetLogRequest`](#getlogrequest) | [`GetLogResponse`](#getlogresponse) | | `Snapshot` | [`SnapshotRequest`](#snapshotrequest) | [`SnapshotResponse`](#snapshotresponse) | | `EnsureBrowser` | [`EnsureBrowserRequest`](#ensurebrowserrequest) | [`EnsureBrowserResponse`](#ensurebrowserresponse) | | `EnsureIde` | [`EnsureIdeRequest`](#ensureiderequest) | [`EnsureIdeResponse`](#ensureideresponse) | | `Resume` | [`ResumeRequest`](#resumerequest) | [`ResumeResponse`](#resumeresponse) | | `EvictLocal` | [`EvictLocalRequest`](#evictlocalrequest) | [`EvictLocalResponse`](#evictlocalresponse) | | `EvictIdle` | [`EvictIdleRequest`](#evictidlerequest) | [`EvictIdleResponse`](#evictidleresponse) | | `ListCheckpoints` | [`ListCheckpointsRequest`](#listcheckpointsrequest) | [`ListCheckpointsResponse`](#listcheckpointsresponse) | | `GetArtifact` | [`GetArtifactRequest`](#getartifactrequest) | [`GetArtifactResponse`](#getartifactresponse) (stream) | | `CreateArtifactFromPath` | [`CreateArtifactFromPathRequest`](#createartifactfrompathrequest) | [`CreateArtifactFromPathResponse`](#createartifactfrompathresponse) | ## Messages ### AppEndpoint | Field | Type | |---|---| | `hostname` | `string` | | `port` | `uint32` | ### ArtifactMetadata | Field | Type | |---|---| | `media_type` | `string` | | `size_bytes` | `uint64` | | `file_name` | `string` | ### CancelExecRequest | Field | Type | |---|---| | `session_id` | `string` | | `exec_id` | `string` | ### CancelExecResponse No fields. ### CheckpointSummary | Field | Type | |---|---| | `snapshot_id` | `string` | | `created_at` | `string` | | `size_bytes` | `uint64` | | `events_cursor` | `int64` (optional) | | `recoverable` | `bool` | | `is_latest` | `bool` | ### CompleteToolCallRequest | Field | Type | |---|---| | `session_id` | `string` | | `tool_call_id` | `string` | | `result_json` | `string` | ### CompleteToolCallResponse | Field | Type | |---|---| | `session_id` | `string` | | `note` | `string` | ### ConversationEntry | Field | Type | |---|---| | `idx` | `int64` | | `kind` | `string` | | `at` | `string` | | `payload_json` | `string` | ### CopyFileResult | Field | Type | |---|---| | `path` | `string` | | `size_bytes` | `uint64` | | `sha256` | `string` | ### CopyFilesRequest | Field | Type | |---|---| | `source_session_id` | `string` | | `target_session_id` | `string` | | `paths` | repeated `string` | ### CopyFilesResponse | Field | Type | |---|---| | `files` | repeated [`CopyFileResult`](#copyfileresult) | ### CreateArtifactFromPathRequest | Field | Type | |---|---| | `session_id` | `string` | | `path` | `string` | | `caption` | `string` (optional) | | `suppress_event` | `bool` | ### CreateArtifactFromPathResponse | Field | Type | |---|---| | `artifact_id` | `string` | | `media_type` | `string` | | `size_bytes` | `uint64` | ### CreateSessionRequest | Field | Type | |---|---| | `image_uri` | `string` | | `mode` | `string` | | `prompt` | `string` (optional) | | `prompt_id` | `string` (optional) | | `secrets` | `map` | | `harness_env` | `map` | | `selected_skills` | repeated `string` | | `capabilities` | repeated `string` | | `integration_policy_json` | `string` | | `harness` | `string` (optional) | | `oauth_credential` | [`OAuthCredentialBinding`](#oauthcredentialbinding) | | `harness_mode` | `string` (optional) | | `requested_session_id` | `string` (optional) | | `apps` | repeated [`AppEndpoint`](#appendpoint) | ### CreateSessionResponse | Field | Type | |---|---| | `session_id` | `string` | | `status` | `string` | | `image_version` | `string` | | `kind` | `string` | ### DeleteSessionRequest | Field | Type | |---|---| | `session_id` | `string` | ### DeleteSessionResponse No fields. ### DequeueQueuedPromptRequest | Field | Type | |---|---| | `session_id` | `string` | | `prompt_id` | `string` | ### DequeueQueuedPromptResponse | Field | Type | |---|---| | `session_id` | `string` | | `note` | `string` | ### EditQueuedPromptRequest | Field | Type | |---|---| | `session_id` | `string` | | `prompt_id` | `string` | | `text` | `string` | ### EditQueuedPromptResponse | Field | Type | |---|---| | `session_id` | `string` | | `note` | `string` | ### EnsureBrowserRequest | Field | Type | |---|---| | `session_id` | `string` | ### EnsureBrowserResponse | Field | Type | |---|---| | `port` | `uint32` | ### EnsureIdeRequest | Field | Type | |---|---| | `session_id` | `string` | ### EnsureIdeResponse | Field | Type | |---|---| | `port` | `uint32` | ### EvictIdleRequest | Field | Type | |---|---| | `session_id` | `string` | ### EvictIdleResponse | Field | Type | |---|---| | `session_id` | `string` | | `status` | `string` | ### EvictLocalRequest | Field | Type | |---|---| | `session_id` | `string` | ### EvictLocalResponse No fields. ### ExecExit | Field | Type | |---|---| | `exit_status` | `int32` (optional) | | `rusage` | [`ExecRusage`](#execrusage) | ### ExecOutput | Field | Type | |---|---| | `started` | [`ExecStarted`](#execstarted) (one of event) | | `stdout` | `bytes` (one of event) | | `stderr` | `bytes` (one of event) | | `exit` | [`ExecExit`](#execexit) (one of event) | ### ExecRequest | Field | Type | |---|---| | `session_id` | `string` | | `command` | `string` (optional) | | `argv` | repeated `string` | | `env` | `map` | | `workdir` | `string` (optional) | | `timeout_secs` | `uint64` (optional) | | `exec_id` | `string` (optional) | | `stdout_offset` | `uint64` (optional) | | `stderr_offset` | `uint64` (optional) | | `wake` | `bool` (optional) | ### ExecRusage | Field | Type | |---|---| | `wall_ms` | `uint64` | | `peak_rss_kb` | `uint64` (optional) | | `user_cpu_ms` | `uint64` (optional) | | `sys_cpu_ms` | `uint64` (optional) | ### ExecStarted | Field | Type | |---|---| | `exec_id` | `string` | ### GetArtifactRequest | Field | Type | |---|---| | `session_id` | `string` | | `artifact_id` | `string` | ### GetArtifactResponse | Field | Type | |---|---| | `metadata` | [`ArtifactMetadata`](#artifactmetadata) (one of msg) | | `chunk` | `bytes` (one of msg) | ### GetLogRequest | Field | Type | |---|---| | `session_id` | `string` | | `kind` | `string` (optional) | | `limit` | `int64` (optional) | | `tail` | `bool` (optional) | ### GetLogResponse | Field | Type | |---|---| | `session_id` | `string` | | `kind` | `string` | | `events` | repeated [`ConversationEntry`](#conversationentry) | ### GetSessionRequest | Field | Type | |---|---| | `session_id` | `string` | ### GetSessionResponse | Field | Type | |---|---| | `session` | [`Session`](#session) | ### InterruptRequest | Field | Type | |---|---| | `session_id` | `string` | | `source` | `string` | ### InterruptResponse | Field | Type | |---|---| | `session_id` | `string` | | `note` | `string` | ### ListCheckpointsRequest | Field | Type | |---|---| | `session_id` | `string` | ### ListCheckpointsResponse | Field | Type | |---|---| | `session_id` | `string` | | `checkpoints` | repeated [`CheckpointSummary`](#checkpointsummary) | ### ListSessionEventsRequest | Field | Type | |---|---| | `session_id` | `string` | | `after_idx` | `int64` (optional) | | `limit` | `int64` (optional) | | `before_idx` | `int64` (optional) | | `kinds` | repeated `string` | | `tool_names` | repeated `string` | ### ListSessionEventsResponse | Field | Type | |---|---| | `events` | repeated [`SessionEvent`](#sessionevent) | | `next_after_idx` | `int64` | ### ListSessionsRequest No fields. ### ListSessionsResponse | Field | Type | |---|---| | `sessions` | repeated [`SessionListItem`](#sessionlistitem) | ### OAuthCredentialBinding | Field | Type | |---|---| | `subject` | `OAuthSubject` | | `provider` | `string` | ### ReadFileMetadata | Field | Type | |---|---| | `path` | `string` | | `size_bytes` | `uint64` | | `sha256` | `string` | | `file_name` | `string` | ### ReadFileRequest | Field | Type | |---|---| | `session_id` | `string` | | `path` | `string` | ### ReadFileResponse | Field | Type | |---|---| | `metadata` | [`ReadFileMetadata`](#readfilemetadata) (one of frame) | | `chunk` | `bytes` (one of frame) | ### ResumeRequest | Field | Type | |---|---| | `session_id` | `string` | ### ResumeResponse | Field | Type | |---|---| | `session_id` | `string` | | `snapshot_id` | `string` (optional) | | `size_bytes` | `uint64` (optional) | | `note` | `string` | ### SendPromptRequest | Field | Type | |---|---| | `session_id` | `string` | | `text` | `string` | | `prompt_id` | `string` | | `harness_mode` | `string` (optional) | ### SendPromptResponse | Field | Type | |---|---| | `session_id` | `string` | | `note` | `string` | ### Session | Field | Type | |---|---| | `id` | `string` | | `status` | `string` | | `host_id` | `string` (optional) | | `sandbox_id` | `string` (optional) | | `image` | `string` | | `mode` | `string` | | `created_at` | `string` | | `last_active_at` | `string` | | `suggested_title` | `string` (optional) | | `last_event_at` | `string` (optional) | ### SessionEvent | Field | Type | |---|---| | `idx` | `int64` (optional) | | `kind` | `string` | | `payload_json` | `string` | ### SessionListItem | Field | Type | |---|---| | `session` | [`Session`](#session) | | `owner_email` | `string` (optional) | | `owner_name` | `string` (optional) | | `owner_kind` | `string` (optional) | ### SnapshotRequest | Field | Type | |---|---| | `session_id` | `string` | ### SnapshotResponse | Field | Type | |---|---| | `session_id` | `string` | | `snapshot_id` | `string` (optional) | | `size_bytes` | `uint64` (optional) | | `note` | `string` | ### StreamEventsRequest | Field | Type | |---|---| | `session_id` | `string` | | `since` | `int64` (optional) | | `durable_only` | `bool` | ### WriteFileMetadata | Field | Type | |---|---| | `session_id` | `string` | | `path` | `string` | | `size_bytes` | `uint64` | | `sha256` | `string` | | `mode` | `uint32` (optional) | ### WriteFileRequest | Field | Type | |---|---| | `metadata` | [`WriteFileMetadata`](#writefilemetadata) (one of frame) | | `chunk` | `bytes` (one of frame) | ### WriteFileResponse | Field | Type | |---|---| | `path` | `string` | | `size_bytes` | `uint64` | | `sha256` | `string` | --- # ShellRelayService > The ShellRelayService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/shell-relay/ Generated from [`session.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/session.proto). Every method is `POST /rpc/engram.app.v1.ShellRelayService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `Relay` | [`RelayShellRequest`](#relayshellrequest) (stream) | [`RelayShellResponse`](#relayshellresponse) (stream) | ## Messages ### RelayShellRequest | Field | Type | |---|---| | `open` | [`ShellOpen`](#shellopen) (one of frame) | | `text` | `string` (one of frame) | | `binary` | `bytes` (one of frame) | | `ping` | `bytes` (one of frame) | | `pong` | `bytes` (one of frame) | | `close` | [`ShellClose`](#shellclose) (one of frame) | ### RelayShellResponse | Field | Type | |---|---| | `text` | `string` (one of frame) | | `binary` | `bytes` (one of frame) | | `ping` | `bytes` (one of frame) | | `pong` | `bytes` (one of frame) | | `close` | [`ShellClose`](#shellclose) (one of frame) | ### ShellClose | Field | Type | |---|---| | `code` | `uint32` | | `reason` | `string` | ### ShellOpen | Field | Type | |---|---| | `session_id` | `string` | --- # TaskService > The TaskService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/task/ Generated from [`task.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/task.proto). Every method is `POST /rpc/engram.app.v1.TaskService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `CreateTask` | [`CreateTaskRequest`](#createtaskrequest) | [`CreateTaskResponse`](#createtaskresponse) | | `ListTasks` | [`ListTasksRequest`](#listtasksrequest) | [`ListTasksResponse`](#listtasksresponse) | | `GetTask` | [`GetTaskRequest`](#gettaskrequest) | [`GetTaskResponse`](#gettaskresponse) | | `DeleteTask` | [`DeleteTaskRequest`](#deletetaskrequest) | [`DeleteTaskResponse`](#deletetaskresponse) | | `UpdateTask` | [`UpdateTaskRequest`](#updatetaskrequest) | [`UpdateTaskResponse`](#updatetaskresponse) | ## Messages ### CreateTaskRequest | Field | Type | |---|---| | `type` | `string` | | `prompt` | `string` (optional) | | `title` | `string` (optional) | | `profile_id` | `string` | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `effort` | `string` (optional) | | `harness_mode` | `string` (optional) | | `defer_initial_prompt` | `bool` | | `model_router` | `string` (optional) | ### CreateTaskResponse | Field | Type | |---|---| | `task` | [`Task`](#task) | ### DeleteTaskRequest | Field | Type | |---|---| | `task_id` | `string` | ### DeleteTaskResponse No fields. ### GetTaskRequest | Field | Type | |---|---| | `task_id` | `string` | | `session_id` | `string` | ### GetTaskResponse | Field | Type | |---|---| | `task` | [`Task`](#task) | ### ListTasksRequest | Field | Type | |---|---| | `scope` | `string` | | `search` | `string` | | `created_by_user_ids` | repeated `string` | | `states` | repeated `string` | | `page` | `int32` | | `page_size` | `int32` | | `order` | `string` | ### ListTasksResponse | Field | Type | |---|---| | `tasks` | repeated [`Task`](#task) | | `total_count` | `int32` | | `session_state_unavailable` | `bool` | ### Task | Field | Type | |---|---| | `id` | `string` | | `type` | `string` | | `title` | `string` (optional) | | `status` | `string` | | `created_by_user_id` | `string` (optional) | | `source_json` | `string` | | `sessions` | repeated [`TaskSessionRef`](#tasksessionref) | | `created_at` | `string` | | `title_is_custom` | `bool` | | `created_by` | `User` (optional) | | `harness` | `string` (optional) | | `model` | `string` (optional) | | `effort` | `string` (optional) | | `parent_task_id` | `string` (optional) | | `root_task_id` | `string` (optional) | | `local_task_name` | `string` (optional) | | `canonical_task_name` | `string` (optional) | | `spawning_session_id` | `string` (optional) | | `descendants` | repeated [`Task`](#task) | | `model_router` | `string` (optional) | ### TaskSessionRef | Field | Type | |---|---| | `session_id` | `string` | | `role` | `string` (optional) | | `session` | `Session` (optional) | | `profile` | `ProfileSnapshot` (optional) | ### UpdateTaskRequest | Field | Type | |---|---| | `task_id` | `string` | | `title` | `string` (optional) | ### UpdateTaskResponse | Field | Type | |---|---| | `task` | [`Task`](#task) | --- # WebhookRegistrationService > The WebhookRegistrationService methods and their request and response messages. Source: https://engramsfactory.com/docs/api/webhook-registration/ Generated from [`automation.proto`](https://github.com/cortexapps/engrams/blob/main/crates/engram-protocol/proto/engram/app/v1/automation.proto). Every method is `POST /rpc/engram.app.v1.WebhookRegistrationService/` with a JSON or protobuf body and an `x-api-key` header. ## Methods | Method | Request | Response | |---|---|---| | `CreateWebhookRegistration` | [`CreateWebhookRegistrationRequest`](#createwebhookregistrationrequest) | [`CreateWebhookRegistrationResponse`](#createwebhookregistrationresponse) | | `ListWebhookRegistrations` | [`ListWebhookRegistrationsRequest`](#listwebhookregistrationsrequest) | [`ListWebhookRegistrationsResponse`](#listwebhookregistrationsresponse) | | `DeleteWebhookRegistration` | [`DeleteWebhookRegistrationRequest`](#deletewebhookregistrationrequest) | [`DeleteWebhookRegistrationResponse`](#deletewebhookregistrationresponse) | | `ListWebhookEvents` | [`ListWebhookEventsRequest`](#listwebhookeventsrequest) | [`ListWebhookEventsResponse`](#listwebhookeventsresponse) | ## Messages ### CreateWebhookRegistrationRequest | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `verification_scheme` | `string` | | `provider_hint` | `string` (optional) | ### CreateWebhookRegistrationResponse | Field | Type | |---|---| | `registration` | [`WebhookRegistration`](#webhookregistration) | | `secret` | `string` | ### DeleteWebhookRegistrationRequest | Field | Type | |---|---| | `id` | `string` | ### DeleteWebhookRegistrationResponse | Field | Type | |---|---| | `deleted` | `bool` | ### ListWebhookEventsRequest | Field | Type | |---|---| | `registration_id` | `string` | ### ListWebhookEventsResponse | Field | Type | |---|---| | `events` | repeated [`WebhookEvent`](#webhookevent) | | `variables` | repeated [`WebhookVariable`](#webhookvariable) | ### ListWebhookRegistrationsRequest No fields. ### ListWebhookRegistrationsResponse | Field | Type | |---|---| | `registrations` | repeated [`WebhookRegistration`](#webhookregistration) | ### WebhookEvent | Field | Type | |---|---| | `key` | `string` | | `display_name` | `string` | | `observed` | `bool` | ### WebhookRegistration | Field | Type | |---|---| | `id` | `string` | | `name` | `string` | | `verification_scheme` | `string` | | `provider_hint` | `string` (optional) | | `created_by_user_id` | `string` (optional) | | `created_at` | `string` | | `updated_at` | `string` | | `disabled_reason` | `string` (optional) | ### WebhookVariable | Field | Type | |---|---| | `path` | `string` | | `alias` | `string` | --- # Developing engrams > The repository's layout, the toolchain, the dev stack, and the gates a change has to pass. Source: https://engramsfactory.com/docs/contributing/development/ engrams is one repository with a Rust workspace at the root and two TypeScript projects beside it. | Path | What it is | Tooling | |---|---|---| | `crates/` | The Rust workspace: the coordinator, the host agent, the in-guest daemon, the sandbox backends, the storage and cloud backends, the harness adapters, the `engrams` CLI | cargo | | `orchestrator/` | The product API and integrations, on Bun and Hono | bun | | `web/` | The dashboard, a React app | pnpm | | `site/` | This site, Astro and Starlight | pnpm | | `deploy/` | Helm charts, Terraform, the demo image, the harness descriptors | | | `docs/` | Design notes and runbooks for people working on engrams | | `AGENTS.md` at the root is the working guide for the repository: the commands, the test lanes, and the conventions. Read it before a first change; this page is the short version. ## Toolchain `nix develop` gives you everything pinned: Rust, `just`, Tilt, nextest, the protobuf compiler, Node and pnpm, Bun, and the musl cross-compilers for the guest binaries. The same hashes work on macOS and Linux. Without Nix, the [local quickstart](https://engramsfactory.com/docs/getting-started/local-quickstart/) lists what to install by hand. ## The dev stack `just dev` runs the whole thing under Tilt with the backend picked for your machine. Git worktrees share one dev identity: the master key and the baked bundles live with the primary checkout, so a worktree never re-bakes and never breaks a sealed key. `just bootstrap` and `just pull-kernel` are one-time. The inner loop for Rust is `cargo check -p ` and `cargo nextest run -p `; workspace-wide cargo mid-edit queues behind rust-analyzer. `just check` is the full Rust gate, `cargo fmt --check`, `cargo clippy -D warnings`, the dependency-hash check, and every test, and it runs once before a pull request that touches Rust. Do not run it for a change that only touches docs, the web app, or the orchestrator. ## The gates a change has to pass Use the smallest gate that covers what you changed. - **Docs only:** `git diff --check`. - **Site only:** from `site/`, `pnpm build`, which runs the leak lint, `astro check`, and the build. - **Web only:** from `web/`, `pnpm format:check`, `pnpm lint`, the focused `pnpm test` targets, and `pnpm build`. - **Orchestrator only:** from `orchestrator/`, `bun run typecheck` and the focused `bun test` targets. - **Rust or shared backend:** per-crate checks and tests while editing, then `just check` once before the pull request. Linux-only code is invisible to clippy on a Mac, so cross-check it with `cargo clippy --target aarch64-unknown-linux-musl -p --all-targets`. CI is path-gated: only the lanes a change can affect run, and one aggregate check, `CI Gate`, is what a pull request needs green. Tests that need a Linux host with KVM run on KVM runners and must be listed in the workflow to run at all; a new test that CI never invokes is a bug. ## Conventions One logical change per commit. Commit messages and pull request descriptions carry the reasoning; a design record is for a new crate, a new trait boundary, a schema or wire change, or a decision later work has to build on, and nothing smaller. Prefer a clean break over a compatibility shim: image rebuilds and schema changes are acceptable, deprecated stubs are not. Never silence the type checker or a lint to make an error go away; a mismatch is the compiler telling you the shapes do not line up. In the coordinator and Postgres code, time and randomness are injected: read the clock and the entropy source from the service context rather than calling the system, so the same code runs under the deterministic simulator. Every background driver keeps its logic in a `run_once` step that tests drive directly, with the timer loop as a thin wrapper around it. When a test fails, read the production code before you touch the assertion; a failing test is usually a real bug. A flake gets fixed the day it is noticed. ## Filing issues Issues and pull requests are on [GitHub](https://github.com/cortexapps/engrams). For a bug, include the backend (Firecracker, Apple Virtualization, or process), the commit, and the coordinator and host-agent log lines around the failure; for a session that misbehaved, the session id and the event log from `engrams session logs` are the most useful thing you can attach.