Skip to main content

​
Provider connections

Live execution only happens when Keycli has a valid provider connection for the exact target you want to mutate. That means the normal self-serve order is:
  1. bootstrap a workspace
  2. create a provider connection
  3. scope it tightly
  4. test it
  5. inspect readiness
  6. then create plans that target that scope

​
The rule to remember

Do not expect Keycli to fake confidence. If the connection is missing, invalid, or out of scope, Keycli should stay explicit and refuse to pretend live execution is available. That honesty is a feature, not a missing polish item.

​
Current provider support

  • Vercel — best first live demo path
  • GitHub — strongest current mixed-provider wedge
  • Render — real env var mutation, but not the recommended first session
If you only connect one provider on day one, make it Vercel. Why:
  • single provider
  • preview-safe demo path exists
  • easiest route to seeing plan.execution.mode: "provider-api"

​
Baseline flow

​
1) Start the hosted API

npm run api:hosted

​
2) Bootstrap a workspace

BOOTSTRAP=$(curl -s -X POST http://localhost:8788/v1/bootstrap \
  -H 'content-type: application/json' \
  -d '{"workspaceName":"demo","ownerName":"ricco"}')
Capture the owner token from the response and use it for connection setup.

​
3) Create the connection with explicit scope

Current scope shapes:
  • Vercel: { "provider": "vercel", "project": "your-project" }
  • GitHub: { "provider": "github", "repository": "org/repo" }
  • Render: { "provider": "render", "serviceId": "srv-..." }
Use the narrowest truthful scope you can.

​
4) Test the connection

After creating a connection, test it against the exact target you want to mutate. That tells you whether live execution is actually available for that target.

​
5) Inspect workspace readiness

Use authenticated capabilities to see what the workspace can honestly do: 
curl -s http://localhost:8788/v1/capabilities \
  -H "authorization: Bearer $KEYCLI_TOKEN"
Look for:
  • supported
  • configured
  • available
  • reason
  • scope metadata

​
Common reasons live execution is not available

Typical honest failure reasons include:
  • missing connection
  • invalid or expired credentials
  • scope mismatch
  • provider adapter not available for that target
When that happens, fix the connection story first. Do not jump straight to plan debugging.

​
Which guide to use

​
Use Vercel if you want the cleanest first win

Use the Vercel guide if you want:
  • the safest live demo
  • a single-provider preview target
  • a quick path to provider-api

​
Use GitHub when you want the strongest current wedge

Use the GitHub guide if you want:
  • GitHub Actions secret mutation
  • GitHub comment-based approval capture
  • the strongest current multi-provider story

​
Use Render when it matches your real stack

Use the Render guide if you need:
  • live Render service env var mutation
  • readiness and scope enforcement for Render

​
After connections

Once a provider is connected and tested, go straight to: