Jetty Setup Wizard

Security Guidelines

• Never echo, print, or log API tokens or keys in output. Use redacted forms (e.g.,

  mlc_...xxxx

  ) when referring to tokens in messages to the user.
• Never store tokens in project files like

  CLAUDE.md

  that may be committed to version control. Use the user-scoped config directory

  ~/.config/jetty/

  .
• Read secrets interactively with

  read -rs

  so the raw value never appears in generated commands, tool-call logs, or shell history. Pipe the value directly from the variable into

  curl

  and

  unset

  it immediately after.
• Confirm with the user before each API call that sends credentials to an external service.
• Never store provider API keys locally — they are sent directly to the Jetty API for server-side storage and are not written to any local file.

Step 1: Check for Existing Token

1. Check

   ~/.config/jetty/token

   for a stored token
2. Also check the project's

   CLAUDE.md

   file (for backward compatibility) for a token starting with

   mlc_

3. If found in

   CLAUDE.md

   but not in

   ~/.config/jetty/token

   , migrate it (see "Save the Token" below) and remove it from

   CLAUDE.md

4. If found, validate it:

TOKEN="$(cat ~/.config/jetty/token 2>/dev/null)"
curl -s -H "Authorization: Bearer $TOKEN" "https://flows-api.jetty.io/api/v1/collections/" | head -c 200

"Found a valid Jetty token (

mlc_...{last 4 chars}

). You're already connected!"

• Header: "Setup"
• Question: "You already have a Jetty token configured. What would you like to do?"
• Options:
  • "Create my first runbook" / "Learn about runbooks and build one"
  • "Reconfigure" / "Start fresh with a new token or provider"
  • "I'm good" / "No further setup needed"

Step 2: Account Creation

• Header: "Account"
• Question: "Do you already have a Jetty account?"
• Options:
  • "Yes, I have an API key" / "I have a Jetty account and can paste my API key"
  • "No, I need to sign up" / "Open the Jetty signup page in my browser"

If "Yes, I have an API key":

• Header: "API Key"
• Question: "Please paste your Jetty API key (starts with mlc_):"
• Options:
  • "I'll type it in" / "Let me enter my API key" (they will use the "Other" option to type it)
  • "I need to find it" / "Open flows.jetty.io so I can get my key"

open "https://flows.jetty.io/settings" 2>/dev/null || xdg-open "https://flows.jetty.io/settings" 2>/dev/null

If "No, I need to sign up":

"Opening Jetty in your browser. Here's what to do:

1. Click Get started free to create your account
2. Complete the onboarding (pick a collection name — this is your workspace)
3. Once you're on the dashboard, go to Settings to find your API key
4. Copy the API key and come back here to paste it"

open "https://flows.jetty.io/sign-up" 2>/dev/null || xdg-open "https://flows.jetty.io/sign-up" 2>/dev/null

• Header: "API Key"
• Question: "Once you've signed up, paste your Jetty API key here (starts with mlc_):"
• Options:
  • "I'll type it in" / "Let me paste my API key" (they will use the "Other" option)
  • "I'm stuck" / "I need help finding my API key"

"Your API key is at flows.jetty.io → Settings → API Tokens. Click Create Token, copy it, and paste it here."

Validate the Key

read -rs

mkdir -p ~/.config/jetty && chmod 700 ~/.config/jetty
echo "Paste your Jetty API token and press Enter:"
read -rs JETTY_TOKEN && printf '%s' "$JETTY_TOKEN" > ~/.config/jetty/token && unset JETTY_TOKEN
chmod 600 ~/.config/jetty/token
# Now validate using the stored file
curl -s -H "Authorization: Bearer $(cat ~/.config/jetty/token)" "https://flows-api.jetty.io/api/v1/collections/"

read -rs

1. Parse the response to find the collection name(s)
2. Tell the user which collections they have access to

Save the Token

read -rs

CLAUDE.md

I have a production jetty api token mlc_...

CLAUDE.md

"Your API token is saved to

~/.config/jetty/token

(user-scoped, outside your project directory). It won't be accidentally committed to git."

Step 3: Choose Provider & Store API Key

Step 3a: Check for Existing Keys & Offer Trial

TOKEN="$(cat ~/.config/jetty/token)"
RESPONSE=$(curl -s "https://flows-api.jetty.io/api/v1/collections/$COLLECTION" \
  -H "Authorization: Bearer $TOKEN")
echo "$RESPONSE" | python3 -c "import sys,json; d=json.load(sys.stdin); evars=d.get('environment_variables',{}); print('Configured keys:', list(evars.keys()) if evars else 'none')"

environment_variables

OPENAI_API_KEY

ANTHROPIC_API_KEY

GEMINI_API_KEY

REPLICATE_API_TOKEN

• Header: "Getting Started"
• Question: "Your collection doesn't have any AI provider keys configured yet.\n\nWould you like to:"
• Options:
  • "Try Jetty free" / "Get 10 free runs (up to 60 minutes) using Jetty-provided AI keys. No third-party signup needed."
  • "Add your own keys" / "Configure your OpenAI, Anthropic, Gemini, or Replicate API keys now."

TOKEN="$(cat ~/.config/jetty/token)"
curl -s -X POST "https://flows-api.jetty.io/api/v1/trial/$COLLECTION/activate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" | python3 -c "
import sys, json
d = json.load(sys.stdin)
if d.get('active') or d.get('status') == 'active':
    print(f'Trial activated! Runs remaining: {d.get(\"runs_remaining\", \"?\")}, Minutes remaining: {d.get(\"minutes_remaining\", \"?\")}')
else:
    print('Error:', json.dumps(d))
"

• On success: Tell the user their trial is activated, show remaining runs and minutes, then skip directly to Step 4 (Deploy the Demo Workflow). The trial provides all necessary AI keys server-side.
• On error: Inform the user the trial could not be activated, then fall through to the "Add your own keys" flow below.

Step 3b: Choose Provider

• Header: "Provider"
• Question: "Which AI provider would you like to configure for your workflows?"
• Options:
  • "OpenAI" / "GPT models, DALL-E image generation, and more"
  • "Google Gemini" / "Gemini models for text, vision, and image generation"

• Header: "Provider Key"
• Question: "Paste your {OpenAI/Google} API key:"
• Options:
  • "I'll type it in" / "Let me paste my API key" (they will use the "Other" option)
  • "Where do I get one?" / "Help me find or create an API key"

• OpenAI: "Get your API key at https://platform.openai.com/api-keys"
  bash

  open "https://platform.openai.com/api-keys" 2>/dev/null || xdg-open "https://platform.openai.com/api-keys" 2>/dev/null

• Gemini: "Get your API key at https://aistudio.google.com/apikey"
  bash

  open "https://aistudio.google.com/apikey" 2>/dev/null || xdg-open "https://aistudio.google.com/apikey" 2>/dev/null

Step 3c: Store the Provider Key in Collection Environment Variables

• Header: "Confirm"
• Question: "I'll now send your {provider} API key to Jetty's server so your workflows can use it. The key is stored server-side in your collection's environment variables and is NOT saved locally. Proceed?"
• Options:
  • "Yes, store it" / "Send my API key to Jetty"
  • "Cancel" / "Don't store the key"

read -rs

COLLECTION="the-collection-name"
echo "Paste your OpenAI API key and press Enter:"
read -rs PROVIDER_KEY && \
  printf '{"environment_variables": {"OPENAI_API_KEY": "%s"}}' "$PROVIDER_KEY" | \
  curl -s -X PATCH -H "Authorization: Bearer $(cat ~/.config/jetty/token)" \
    -H "Content-Type: application/json" \
    "https://flows-api.jetty.io/api/v1/collections/$COLLECTION/environment" \
    --data-binary @- && \
  unset PROVIDER_KEY

COLLECTION="the-collection-name"
echo "Paste your Gemini API key and press Enter:"
read -rs PROVIDER_KEY && \
  printf '{"environment_variables": {"GEMINI_API_KEY": "%s"}}' "$PROVIDER_KEY" | \
  curl -s -X PATCH -H "Authorization: Bearer $(cat ~/.config/jetty/token)" \
    -H "Content-Type: application/json" \
    "https://flows-api.jetty.io/api/v1/collections/$COLLECTION/environment" \
    --data-binary @- && \
  unset PROVIDER_KEY

read -rs

printf

curl

TOKEN="$(cat ~/.config/jetty/token)"
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/collections/$COLLECTION" | python3 -c "import sys,json; d=json.load(sys.stdin); evars=d.get('environment_variables',{}); print('Stored keys:', list(evars.keys()) if evars else 'none')"

"Your {provider} API key has been stored in your Jetty collection's server-side environment. Workflows will use it automatically. The key was not saved to any local file."

Step 3d: Agent Runtime Key (for Runbooks)

• Header: "Agent Runtime"
• Question: "Jetty runbooks run inside a coding agent. Which will you use?"
• Options:
  • "Claude Code" / "Anthropic's claude-sonnet-4-6. Needs an Anthropic API key (~$3/MTok input)"
  • "Codex" / "OpenAI's gpt-5.4. Needs an OpenAI API key"
  • "Gemini CLI" / "Google's gemini-3.1-pro-preview. Needs a Google AI API key"
  • "Skip for now" / "I'll configure this later when I need runbooks"

• Claude Code →

  ANTHROPIC_API_KEY

• Codex →

  OPENAI_API_KEY

  (may already exist from provider step above)
• Gemini CLI →

  GOOGLE_API_KEY

  (may already exist from provider step above)

TOKEN="$(cat ~/.config/jetty/token)"
COLLECTION="the-collection-name"
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://flows-api.jetty.io/api/v1/collections/$COLLECTION" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); evars=d.get('environment_variables',{}); print('Stored keys:', list(evars.keys()) if evars else 'none')"

"Your {agent} API key is already configured. You're ready to run runbooks!"

read -rs

curl PATCH

unset

• Anthropic: "Get your key at https://console.anthropic.com/settings/keys"
  bash

  open "https://console.anthropic.com/settings/keys" 2>/dev/null || xdg-open "https://console.anthropic.com/settings/keys" 2>/dev/null

• OpenAI: "Get your key at https://platform.openai.com/api-keys"
• Google: "Get your key at https://aistudio.google.com/apikey"

Step 4: Introduce Runbooks

What's a runbook?

A runbook is a human-readable markdown file that describes a series of steps for a coding agent to follow — like a recipe for automation. Here's what makes them powerful:

• Plain markdown — You can read, edit, and version-control them just like any other document
• Agent-executed — A coding agent (Claude Code, Codex, Gemini CLI) reads the runbook and carries out each step autonomously
• Measurable outcomes — Every runbook ends with a concrete, verifiable result (a report, a dataset, a set of passing tests)
• Multi-step with judgment — Runbooks can include evaluation loops where the agent checks its own work and iterates until the result meets a quality bar
• API-connected — Tasks can interact with any system you give them access to via API keys stored in your Jetty collection. They can call external APIs, query databases, process files, and more
• Long-running — Unlike a quick chat response, runbook tasks typically run for several minutes (up to 60), working through complex multi-step processes end to end

Think of a runbook as the difference between asking someone a question and handing them a detailed project brief.

Step 5: Suggest a Starter Runbook

• Header: "Your First Runbook"
• Question: "What kind of task would you like to automate? Pick a starter template or describe your own."
• Options:
  • "Data extraction" / "Extract structured data from documents, validate against a schema, and produce a quality report"
  • "Content generation" / "Generate content from a brief, score it against a rubric, and iterate until it meets a quality bar"
  • "Testing & regression" / "Run a test suite or replay queries against an API, evaluate pass/fail, and produce a regression report"
  • "Something else" / "I'll describe what I want to automate"

If the user picks a template:

"This runbook will pull data from a source you specify (documents, APIs, web pages), extract structured fields, validate them against a schema, and iterate on any errors — then produce a summary report."

"This runbook will take a brief or prompt, generate content (text, images, code — whatever you need), evaluate the output against quality criteria you define, and refine it until it's good enough."

"This runbook will run a set of test cases against an API or system, compare results to expected outcomes, and produce a pass/fail regression report with details on any failures."

• Header: "Describe Your Task"
• Question: "Now describe your specific use case in a sentence or two. What goes in, what processing happens, and what comes out? For example: 'Pull product descriptions from our CSV, translate them to Spanish, and check that each translation preserves the brand name and key specs.'"
• Options:
  • "I'll describe it" / "Let me type my use case" (user types in the text field)

If the user chose "Something else":

• Header: "Describe Your Task"
• Question: "Describe the task you'd like to automate in simple terms. What goes in, what processing happens, and what should come out at the end? Remember — any system you can reach via an API key, the agent can interact with too."
• Options:
  • "I'll describe it" / "Let me type a description" (user types in the text field)
  • "Show me more examples" / "I'd like to see more ideas first"

Example runbook tasks people have built:

1. NL-to-SQL Regression — Pull failed queries from a log, replay them against an NL-to-SQL API, execute on a database, evaluate pass/fail, produce a regression report
2. PDF-to-Metadata Conversion — Extract metadata from academic PDFs, generate structured JSON-LD, validate against a schema, iterate on errors
3. Branded Social Graphics — Parse a text script, generate AI images, compose HTML with overlays, judge against a brand rubric, iterate until on-brand
4. Clinical Training Content — Parse competency documents, generate training scenarios, score with a rubric, produce learning plans
5. API Health Monitor — Hit a list of endpoints, compare response shapes to expected schemas, flag regressions, produce a status report

Step 6: Hand Off to Create-Runbook

"Great — I have enough to get started. I'm going to hand you off to the runbook creation wizard, which will walk you through building your runbook step by step."

/create-runbook

"Run

/create-runbook <their task description>

to start building your runbook."

Step 7: Next Steps

"You're all set! Here's what you can do next:

Run your runbook on Jetty:

/jetty run-runbook <path-to-your-runbook>

Create another runbook:

/create-runbook

— the wizard will guide you through it

Optimize a runbook after a few runs:

/optimize-runbook

— analyzes past executions and suggests improvements

Manage your workflows and tasks:

/jetty list tasks

— see everything in your collection

Check execution history:

/jetty show trajectories

— see all past runs and their results

The

/jetty

command is your gateway to the full Jetty platform. Just describe what you want in natural language."

Important Notes

• Read the token from file: Use

  TOKEN="$(cat ~/.config/jetty/token)"

  at the start of each bash command block. Environment variables do not persist between bash invocations.
• Never log credentials: Do not echo, print, or include tokens/keys in output shown to the user. Use redacted forms like

  mlc_...xxxx

  .
• Read secrets interactively via

  read -rs

  : Never embed secrets in generated commands, heredocs, or temp files. Use

  read -rs VAR && printf ... "$VAR" | curl --data-binary @-

  so the secret flows from the user's terminal directly into the API call without appearing in tool-call output or shell history. Always

  unset

  the variable immediately after use.
• URL disambiguation: Use

  flows-api.jetty.io

  for all API calls (workflows, collections, tasks, trajectories, files). NEVER use

  flows.jetty.io

  for API calls (it's the web frontend).
• Trajectories response shape: The list endpoint returns

  {"trajectories": [...]}

  — always access via

  .trajectories[]

  .
• Steps are objects, not arrays: Trajectory steps are keyed by step name (e.g.,

  .steps.expand_prompt

  ), not by index.