Skip to content

quickstart.mdx

Latest commit

 

History

History
166 lines (120 loc) · 10 KB

quickstart.mdx

File metadata and controls

166 lines (120 loc) · 10 KB
title Quickstart
description Install zombiectl, run /usezombie-install-platform-ops, see a real diagnosis in Slack.

This walks through installing the flagship platform-ops agent on one of your repositories. Total time: about ten minutes from a cold machine. At the end, a deploy failure on the repo lands an evidenced diagnosis in your Slack channel.

You'll drive the install via a markdown-skill host. Any of these work — the install skill ships identical prompts in each:
  • Claude Code — claude.ai/code
  • Amp — ampcode.com
  • Codex CLI — npm install -g @openai/codex
  • OpenCode — opencode.ai

Pick one. The rest of this page assumes you have a working session in front of you.

```bash npm install -g @usezombie/zombiectl npx skills add usezombie/skills ```

Verify:

zombiectl --version

zombiectl is the only binary you install on your machine; it ships the skill samples under ~/.config/usezombie/samples/ so the install skill can drive zombiectl install --from against a known-good source. npx skills add usezombie/skills then symlinks the /usezombie-* host skills from the public usezombie/skills repo into every supported agent it detects — so /usezombie-install-platform-ops is ready to invoke in the next step.

```bash zombiectl login ```

Opens a Clerk-backed approval page in your browser. After you click Approve, the page shows a 6-digit verification code — type it back into the CLI to complete login. The code binds the browser approver to the terminal you're typing from. Hosted execution (event receipts + runs) is free until July 31, 2026 — no credit card to start; see pricing for the metered rates after the trial. You bring your provider and model — pay them directly. usezombie marks up zero on inference.

Login also fetches your tenant's workspaces and selects the first one as active locally. Signup auto-provisions a default workspace, so your CLI is ready to install agents immediately — no workspace add required.

Pass --token-name "your-device-label" to label this install so it's easy to recognize on the approval page and in zombiectl auth status later. Defaults to your platform family otherwise.

**No terminal — CI, or an agent driving the CLI?** Skip the browser entirely: supply a token via the `--token ` flag, the `ZOMBIE_TOKEN` environment variable, or piped on stdin — resolved in that order (prefer the env var or stdin to keep it out of shell history). Add `--no-input` to fail fast instead of waiting for the code — a no-TTY shell with no token exits with an error. Full precedence in [`zombiectl login`](/cli/zombiectl#zombiectl-login). ```bash zombiectl workspace add platform-ops ```

Skip this step if the signup-provisioned default workspace is fine. Run it only when you want a second workspace or a custom name. Workspaces are the boundary for credentials, access control, and webhook namespaces — every agent lives in exactly one. Switch later with zombiectl workspace use <id>. See Command reference → workspaces.

The `npx skills add usezombie/skills` in Step 2 already added the `/usezombie-install-platform-ops` skill to your agent. Invoke it: 
/usezombie-install-platform-ops

The skill drives zombiectl install --from ~/.config/usezombie/samples/platform-ops under the hood. Power users can run that directly; everyone else gets the guided flow.

**Fresh machine?** `curl -fsSL https://usezombie.sh | bash` installs `zombiectl` and the skill in one shot (it runs npm under the hood) — a one-command replacement for Step 2. You still need `zombiectl login` (Step 3) before the skill works. Run `curl -fsSL https://usezombie.sh` without `| bash` to read it first.

The skill asks three gating questions:

  • Slack channel — where diagnoses post (e.g. #platform-ops).
  • Production branch glob — which branches count as production (default main).
  • Cron schedule (optional) — for periodic health checks (e.g. */30 * * * *). Leave blank for webhook-only.

It writes .usezombie/platform-ops/SKILL.md and .usezombie/platform-ops/TRIGGER.md into the current repo. Re-running against the same workspace is idempotent; existing files are diffed and updated.

The install skill registers the GitHub webhook automatically. It reads the `triggers[]` block in the generated `TRIGGER.md`, then calls `gh api repos///hooks` per webhook trigger — using the user's existing `gh` authentication and the `webhook_secret` field from the workspace `github` credential. There is no paste-into-GitHub step.

After install, the skill prints a summary line per registered hook:

✓ github · https://api.usezombie.com/v1/webhooks/zmb_2041/github
  hook_id=489182  events=[workflow_run]  active=true
  HMAC self-verify: ok

The agent filters incoming payloads for conclusion=failure on a production-branch workflow — the rule lives in the generated .usezombie/platform-ops/SKILL.md and is editable. See Authoring to widen or narrow it.

If gh is not authenticated for admin:repo_hook scope, the skill stops with the exact recovery command (gh auth refresh -s admin:repo_hook). If the hook already exists at the same URL, the skill matches on config.url and advances — re-running the install is idempotent.

**One workspace credential, many repos.** The workspace's `github` credential carries the signing secret for every agent in the workspace. Tradeoff: rotation is workspace-wide; rotating the workspace `github` credential affects every agent that uses it. **Rotating the webhook secret.** The signing secret lives in the workspace vault under the `github` credential — there is no user-visible copy printed at install. To rotate, replace the credential then update every registered hook with `gh`. Two steps: 
**1. Rotate the workspace `github` credential.** Generate a new webhook secret (e.g. `openssl rand -hex 32`), store it in 1Password, then pipe the credential JSON through `op inject` so the secret never appears in shell history or argv. Run `op signin` first — if the 1Password session is stale, `op inject` fails before `zombiectl` runs and the workspace vault is left untouched (don't proceed to step 2 in that case, or your GitHub webhooks will be set to a secret the server never stored):

```bash
cat <<'JSON' | op inject | zombiectl credential add github --data=@- --force
{
  "api_token":      "{{ op://Personal/usezombie-github/api_token }}",
  "webhook_secret": "{{ op://Personal/usezombie-github/webhook_secret }}"
}
JSON
```

`op inject` substitutes each `{{ op://... }}` reference with the resolved secret and pipes the rendered JSON to `zombiectl`. `--data=@-` reads from stdin; `--force` overwrites the existing credential. If you don't use 1Password, the literal-JSON form below works the same — just keep it on stdin, never inline:

```bash
cat <<'JSON' | zombiectl credential add github --data=@- --force
{ "api_token": "ghp_...", "webhook_secret": "<new-secret>" }
JSON
```

See [Credentials](/zombies/credentials) for the full schema.

**2. Update every registered hook.** Re-run `/usezombie-install-platform-ops` in each repo — the install skill detects the existing hook, calls `gh api -X PATCH repos/<owner>/<repo>/hooks/<hook_id>` with the new secret, and re-runs HMAC self-verify. The old secret stops working the moment step 1 completes, so do this immediately after.
Cause a deploy failure on the production branch — push a known-broken commit, fail a test on purpose, whatever you have handy. Within seconds:
  • GitHub fires workflow_run.completed with conclusion: failure to the webhook URL.
  • The agent wakes, calls the tools TRIGGER.md allow-lists (http_request against your hosting provider, memory_store for findings), gathers evidence from the failed workflow.
  • An evidenced diagnosis posts to your Slack channel.

Tail it — replace <zombie_id> with the value the install step printed (e.g. zmb_2041):

zombiectl logs zmb_2041

Need to slice by source or time window? zombiectl events zmb_2041 --actor 'webhook:*' --since 30m. Lost track of the ID? zombiectl list prints every agent in the active workspace. Or watch the same stream in the dashboard at app.usezombie.com.

What just happened

The platform-ops agent installed SKILL.md (the prose system prompt — what to investigate, how to phrase a diagnosis) and TRIGGER.md (which tools the model can call) into your repo. From here, behaviour iterates on prose: edit the .usezombie/platform-ops/SKILL.md file, push, the next trigger runs the new behaviour. No redeploys, no DAG editor.

Next steps

`zombiectl steer "morning health check"` — same reasoning loop, manual trigger. Useful before you have a webhook firing. The two markdown files in `.usezombie/platform-ops/` are the entire behaviour. Edit them like any other source file. Why deep incidents keep reasoning past the model's context cap. Defaults work for 95% of cases. The `SKILL.md` + `TRIGGER.md` reference for writing your own.