steadmesh

Steadmesh

This platform turns an organisation declared in Terraform (culture, teams, seats, harnesses, memory, grants, message routes and channel bindings) into persistent agents running on Kubernetes. Each seat runs Claude Code, Codex or Pi on a model endpoint you choose. People message their personal representatives over Slack (or a terminal). Representatives keep context, delegate to other seats, and agents can track work in Linear.

Steadmesh is early-stage. Check releases for published artifacts. This source tree and its quickstart target v0.7.0; wait for that release's publishing workflow to finish before installing its chart, images and Terraform provider.

Documentation: steadmesh.com, built from the static pages in docs/ with no build step: a quickstart, a tutorial, guides, reference pages, an FAQ, the demo results and the acceptance status. The design is in agent_organisation_initial_technical_design.md, and acceptance status is tracked in tests/acceptance/RESULTS.md.

Operate and delegate bounded work

Introduced in v0.6.0:

• Inspect, watch, pause and resume seats by their stable declaration key, with an explicit Kubernetes context
• Enforce cumulative model output budgets per organisation, seat and execution. These do not cap input tokens or dollar cost
• Delegate a task to a disposable worker with explicit text inputs, narrow permissions and reviewed result files
• Compare independent run alternatives from a shared handoff and record a chosen result. Selection does not apply files or change the working tree

See the upgrade notes before using these features on an older deployment.

Compose native teams

v0.7.0 adds native teams: combine declared leaders with bounded pools of independent teammates, coordinate through an explicitly shared work board, and choose fixed, self-editable or reviewed working instructions. Membership, mission editing, review, messaging and tool access remain separately controlled. Existing organizations keep their declared-team behavior unless these policies are enabled. Read the v0.7.0 upgrade notes before rollout.

External representative MCP gateway

The source tree includes an opt-in representative MCP gateway for an external agent to send durable messages, check their status and read its own representative conversation. It uses a separate authenticated listener; the internal platform API is never its public endpoint. It is disabled by default and requires an approved compatible deployment and HTTPS host. ChatGPT/dot connections require an existing OAuth provider; compatible MCP clients can also use a locally generated private bearer key. The setup guide covers Secret-based configuration, permissions, rotation and smoke tests.

Fastest start: the example organisation

darcys22/steadmesh-example is a four-seat organisation (representative, tech lead, senior engineer, reviewer) on Pi, with any OpenAI-compatible model endpoint and one GitHub repository. Clone it, fill in .env, apply platform/ then organisation/, and chat from the terminal with orgctl. No Slack needed. Its README and the quickstart walk through every step. Sandbox GitHub access on the hardened platform requires an existing credential-ledger Secret, including when delivering a PAT. Keep its key outside Terraform and Helm state; pass only its name with credential_ledger_secret_name. Older deployments need the permission-hardening rollout.

Quickstart: run agents in your cluster with Slack

You don't need to clone this repository. Terraform downloads everything: the provider from the Terraform Registry, the platform chart and images from ghcr.io, and the modules from GitHub.

What you need

• A Kubernetes cluster and a kubeconfig context for it. The cluster needs:
  • a CNI that enforces NetworkPolicy, because seats only start once their sandbox is verified (kind's default CNI, Calico and Cilium all qualify);
  • a default StorageClass;
  • about 4 CPUs and 8 GB of memory free.
• Terraform 1.5 or later, and kubectl.
• A Slack app. Create it from slack-app-manifest.yaml (api.slack.com/apps → Create New App → From a manifest). You need:
  • an app-level token (xapp-…, scope connections:write);
  • the bot token (xoxb-…);
  • your workspace ID (T…);
  • the member ID (U…) of each person who gets a representative. In Slack: profile → ⋮ → Copy member ID.
• A model API key. Seats run Claude Code on Anthropic by default; Codex (OpenAI Responses) and Pi (Anthropic, OpenAI Responses or Chat Completions) can be chosen per seat. Your provider bills every model request.
• Optional: a Linear API key and team ID, so agents can create projects and issues.

1. Get the quickstart

mkdir steadmesh && cd steadmesh
terraform init -from-module="github.com/darcys22/steadmesh//quickstart?ref=v0.7.0"

This copies two small Terraform roots into the directory:

• platform/ installs Steadmesh into your cluster;
• organisation/ declares your agents.

They are separate because the organisation's provider needs the platform's CRDs to exist before it can plan.

2. Install the platform

cd platform
cp terraform.tfvars.example terraform.tfvars   # set kube_context and your tokens
terraform init
terraform apply

This creates the steadmesh-system and steadmesh namespaces, Postgres, the platform chart and the credential Secrets. It never uses your current kubectl context, only the kube_context you set. Tokens given as variables end up in this root's Terraform state, so keep terraform.tfvars and the state private, or create the Secrets yourself and set existing_secret_refs instead.

3. Declare your organisation

cd ../organisation
cp terraform.tfvars.example terraform.tfvars   # workspace ID and the people
terraform init
terraform apply

Each person in humans gets a personal representative. Representatives can delegate to an engineering lead, who works with an engineer. The organisation stage reads the cluster, namespace and secret references from the platform stage's state. terraform apply returns once every seat has passed its readiness checks, which takes a few minutes the first time while the seat images are pulled.

4. Talk to your representative

In Slack, open the app and send it a direct message. Your representative replies in the same DM. Try:

• asking it to remember a preference;
• asking it to have engineering look into something;
• with Linear connected, asking for a project for a small task.

To watch the agents work, set enable_console = true in platform/terraform.tfvars, apply, and open the read-only console:

kubectl --context <your-context> -n steadmesh-system port-forward deploy/steadmesh-console 8090
# http://127.0.0.1:8090

Shape your organisation

Everything about your organisation is in organisation/:

• Culture and roles: edit instructions/culture.md (how everyone works) and instructions/representative.md (how representatives behave).
• People: add an entry to humans in terraform.tfvars. One Slack app serves every representative.
• Seats: add a teammate to local.engineering in main.tf, for example reviewer = { role = "reviewer", display_name = "Reviewer" }. Then give it a route under message_routes, such as eng_lead_reviewer = { from = "seat:eng_lead", to = "seat:reviewer", bidirectional = true }. Seats can only message along declared routes.
• Access: connections are only usable through grants. The Linear grant gives the whole engineering team project.create and task.write.

terraform plan shows exactly which seats a change affects. Seats keep their identity, workspace and memory across applies. The tutorial walks through every part of the declaration.

Upgrade or remove

• Upgrade: fetch the new release's quickstart into a fresh directory and carry over your terraform.tfvars, instructions/ and state. Or change every ?ref=v…, steadmesh_version and the provider version in your copy. Then apply platform/, then organisation/.
• Remove: run terraform destroy in organisation/, then in platform/. With data_retention = "retain", destroying the organisation keeps its memory and history in the platform's database. Destroying platform/ deletes the namespaces, and with them that database. Retention is not a backup and there is no built-in backup yet: back up Postgres and the seat volumes yourself first.

Develop from source

Prerequisites:

• Go 1.27
• Docker (Colima or Docker Desktop)
• kind
• kubectl
• helm
• Terraform ≥ 1.5

Every cluster target pins the kind-steadmesh context.

make tools              # controller-gen, setup-envtest into ./bin
make test               # unit tests
make test-integration   # Postgres (testcontainers), envtest, Terraform acceptance
make e2e                # fresh kind cluster, local images, full apply-to-conversation suite with fakes
make quickstart-test    # fresh kind cluster, runs quickstart/ as a user would, with local builds

make e2e and make quickstart-test delete and recreate the kind cluster, and remove the example Terraform state, before they run.

To deploy the in-repo example organisation (examples/) from source and talk to it through fake Slack and Linear servers, follow docs/from-source.html. To use real Slack, Linear and Claude Code with that setup, see docs/real-services.html and tests/live/README.md.

Releasing

Pushing a tag vX.Y.Z runs .github/workflows/release.yml, which publishes:

• images: ghcr.io/darcys22/steadmesh/<image>:X.Y.Z, for amd64 and arm64;
• chart: oci://ghcr.io/darcys22/steadmesh/charts/platform, version X.Y.Z;
• provider: signed builds and their Registry documentation on darcys22/terraform-provider-steadmesh, which the Terraform Registry serves as darcys22/steadmesh;
• a GitHub release in this repository.

To cut a release, run make release on a clean, up-to-date main. It bumps the minor version from the latest tag (BUMP=patch or BUMP=major, or VERSION=X.Y.Z), runs make lint test, then does what you could do by hand:

hack/set-version.sh X.Y.Z    # point quickstart/ and the provider doc examples at the new tag
make provider-docs           # re-render provider/docs
git commit -am "Release vX.Y.Z" && git tag vX.Y.Z && git push origin main vX.Y.Z

It asks before pushing (YES=1 skips the question); answering no leaves the release commit and tag local, with the commands to push or undo them.

The workflow refuses a tag that quickstart/ doesn't pin, and fails if provider/docs is out of date. The provider documentation is rendered by make provider-docs from the schema's descriptions, provider/docs-templates and provider/docs-examples, so a change to the provider schema needs a make provider-docs too.

One-time setup:

1. Provider release repository. Create the public repository darcys22/terraform-provider-steadmesh with at least one commit (a README is enough). The Terraform Registry only reads releases from a repository with that name.
2. Signing key. Generate a GPG key (RSA, without an expiry or with a long one).
   • Add its ASCII-armoured private key and passphrase to this repository's secrets as GPG_PRIVATE_KEY and GPG_PASSPHRASE.
   • Add a fine-grained token with Contents: read and write on the provider repository as PROVIDER_RELEASE_TOKEN.
3. Registry. After the first release, sign in to registry.terraform.io with GitHub. Publish the provider from darcys22/terraform-provider-steadmesh, and add the GPG public key under your namespace's signing keys.
4. Package visibility. After the first release, make the ghcr.io packages public: the five images and charts/platform. Do this under the repository's Packages → Package settings.

Components

License

Apache License 2.0. See LICENSE.