Quick bootstrap

The fastest way to get Agyn running. The bootstrap repo provisions a local k3d cluster and applies every platform stack via Terraform — Istio, OpenZiti, OpenFGA, Postgres, MinIO, all platform services, and the built-in apps.

This path is for development and evaluation. For production, see Production install.

Before you start

Confirm you have the prerequisites: Docker running, Terraform, and kubectl if you want kubeconfig merged.

Install

git clone --branch latest https://github.com/agynio/bootstrap.git
cd bootstrap
chmod +x apply.sh
./apply.sh

For non-interactive defaults (skips all prompts, uses defaults, merges kubeconfig automatically):

./apply.sh -y

Initial deployment takes about 15 minutes — most of it cluster provisioning, image pulls, and waiting for Argo CD applications to sync.

What it does, step by step

The installer applies nine stacks in order. Each waits for the previous to be healthy before continuing:

Per-step timing is printed at the end.

Defaults

Bootstrap uses these defaults unless you override them with environment variables before running apply.sh:

For real OIDC, set those env vars before apply.sh. See First admin for how the admin user is provisioned.

What you get

agyn.dev and its subdomains resolve to 127.0.0.1 automatically — no /etc/hosts edits needed. The wildcard TLS certificate is signed by the local CA installed in step 3, so browsers should not warn.

Sign in

Open the Console URL and sign in with admin@agyn.io (the default admin) via the mock OIDC provider. After signing in you have cluster admin rights — confirm via First admin.

If you set ADMIN_OIDC_SUBJECT to your own subject before running apply.sh, sign in as that user instead.

Provision a demo fleet

To populate the platform with a ready-made set of agents instead of clicking through the Console, use agynio/demo-agent — a Terraform config that provisions a support, marketing, and data_engineer agent against an OpenAI-backed model:

git clone https://github.com/agynio/demo-agent.git
cd demo-agent
cp terraform.tfvars.example terraform.tfvars
# edit terraform.tfvars: organization_id, api_token, openai_token
terraform init
terraform apply

Get the organization_id from your Console URL and the api_token from User menu → API Tokens → Create token. After apply, the three agents show up in Chat ready to talk to.

Kubeconfig

If you confirmed the kubeconfig merge (or ran with -y), ~/.kube/config now includes the agyn-local context:

kubectl config use-context k3d-agyn-local
kubectl get pods -A

If you skipped the merge, the kubeconfig is at bootstrap/stacks/k8s/.kube/agyn-local-kubeconfig.yaml.

Develop a single service

Once bootstrap is running, you can iterate on an individual platform service against the local cluster with DevSpace from that service's repository:

cd ../gateway
devspace dev      # syncs local code, exits when ready
devspace dev -w   # interactive: stays attached with logs and hot-reload

DevSpace pauses the service's Argo CD auto-sync, syncs local source into the running pod, and restarts the process with hot-reload. Auto-sync is restored on exit.

Teardown

There is no destroy.sh. Tear down by running terraform destroy on each stack in reverse:

terraform -chdir=stacks/apps destroy
terraform -chdir=stacks/platform destroy
terraform -chdir=stacks/data destroy
terraform -chdir=stacks/ziti destroy
terraform -chdir=stacks/deps destroy
terraform -chdir=stacks/routing destroy
terraform -chdir=stacks/system destroy
terraform -chdir=stacks/k8s destroy

The k8s destroy removes the k3d cluster itself. See Uninstall for the full sequence.

Troubleshooting

• Docker not running / not enough resources. Most failures during the k8s and data stacks come from Docker. Give it at least 6 vCPU, 12 GB RAM.
• Port 2496 or 6443 already in use. Stop whatever holds them (lsof -i :2496) or override PORT for ingress.
• Argo CD applications stuck Progressing. First-time image pulls take time. The installer waits up to 10 minutes per app group. If something stays stuck, kubectl -n <ns> logs <pod> from the failing pod.
• CA cert install denied. The CA install step needs sudo. If you cancel it, browsers will warn on every *.agyn.dev URL. Re-run ./install-ca-cert.sh -y local-certs/ca-agyn-dev.pem later.
• agyn.dev doesn't resolve. Very rare — the domain is configured to point at 127.0.0.1 publicly. If your network or DNS provider strips this, set a custom DOMAIN and add it to /etc/hosts yourself.

See Troubleshooting → Install for the full diagnostic flow.

Related

• Prerequisites
• First admin
• Administer → Console overview
• Production install