Initial commit of Agent Substrate

This is the initial release of the Agent Substrate.

Agent substrate is a system built on top of Kubernetes which manages agent-like
workloads to achieve higher scale and efficiency than Kubernetes alone can
offer, with lower latency.  It builds on top of Kubernetes features like
Pods and Pod autoscaling, but takes the Kubernetes control-plane out of the
critical path to achieve lower latency.

It can run on any Kubernetes cluster and does not inhibit “regular” use of
Kubernetes in any way. Kubernetes provides the infrastructure provisioning and
management for all types of workloads, while Agent Substrate provides
agent-specific scheduling and control.

At its core, Agent Substrate maps a larger set of “actors” (applications such
as agents) onto a smaller set of ready “workers” (Kubernetes Pods), relying on
the fact that agent-like applications tend to be idle most of the time to
achieve heavy multiplexing.  It provides functionality to manage an actor’s
lifecycle (e.g. create/destroy, suspend/resume), to assign actors to workers in real
time, and to route incoming traffic to them.

Agent Substrate is intended to be a low-opinion system.  The workloads it
manages don't have to be literal AI agents, but those are the best example of
the kind of applications it is designed for.  It is not an SDK for building
agents, but rather a system for running them at scale.

Agent Substrate is currently in VERY early development.  It is not ready for
production use, and the APIs are almost guaranteed to change.  We are not
making any guarantees about backward compatibility at this stage, and
everything in this project may be changed.

Co-authored-by: Alex Bulankou <alexbu@google.com>
Co-authored-by: Benjamin Elder <bentheelder@google.com>
Co-authored-by: Bowei Du <bowei@google.com>
Co-authored-by: Dmitry Berkovich <dberkov@google.com>
Co-authored-by: Fabricio Voznika <fvoznika@google.com>
Co-authored-by: Francisco Cabrera <fclieutier@google.com>
Co-authored-by: Haven Xia <haoyuxia@google.com>
Co-authored-by: Julian Gutierrez Oschmann <juliangut@google.com>
Co-authored-by: Kevin Steuer <ksteuer@google.com>
Co-authored-by: Max Smythe <smythe@google.com>
Co-authored-by: Maya Wang <mymaya@google.com>
Co-authored-by: Michael Taufen <mtaufen@google.com>
Co-authored-by: Shruti Nair <shrutinair@google.com>
Co-authored-by: Taahir Ahmed <taahm@google.com>
Co-authored-by: Tim Hockin <thockin@google.com>
Co-authored-by: Zoe Zhao <zoezhao@google.com>

Author: 17 people

.agents/skills/agents-md/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: agents-md
+description: Generates or updates an AGENTS.md file
+---
+
+Generate or update AGENTS.md files in key folders of the project.
+Ensure the target AGENTS.md file accurately reflects the current status of the code.
+
+## Key Requirements
+
+There must always be an AGENTS.md file in the project root.
+The AGENTS.md file at the root of the project may include the following sections:
+
+- Project overview
+- Build and test commands
+- Code style guidelines
+- Testing instructions
+- Security considerations
+
+AGENTS.md files in subfolders may be even more concise and specific to those subfolders. 
+
+## Maximize AGENTS.md Performance
+
+To maximize agent performance and token efficiency, adhere to the following:
+
+### Progressive Disclosure
+
+Each AGENTS.md should be short. Approx. 100-150 lines total.
+Link to a handful of relevant, focused reference documents in the same repo, as needed.
+
+### Modularity
+
+While only one AGENTS.md is allowed per folder, you can create an AGENTS.md file in any folder.
+Rather than putting everything in the root AGENTS.md, move highly specific advice to AGENTS.md in the most relevant folders of the project.
+
+### References
+
+When documentation that would have helped you is missing, add references in the docs/ folder found at the project root. When these get out of date, update them.
+
+### Workflows
+
+When references describe workflows, the tasks should be described as numbered steps. For example:
+
+1. Get the beep from the boop.
+2. Then bop it.
+
+### Decisions
+
+When there are multiple ways of doing something in the codebase, use a decision table like the following:
+
+| Question | Boop | Bop |
+| :---- | :---- | :---- |
+| Is foo a bar baz? | ✅ |  |
+| Is foo a quux? |  | ✅ |
+
+### Real Code Examples
+
+If you think they are particularly good examples, include snippets from actual code in the repo, up to approx. 10 lines in length.
+These should only be the most relevant examples and representative of patterns that would be good to repeat in future code.
+Their purpose is to improve code reuse by agents, rather than each agent reinventing the wheel.
+
+### Domain Specific Rules
+
+If you think it would help, you can include a few simple domain specific rules.
+Not too many, or agents will get stuck trying to handle too many rules.
+A general example of a domain specific rule is "Use a finance-specific numeric type for any financial calculations."
+
+### Don't vs. Do
+
+When adding warnings against doing something, also make a concrete suggestion for the correct approach.
+"Don't do X, do Y instead."

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Create a report to help us improve
+
+---
+
+## Expected Behavior
+
+
+## Actual Behavior
+
+
+## Steps to Reproduce the Problem
+
+1.
+1.
+1.
+
+## Specifications
+
+- Version:
+- Platform:

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,6 @@
+Fixes #<issue_number_goes_here>
+
+> It's a good idea to open an issue first for discussion.
+
+- [ ] Tests pass
+- [ ] Appropriate changes to documentation are included in the PR

.github/workflows/pr-workflow.yaml

@@ -0,0 +1,52 @@
+#  Copyright 2026 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+name: pr-workflow
+on:
+  pull_request:
+jobs:
+  run-tests:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Setup Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.26
+    - run: go vet -v ./...
+    - run: go test -v ./...
+    - name: verify
+      run: hack/verify-all.sh
+  e2e-test:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Setup Go
+      uses: actions/setup-go@v5
+      with:
+        go-version: 1.26
+    - name: Install kind
+      run: go install sigs.k8s.io/kind@v0.31.0
+    - name: Create cluster
+      run: hack/create-kind-cluster.sh
+    - name: Install Agent Substrate
+      run: hack/install-ate-kind.sh --deploy-ate-system
+    - name: Wait For Ready
+      run: kubectl wait pod --all --for=condition=Ready --namespace=ate-system --timeout=300s
+    - name: Deploy Counter Demo
+      run: hack/install-ate-kind.sh --deploy-demo-counter
+    - name: Run E2E tests
+      run: KO_DOCKER_REPO=localhost:5001 BUCKET_NAME=ate-snapshots KUBECTL_CONTEXT=kind-kind hack/run-e2e.sh -v -args -no-color

.gitignore

@@ -0,0 +1,15 @@
+# Binaries
+/ateapi
+/substratectl
+/kubectl-ate
+/atelet
+/bin/
+
+# Python
+venv/
+.venv/
+__pycache__/
+*.pyc
+
+# Local environment variables
+.ate-dev-env.sh

.ko.yaml

@@ -0,0 +1,19 @@
+#  Copyright 2026 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+defaultBaseImage: gcr.io/distroless/static-debian11
+
+baseImageOverrides:
+  github.com/agent-substrate/substrate/demos/sandbox: alpine
+  github.com/agent-substrate/substrate/demos/agent-secret: alpine

AGENTS.md

@@ -0,0 +1,49 @@
+# Agent Substrate
+
+## Project Overview
+
+Agent Substrate is a system built on top of Kubernetes which manages agent-like workloads to achieve higher scale and efficiency than Kubernetes alone can offer, with lower latency.
+It takes the Kubernetes control-plane out of the critical path to achieve lower latency by mapping a larger set of “actors” (applications such as agents) onto a smaller set of ready “workers” (Kubernetes Pods).
+Agent Substrate relies on the fact that agent-like applications tend to be idle most of the time to achieve heavy multiplexing.
+
+For development, it's recommended to read the `README.md` and `CONTRIBUTING.md` in the root folder.
+See `hack/install-ate.sh` and `cmd/setup` for provisioning and deploying clusters and GCP resources.
+
+## Build and Test Commands
+
+Agent Substrate uses a `Makefile` for its build and test tasks.
+
+### Building
+- **Binaries**: `make build` (builds images and `kubectl-ate`) or `make build-atectl`
+- **Images**: `make build-images` (uses ko to build container images)
+- **Demos**: `make build-demos`
+
+### Testing and Verification
+- **Run Unit Tests**: `make test`
+- **Run E2E Tests**: `make e2e` (Requires GCP cluster setup and built images)
+- **Run Linters and Verifiers**: `make verify` (Includes `go vet` and checks for formatting, boilerplate headers, licenses, and go modules)
+
+## Code Style Guidelines
+
+- **Go Formatting**: Code must be formatted with `gofmt`. Run `make fmt` to automatically format all files before submitting changes.
+- **Copyright Headers**: All files must contain appropriate copyright and license headers. See templates in `hack/boilerplate/`.
+- **Modularity**: Submit small, focused Pull Requests that touch a limited part of the codebase for easier reviews and rebasing.
+- **Go Modules**: Ensure `go.mod` is clean. Run `go mod tidy` if adding or removing dependencies.
+
+## Testing Instructions
+
+1. Write tests for all new code. We will not merge code that lacks tests.
+2. Ensure changes do not break existing tests.
+3. Run `make verify` locally before requesting a code review to catch common issues like missed copyright headers or formatting drift.
+4. For end-to-end tests involving the actual infrastructure, ensure you have a running cluster (setup via `hack/ate-dev-env.sh.example` and `go run ./cmd/setup --all`).
+
+## Security Considerations
+
+The security story for Substrate is very early and many features are missing.
+However! Take care to respect security best practices when writing code in order to improve Substrate's security over time.
+The following is what Substrate currently offers.
+Keep this up to date when updating AGENTS.md.
+
+- **Workload Isolation**: The project uses `gVisor` (`runsc`) for sandboxing and security isolation of workloads on pods. A temporary gVisor patch might be required (check the README instructions).
+
+For future plans for security, reference `docs/roadmap.md`.

COLLABORATING.md

@@ -0,0 +1,88 @@
+# Collaborating on Agent Substrate
+
+This project is intended to be "very" open.  Especially in the early stages, we
+do not have a lot of infrastructure in place to manage the repository, so we are
+relying on each other to be good collaborators.  To that end, here are some
+guidelines for collaborating on this project.
+
+## Code of conduct
+
+Please read and internalize our [code of conduct](code-of-conduct.md).  We want
+this to be a welcoming and inclusive community, and we expect everyone to
+adhere to the code of conduct at all times.  If you see someone violating the
+code of conduct, please report it to the maintainers immediately.  We take all
+reports seriously and will take appropriate action to address any issues.
+
+Open, direct, honest communication is encouraged, but always be respectful and
+professional.
+
+## World-wide community
+
+This project is not limited to one timezone, and we hope to have collaborators
+from all over the world.  Please be mindful of this at all times.
+
+This project uses English as the primary language for communication.  If
+English is not your first language, please do not hesitate to ask for
+clarification if you do not understand something.
+
+## Written communication
+
+Prefer written communication (PRs, issues, mailing-list) over verbal
+communication (e.g. video calls).  This allows for people who might not have
+been in the conversation to understand why a decision was made the way it was.
+
+When writing, please strive for clarity and conciseness.  Not everyone in the
+community will have the same proficiency in English, so please be mindful of
+that when writing.
+
+## Always use Pull Requests
+
+Do not push directly to the main branch.  Always use pull requests to propose
+changes to the codebase.  This allows for code review and discussion before
+changes are merged, which helps maintain the quality of the codebase and
+fosters collaboration.
+
+### Merging PRs
+
+PRs should be merged by the reviewer of a PR, not the author.
+
+### Using AI
+
+Using AI tools to assist with coding is allowed, but please be transparent
+about it. Regardless of how a PR was created, the _human_ who is offering the
+PR is responsible for the content of the PR, and they should be able to explain
+the code and answer questions about it.  Please be respectful of your
+reviewers' time and do not offer PRs that you cannot explain or defend. If you
+use an AI tool to generate a significant fraction of a PR, please note that in
+the PR comment.
+
+## Code reviews
+
+We want to move quickly, but we need to balance that with quality and
+maintainability.  Code reviews are an important part of that process.  All PRs
+should be reviewed BEFORE they are merged.
+
+### Code reviews across companies
+
+As this community grows, we expect to see collaborators from different
+companies.  Whenever possible, we want to encourage code reviews across
+companies.  This helps foster collaboration and knowledge sharing across the
+community, and it helps prevent silos from forming within the community.
+
+## Working hours
+
+We want to move quickly, but we also want to be respectful of each other's
+time.  For the sake of consistency, this project's "working hours" are Monday
+to Friday, 8am to 8pm, US Pacific Time (GMT-7). Please avoid merging PRs late
+at night or on weekends, unless it is an urgent fix.  This allows for people to
+have a better work-life balance and prevents burnout.  If you do need to merge
+something outside of normal working hours, please try to give a heads up to the
+rest of the community so that they are aware.
+
+## Ownership
+
+As this project grows, we hope to see more and more collaborators.  We want to
+encourage a culture of ownership, where people demonstrate ownership of various
+parts of the codebase - a file, a package, a subsystem.  We should all try to
+respect each other's ownership, but we must not become territorial.  Everyone
+should be ready to track an issue or feature across the code as needed.

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# How to Contribute
+
+We would love to accept your patches and contributions to this project. Before
+you spend a lot of time on a contribution, please review the following
+guidelines.
+
+## Before you begin
+
+### Sign our Contributor License Agreement
+
+Contributions to this project must be accompanied by a
+[Contributor License Agreement](https://cla.developers.google.com/about) (CLA).
+You (or your employer) retain the copyright to your contribution; this simply
+gives us permission to use and redistribute your contributions as part of the
+project.
+
+If you or your current employer have already signed the Google CLA (even if it
+was for a different project), you probably don't need to do it again.
+
+Visit <https://cla.developers.google.com/> to see your current agreements or to
+sign a new one.
+
+### Review our Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google/conduct/).
+
+## Contribution process
+
+This is a very new project, so we are still working out exactly how it is going
+to be developed. For now, we are focused on iterating quickly to find the right
+design and architecture. This has implications for contributors:
+
+1) Things are moving quickly, so PRs may need to be rebased or updated
+frequently. Small PRs that are focused on a single issue or feature are easier
+to review and update than large PRs that touch many different parts of the
+codebase.
+
+2) While we welcome new contributors, we are really focused on the minimal
+capabilities needed to make this project useful. Before you start a new
+contribution, please discuss it with us first (if there is an issue open,
+comment there and if not, open one). We want to make sure that your work is
+aligned with our near-term goals for the project and that we are not
+duplicating work that is already in flight.
+
+3) PRs which are not aligned with our near-term goals may be closed without
+extensive review. We are not trying to be discouraging, but we need to make
+sure that we are focused on the most important work.
+
+### Code Reviews
+
+All submissions, including submissions by project members, require review. We
+use [GitHub pull requests](https://docs.github.com/articles/about-pull-requests)
+for this purpose.
+
+All code changes should be accompanied by tests. We will not merge code that
+does not have tests, and we will not merge code that causes tests to fail.
+
+### Copyright Headers
+
+Every file containing source code must include copyright and license
+information. This includes any JS/CSS files that you might be serving out to
+browsers. (This is to help well-intentioned people avoid accidental copying
+that doesn't comply with the license.)
+
+Our standard headers for various filetypes can be found in
+[./hack/boilerplate](./hack/boilerplate/).