Quickstart#
Install the app, create a key, and have an agent ask you something. About 60 seconds.
1. Install the app#
Download Frame from the App Store on your iPhone, iPad or Mac and open it once. It creates your account on the device (no email needed) and asks to allow notifications. Say yes: that is how approvals reach your lock screen.
2. Create an API key#
In the app: Settings → Projects → Default → Keys → New key. Name it (for example my-laptop), choose the write scope, and copy the secret. It starts with afk_w_ and is shown once.
Keep the key out of git. Put it in an environment variable or your CI secret store.
3. Log in with the CLI#
npx agentsframe login --key afk_w_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxThis verifies the key and stores it in ~/.config/agentsframe/config.json (permissions 600). To skip the file, export AGENTSFRAME_KEY instead. Check the connection any time:
npx agentsframe whoami
npx agentsframe doctor4. Send your first approval#
npx agentsframe approve "Deploy?" --waitYour phone buzzes with Deploy? and two buttons. The command waits until you tap, prints the result and exits with a code your script can branch on: 0 approved, 10 denied.
{"approved":true,"outcome":"answered","action":"approve","state":"answered","card_id":"crd_8f2k1x"}Use it in a script:
if frame approve "Run the database migration on prod?" --wait --timeout 600 --on-expire deny; then
./migrate.sh
else
echo "Not approved, skipping." >&2
fiThe same with curl#
No CLI needed. Create the card, then long-poll for the answer.
export AGENTSFRAME_KEY=afk_w_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# 1. create the card
CARD=$(curl -s https://api.agentsframe.com/v1/cards \
-H "Authorization: Bearer $AGENTSFRAME_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"approval","title":"Deploy?"}')
ID=$(echo "$CARD" | jq -r .id)
# 2. wait for the answer (returns 200 once answered, 202 while still open)
until [ "$(curl -s -o /tmp/card.json -w '%{http_code}' \
-H "Authorization: Bearer $AGENTSFRAME_KEY" \
"https://api.agentsframe.com/v1/cards/$ID/wait?timeout=50")" = 200 ]; do :; done
jq -r '.response.action' /tmp/card.json # approve | denyWithout actions an approval gets Approve and Deny. wait is a long poll: it returns 200 with the card as soon as state leaves open, or 202 after timeout seconds (1 to 55) so you loop.
From code#
import { Frame } from "agentsframe";
const frame = new Frame({ key: process.env.AGENTSFRAME_KEY! });
const { approved } = await frame.approve("Deploy?", { wait: true });
if (approved) await deploy();from agentsframe import Frame
frame = Frame() # reads AGENTSFRAME_KEY
if frame.approve("Deploy?", wait=True).approved:
deploy()What next#
- Ask a question with choices:
frame ask "Which thumbnail?" --option a:A --option b:B - Show a result:
frame show ./render.mp4 --title "Episode 12" --review - Report progress:
frame progress start "Nightly import" --value 0.6 - Put a number on your board:
frame metric set youtube.subscribers 48210 - Give Claude Code or Codex a tool to reach you: MCP setup
- Learn the model: Concepts