# 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.

Every docs page is plain Markdown at its URL with `.md` in place of the trailing slash. The links below point at the Markdown. All the docs in one file are at https://engramsfactory.com/llms-full.txt.

If you are a coding agent asked to install engrams, start with https://engramsfactory.com/docs/getting-started/install-with-an-agent.md.

## Overview

- [engrams](https://engramsfactory.com/): The landing page: what engrams does and who it is for.
- [engrams vs Devin, Factory, and other options](https://engramsfactory.com/compare/): How engrams compares to hosted coding agents and sandbox products, and when to pick each.
- [Architecture](https://engramsfactory.com/architecture/): The processes, the external services, and the storage design.
- [Source code](https://github.com/cortexapps/engrams): The repository on GitHub.

## Getting started

- [What is engrams](https://engramsfactory.com/docs/getting-started/overview.md): Sessions, tasks, profiles, images, harnesses, and hosts, and what happens to a session over its life.
- [Install engrams with a coding agent](https://engramsfactory.com/docs/getting-started/install-with-an-agent.md): Exact steps, checks, and stop conditions for a coding agent that installs engrams on one machine.
- [Run engrams locally](https://engramsfactory.com/docs/getting-started/local-quickstart.md): Start the whole stack on one machine and enable the demo image.
- [Your first session](https://engramsfactory.com/docs/getting-started/first-session.md): Start an agent from the CLI, watch it work, and see it snapshot and resume.
- [FAQ](https://engramsfactory.com/docs/getting-started/faq.md): Short answers to the questions people ask before they run engrams.
- [Glossary](https://engramsfactory.com/docs/getting-started/glossary.md): The words engrams uses, each with the page that owns it.

## Platform

- [Sessions](https://engramsfactory.com/docs/platform/sessions.md): A person starts an agent from the dashboard, Slack, or the CLI; engrams runs their harness in a microVM and keeps the record.
- [Automations](https://engramsfactory.com/docs/platform/automations.md): An agent with ways in, with durable runs, typed inputs, and a visual builder.
- [Pull request review](https://engramsfactory.com/docs/platform/reviews.md): A finder and a verifier review each pull request on the repositories you enroll, and post the confirmed findings as one GitHub review.
- [Slack threads](https://engramsfactory.com/docs/platform/slack-threads.md): Mention the bot in a channel and a session opens for that thread, as the person who asked, with their credentials.

## Concepts

- [Architecture](https://engramsfactory.com/docs/concepts/architecture.md): The four processes, what each owns, and how they talk.
- [Storage and snapshots](https://engramsfactory.com/docs/concepts/storage-and-snapshots.md): Content-addressed chunks, versioned manifests, and the three places engrams gets copy-on-write for free.
- [Sandbox backends](https://engramsfactory.com/docs/concepts/sandbox-backends.md): Firecracker for production, Apple Virtualization for Mac development, subprocesses for iterating.
- [Images and harnesses](https://engramsfactory.com/docs/concepts/images-and-harnesses.md): A session is a plain OCI image plus an agent runtime the host mounts at boot.
- [Egress and secret brokering](https://engramsfactory.com/docs/concepts/egress-and-brokering.md): 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.

## Guides

- [Production deployment](https://engramsfactory.com/docs/guides/deploy-overview.md): One Kubernetes cluster, two Helm releases, and the node-pool rules that are not negotiable.
- [Deploy on GCP](https://engramsfactory.com/docs/guides/deploy-gcp.md): A fresh GCP project to a working engrams deployment on GKE, command by command.
- [Deploy on AWS](https://engramsfactory.com/docs/guides/deploy-aws.md): A fresh AWS account to a working engrams deployment on EKS, command by command.
- [Authoring a warm hook](https://engramsfactory.com/docs/guides/warm-hooks.md): Run a command once at enable time so every session starts with caches filled and daemons running.
- [Upgrade engrams](https://engramsfactory.com/docs/guides/upgrade.md): Move a deployment from one release to the next, and what happens to running sessions while you do.
- [Session telemetry](https://engramsfactory.com/docs/guides/telemetry.md): Export every session's turns, model calls, and tool calls as OpenTelemetry spans to Langfuse or any collector.
- [Google Cloud connections](https://engramsfactory.com/docs/guides/google-cloud-connections.md): Give sessions short-lived Google Cloud credentials through Workload Identity Federation, with no keys anywhere.
- [Bring your own harness](https://engramsfactory.com/docs/guides/custom-harness.md): Run an agent runtime that is not Claude Code or Codex inside engrams sessions.
- [Model routers](https://engramsfactory.com/docs/guides/model-routers.md): Serve models to any harness through OpenRouter, with a per-model policy for who may launch them.
- [Session apps](https://engramsfactory.com/docs/guides/session-apps.md): Give a service running inside a session a stable URL that people and sibling apps can reach, behind the login wall.
- [Connect Slack](https://engramsfactory.com/docs/guides/connect-slack.md): Create the Slack app, connect it, and let people start sessions by mentioning it in a thread.
- [Connect GitHub](https://engramsfactory.com/docs/guides/connect-github.md): Install a GitHub App so sessions get short-lived, scoped tokens and pull requests get reviewed.
- [Connect Linear](https://engramsfactory.com/docs/guides/connect-linear.md): Create the Linear OAuth application, connect it, and trigger automations from issues.
- [Connect Cortex](https://engramsfactory.com/docs/guides/connect-cortex.md): Pick the Cortex API host, add a workspace API key, and give sessions the catalog.
- [Connect Vanta](https://engramsfactory.com/docs/guides/connect-vanta.md): Create Vanta API credentials, connect them, and let sessions run your compliance program.
- [Connect Rippling](https://engramsfactory.com/docs/guides/connect-rippling.md): Create a Rippling API token, connect it, and give sessions your org chart and HR records.
- [Connect Google Workspace](https://engramsfactory.com/docs/guides/connect-google-workspace.md): Give sessions your Google Workspace directory as the organization, and each member their own Gmail, Calendar, and Drive.

## Reference

- [CLI](https://engramsfactory.com/docs/reference/cli.md): The engrams command, its authentication model, and every subcommand.
- [API overview](https://engramsfactory.com/docs/reference/api.md): The Connect RPC surface the dashboard and CLI use, and the few routes that live outside it.
- [Configuration](https://engramsfactory.com/docs/reference/configuration.md): The environment variables the coordinator and the host agent run on, and how secrets, the master key, and the egress CA reach them.
- [Helm chart: engram](https://engramsfactory.com/docs/reference/helm-engram.md): The control-plane chart, what it deploys and does not, and the values that matter.
- [Helm chart: engram-host-fleet](https://engramsfactory.com/docs/reference/helm-engram-host-fleet.md): The Firecracker host fleet as a DaemonSet, the operator that rolls and scales it, and the values behind them.
- [Terraform: GCP](https://engramsfactory.com/docs/reference/terraform-gcp.md): The composable modules and the one-apply quickstart for GKE.
- [Terraform: AWS](https://engramsfactory.com/docs/reference/terraform-aws.md): The composable modules and the one-apply quickstart for EKS.

## Optional

- [API reference](https://engramsfactory.com/docs/api.md): Every Connect RPC service, generated from the proto files.
- [ApiKeyService](https://engramsfactory.com/docs/api/api-key.md): The ApiKeyService methods and their request and response messages.
- [ArtifactService](https://engramsfactory.com/docs/api/artifact.md): The ArtifactService methods and their request and response messages.
- [AutomationRunService](https://engramsfactory.com/docs/api/automation-run.md): The AutomationRunService methods and their request and response messages.
- [AutomationService](https://engramsfactory.com/docs/api/automation.md): The AutomationService methods and their request and response messages.
- [FleetService](https://engramsfactory.com/docs/api/fleet.md): The FleetService methods and their request and response messages.
- [HarnessCatalogService](https://engramsfactory.com/docs/api/harness-catalog.md): The HarnessCatalogService methods and their request and response messages.
- [ImageService](https://engramsfactory.com/docs/api/image.md): The ImageService methods and their request and response messages.
- [IntegrationOpService](https://engramsfactory.com/docs/api/integration-op.md): The IntegrationOpService methods and their request and response messages.
- [IntegrationService](https://engramsfactory.com/docs/api/integration.md): The IntegrationService methods and their request and response messages.
- [MintService](https://engramsfactory.com/docs/api/mint.md): The MintService methods and their request and response messages.
- [ModelRouterService](https://engramsfactory.com/docs/api/model-router.md): The ModelRouterService methods and their request and response messages.
- [MountCatalogService](https://engramsfactory.com/docs/api/mount-catalog.md): The MountCatalogService methods and their request and response messages.
- [OAuthCredentialService](https://engramsfactory.com/docs/api/oauth-credential.md): The OAuthCredentialService methods and their request and response messages.
- [OrgSecretService](https://engramsfactory.com/docs/api/org-secret.md): The OrgSecretService methods and their request and response messages.
- [PapercutService](https://engramsfactory.com/docs/api/papercut.md): The PapercutService methods and their request and response messages.
- [PortRelayService](https://engramsfactory.com/docs/api/port-relay.md): The PortRelayService methods and their request and response messages.
- [ProfileService](https://engramsfactory.com/docs/api/profile.md): The ProfileService methods and their request and response messages.
- [PrRefService](https://engramsfactory.com/docs/api/pr-ref.md): The PrRefService methods and their request and response messages.
- [RetentionService](https://engramsfactory.com/docs/api/retention.md): The RetentionService methods and their request and response messages.
- [ReviewService](https://engramsfactory.com/docs/api/review.md): The ReviewService methods and their request and response messages.
- [SessionService](https://engramsfactory.com/docs/api/session.md): The SessionService methods and their request and response messages.
- [ShellRelayService](https://engramsfactory.com/docs/api/shell-relay.md): The ShellRelayService methods and their request and response messages.
- [TaskService](https://engramsfactory.com/docs/api/task.md): The TaskService methods and their request and response messages.
- [WebhookRegistrationService](https://engramsfactory.com/docs/api/webhook-registration.md): The WebhookRegistrationService methods and their request and response messages.

- [Developing engrams](https://engramsfactory.com/docs/contributing/development.md): The repository's layout, the toolchain, the dev stack, and the gates a change has to pass.
