Quickstart

Get from zero to a running Tahyi swarm in four steps. This guide targets early adopters on the pre-0.1 scaffold — commands and URLs will tighten as TAH-77 ships the core repo.

Time: ~15 minutes (once the release is available)
Prerequisites: Node.js 22+, access to a non-production environment you control, and API credentials for at least one LLM provider.

1. Clone and install

git clone https://github.com/kay-g2/tahyi.git
cd tahyi
npm install

Note: Repos are private during pre-release (TAH-87). Clone access and public URLs go live when the board approves release. Until then, track progress on TAH-74.

Copy the example environment file and fill in your provider keys:

cp .env.example .env

Never commit .env or paste secrets into agent prompts — use environment-injected credentials only.

2. Start the control plane

npm run dev

The local control plane exposes:

• Dashboard — swarm status, active tasks, audit log
• Docs — this site, served alongside the app
• API — coordination layer for specialist agents

Default URL: http://localhost:4321 (exact port may vary by scaffold version).

3. Register your environment

Tahyi needs a beachhead environment — one cluster, namespace, or account to operate against. Start with non-production.

npx tahyi env register \
  --name staging \
  --type kubernetes \
  --kubeconfig ~/.kube/config

Supported environment types will expand after 0.1. The first release targets a single well-documented stack so the swarm can be tested end-to-end.

4. Deploy your first specialist

Enable one founding specialist — deployment is the recommended first agent:

npx tahyi agent enable deployment-maintainer \
  --environment staging \
  --dry-run

Dry-run mode is on by default for pre-0.1 builds. The agent plans actions, writes them to the audit log, and waits for approval before touching real infrastructure.

Verify it worked:

1. Open the dashboard → Agents → confirm deployment-maintainer shows idle or planning.
2. Open Tasks → you should see a bootstrap health-check task with full trace.
3. Review the plan in the audit log before approving any non-dry-run action.

What you just built

You now have:

• A local Tahyi control plane
• One registered non-prod environment
• One specialist agent operating in dry-run mode
• An audit trail for every planned action

Next steps

Goal	Go to
Understand swarm vocabulary	Core Concepts
Add monitoring or DBA specialists	How it Works
Contribute or report issues	Contributing

Troubleshooting

Agent stays in blocked: Check that environment credentials are valid and the LLM provider key is set in .env.

Dry-run plans look empty: Pre-0.1 builds ship with limited tool integrations — expect fuller plans after 0.1.

Port already in use: Set PORT=4322 (or any free port) in .env and restart.

Open an issue on GitHub or ask in the project thread on TAH-74 if you hit a blocker not covered here.