Docs
API local

Visão geral
O Knobler expõe um servidor HTTP opcional em 127.0.0.1:4477. Ele aceita
notificações transitórias, live activities, controle do espelho e perguntas
interativas. O servidor escuta somente loopback. As rotas legadas, incluindo
/ask, permanecem sem autenticação por compatibilidade. Solicitações de
agentes usam um token efêmero de sessão, gravado com modo 0600 (pasta 0700)
em ~/Library/Application Support/Knobler/agent-request-token. Cada abertura do
app gera um token novo e o grava quando a porta liga de fato — enquanto ela
estiver com outro processo, o arquivo continua com o token de quem a tem. Só
roda uma instância por vez (a mais nova encerra a anterior), então o arquivo
sempre corresponde ao processo que está escutando.
Ligue em Ajustes → Notch → API local. Desligar a opção fecha o listener e remove activities e perguntas pendentes. Se a porta estiver ocupada quando a API sobe, ela tenta de novo sozinha — depois de 1 s, 2 s, 4 s… até uma vez por minuto — até ligar ou até a opção ser desligada.
Segurança: requisições de navegador
Escutar só no loopback não impede que uma página aberta no navegador chame a
API. Por isso o servidor recusa com 403 as requisições que só um navegador
faria:
Hostdiferente de127.0.0.1oulocalhost(com ou sem:4477). Isso bloqueia DNS rebinding, em que um domínio externo passa a resolver para o loopback.Originpresente e diferente dehttp://127.0.0.1:4477ouhttp://localhost:4477. Isso bloqueia CSRF: todo POST de navegador levaOrigin.Sec-Fetch-Sitediferente denoneousame-origin. Isso bloqueia o GET cross-site, como<img src="…/ask/<id>">, que consumiria uma resposta.
curl, scripts e hooks não mandam esses headers e continuam funcionando sem mudança.
Ferramentas rápidas
# notificação
curl -X POST http://127.0.0.1:4477/notify \
-H 'Content-Type: application/json' \
-d '{"title":"Deploy finalizado","body":"em produção","app":"Terminal"}'
# live activity determinada; progress aceita 0–1 ou 0–100
curl -X POST http://127.0.0.1:4477/activity \
-d '{"id":"deploy","title":"Deploy","detail":"rsync","progress":40}'
# encerrar activity
curl -X POST http://127.0.0.1:4477/activity \
-d '{"id":"deploy","done":true}'
CLI incluído:
tools/knobler notify "Título" ["corpo"] ["app"]
tools/knobler activity <id> <0-100|-> "Título" ["detalhe"]
tools/knobler done <id>
tools/knobler ask "Pergunta?" "Opção A" "Opção B"
tools/knobler agent-request publish '{"id":"perm-1","agent":"claude","kind":"permission","title":"Permissão","summary":"Ler README","source":"terminal","actions":[{"action":"allow"},{"action":"deny"}]}'
tools/knobler agent-request wait perm-1
tools/knobler codex check # o app-server instalado expõe as aprovações?
tools/knobler codex bridge # app-server com as aprovações espelhadas no NOB
Referência dos endpoints
POST /notify
Publica um card transitório. title é obrigatório e não pode ser vazio.
{
"title": "Deploy finalizado",
"body": "em produção",
"app": "Terminal",
"supacodeWorktree": "/projetos/app",
"supacodeTab": "deploy"
}
supacodeWorktree e supacodeTab são opcionais e permitem focar uma sessão
do Supacode quando o card for clicado. Sucesso retorna {"ok":true}; JSON
inválido ou sem título retorna 400.
POST /activity
Cria ou atualiza uma activity por id. Se id for omitido, usa default.
{
"id": "deploy",
"title": "Deploy",
"detail": "rsync",
"progress": 0.4
}
progress é opcional e pode estar em 0…1 ou 0…100; valores são limitados
ao intervalo válido. Para atividade indeterminada, omita o campo ou use null.
Para remover:
{"id":"deploy","done":true}
Uma activity expira após 30 minutos sem atualização. A activity mais recentemente atualizada é a exibida.
POST /keyboard/lock · POST /keyboard/unlock
Bloqueia o teclado inteiro (teclas, modificadores, mídia) pra limpeza; o notch mostra "Teclado bloqueado — clique para destravar". Sem corpo. Não liga sem Acessibilidade (abre Ajustes › Permissões) nem com campo de senha focado (avisa no notch). O estado é só em memória: sair do app libera o teclado.
curl -X POST http://127.0.0.1:4477/keyboard/lock
POST /dictation/toggle
Liga ou desliga a gravação do ditado, o mesmo que segurar e soltar a ⌥ direita. A primeira chamada começa a gravar; a segunda para e transcreve. Sem corpo. Respeita o toggle de ditado em Ajustes: desligado, não começa a gravar. Como não instala o monitor de teclas, digitar durante a gravação não cancela.
curl -X POST http://127.0.0.1:4477/dictation/toggle
POST /mirror (plugin: espelho)
Liga o espelho no notch do monitor sob o ponteiro ou desliga o espelho em todos
os monitores. Com o Espelho desinstalado a rota responde
404 {"ok":false,"error":"plugin não instalado","plugin":"espelho"} — a marca
(plugin: X) no título é a fronteira entre rota estável e rota de peça.
{"on":true}
{"on":false}
Sem corpo, on assume true.
POST /ask
Cria uma pergunta interativa. O formato é compatível com AskUserQuestion:
{
"id": "ask-123",
"source": "knobler",
"questions": [
{
"question": "Continuar?",
"header": "Deploy",
"multiSelect": false,
"options": [
{"label":"Sim","description":"Continuar o deploy"},
{"label":"Não","description":"Parar agora"}
]
}
]
}
id e questions não vazios são obrigatórios. Cada pergunta precisa de pelo
menos uma opção com label. source é opcional e aparece como contexto no
card. O resultado é mostrado no notch e consultado pelo caller em
GET /ask/<id>, de preferência em long-poll.
GET /ask/<id>
Retorna o estado da pergunta:
{"answered":false}
Resposta concluída:
{
"answered": true,
"answers": {
"Continuar?": {"labels":["Sim"]}
}
}
Resposta com texto livre usa text; esse texto vence os labels da mesma
pergunta. A resposta é consumida na primeira leitura bem-sucedida. Se o card
for cancelado:
{"cancelled":true}
Pergunta desconhecida retorna 404. Perguntas pendentes expiram após 15
minutos.
Long-poll (X-Knobler-Wait)
GET /ask/<id> e GET /agent-requests/<id> aceitam o header
X-Knobler-Wait: <segundos>. Com ele, se o estado ainda está pendente, o
servidor segura a conexão e responde quando a pergunta ou a solicitação fica
final (respondida, cancelada, resolvida, dispensada ou expirada) ou quando o
prazo vence, o que vier primeiro. O JSON é o mesmo de um GET comum: prazo
vencido devolve {"answered":false} ou {"state":"pending"}, e o estado final
continua sendo lido uma única vez.
- O prazo é limitado a 25 s. Header ausente, zero, negativo ou inválido responde na hora, como sempre.
- Estado já final, id desconhecido,
401e403respondem na hora: o guarda de navegador e o Bearer valem antes de segurar. - Cliente que desiste (Ctrl-C, timeout) libera a vaga na hora, sem consumir a resposta. Acima de 64 conexões seguradas, o GET responde na hora.
- Desligar a API derruba as conexões seguradas, como recusaria um GET novo.
Por que existe: cada GET abre uma conexão TCP, e o Network.framework grava umas 20 linhas por conexão no log do sistema. Esperar um card com polling a cada 0,3 s enchia o log; com long-poll é uma conexão a cada 25 s.
É header, e não query string, porque o app sem suporte (0.36.0 e anteriores)
ignora o header e responde na hora. O cliente mantém o laço de sempre — GET com
o header e, se ainda pendente, sleep 0.3 — e funciona com as duas versões. O
timeout do cliente precisa cobrir a espera, com folga.
Timeout do cliente não quer dizer API fora. O prazo do servidor corre no
relógio que para quando o Mac dorme; o -m do curl (e o AbortSignal.timeout
do Node) conta o sono. Um Mac que dorme mais de 5 s no meio da espera estoura o
cliente com a pergunta ainda pendente. Trate o timeout (curl sai com 28) com
uma leitura sem espera: se ela responde, siga o laço; se não, o app parou de
verdade.
while :; do
rc=0
state="$(curl -sf -m 30 -H 'X-Knobler-Wait: 25' http://127.0.0.1:4477/ask/ask-123)" || rc=$?
# 28 = timeout: pode ser só o Mac que dormiu
[ "$rc" -eq 28 ] && { rc=0; state="$(curl -sf -m 2 http://127.0.0.1:4477/ask/ask-123)" || rc=$?; }
[ "$rc" -eq 0 ] || break
case "$state" in *'"answered":true'* | *'"cancelled":true'*) echo "$state"; break ;; esac
sleep 0.3
done
O CLI (knobler ask, knobler agent-request wait), os hooks do Claude e a
ponte do Codex já esperam assim.
POST /ask/<id>/cancel
Cancela uma pergunta pendente. A operação é idempotente e retorna
{"ok":true} mesmo quando a pergunta já terminou.
Solicitações de agentes autenticadas
Todas as rotas em /agent-requests exigem Authorization: Bearer <token>.
O token muda a cada inicialização do app; use o CLI incluído em vez de copiá-lo
para histórico de shell.
POST /agent-requests publica uma solicitação. Campos obrigatórios: id
(ASCII seguro para URL), agent (claude ou codex), kind (question ou
permission), title, summary, source (terminal, cli ou ide) e
entre uma e oito actions. As ações são allow, allowForSession, deny,
cancel, ou option/text com value.
{
"id": "permission-42",
"agent": "claude",
"kind": "permission",
"title": "Ler arquivo",
"summary": "README.md",
"source": "terminal",
"actions": [{"action":"allow"}, {"action":"deny"}]
}
GET /agent-requests/<id> retorna {"state":"pending"} enquanto aguarda
(aceita long-poll). Depois retorna uma única vez o
estado final e result; a segunda leitura é 404. A ação em result vem no
mesmo formato das actions — um objeto, não uma string:
{"id":"permission-42","state":"resolved","result":{"action":{"action":"allow"},"responder":"nob","state":"resolved"}}
POST /agent-requests/<id>/resolve recebe uma ação nesse formato e aceita
apenas uma ação oferecida. POST /agent-requests/<id>/dismiss cancela.
Resoluções repetidas são no-op: a primeira ação válida vence.
Claude PermissionRequest
O hook do Claude envia tool_name, tool_input, permission_suggestions e
session_id ao endpoint como dados, sem executar o conteúdo recebido. allow
autoriza apenas a operação atual. allowForSession só está disponível quando
Claude forneceu uma sugestão de allow; o hook muda o destino dessas regras para
session, portanto não escreve configurações persistentes. Em falha ou timeout
da API, ele sai com sucesso e sem JSON para manter o prompt nativo do Claude.
Aprovações do Codex
A ponte tools/codex-agent-bridge.mjs traduz os pedidos de aprovação do
app-server do Codex para o mesmo endpoint: allow/allowForSession viram
accept/acceptForSession, deny vira decline e cancel interrompe o
turno. Emendas de execpolicy e de política de rede não viram botão, porque são
regras persistentes. Sem token, sem API ou sem decisão dentro do prazo, a ponte
não responde e o Codex mostra a aprovação nativa. Detalhes em
agent-requests.md.
GET /status
Retorna diagnóstico do app. O schema é deliberadamente extensível; campos
atuais incluem notches, player, visualizerTapped, dictation, ask,
agentRequests, micInUse, silenciando, lanMessaging, desempenho e
plugins — este último é a lista de
ids das peças instaladas (ver plugins.md), pra um script
perguntar uma vez em vez de descobrir batendo em rota; campo de peça desligada
simplesmente não aparece. silenciando é true quando a
notificação que chegar agora vai direto pro histórico em vez de virar card (ver
notifications.md). Cada entrada de notches traz também focus: o
identificador da seção que o card aberto está mostrando (musica, atividade,
pomodoro, shelf, espelho, mensagens, historico, nota, link,
anotacao), ou string vazia quando não há seção em foco. A anotação de tela
reporta em annotation: axTrusted, tapExists, tapEnabled, isActive,
tool, background e lineWidth. O espelho reporta cameraAuth,
cameraDevice, mirrorSessionRunning, mirrorUseCount e mirrorFailed —
este último é true quando abrir o dispositivo de vídeo falhou. ask e
agentRequests trazem pending e waiting — este último conta as conexões em
long-poll seguradas agora. desempenho é a última amostra do registro de
desempenho (tirada no lançamento e a cada 5 min, nunca mais velha que isso):
data, versao, pid, uptime_s, footprint_mb, residente_mb, cpu_s,
cpu_pct, threads, notches, displays e janelas — os campos e o
histórico de 7 dias estão em
troubleshooting.md.
curl -sS http://127.0.0.1:4477/status | jq .
curl -sS http://127.0.0.1:4477/status | jq .desempenho
Use esse endpoint para diagnóstico local, não como contrato de persistência.
Erros e limites
200com{"ok":true}para comandos aceitos.400para JSON inválido ou campos obrigatórios ausentes.403para requisição de navegador (Host,OriginouSec-Fetch-Sitefora do loopback; veja acima).404para endpoint desconhecido, Ask inexistente ou rota de plugin desinstalado (o corpo trazplugincom o id da peça).- O listener recebe até 64 KiB por requisição.
- O long-poll segura um GET por no máximo 25 s e no máximo 64 conexões ao mesmo tempo.
- Corpos de
/agent-requestssão limitados a 32 KiB e retornam413acima desse limite; JSON ou campos inválidos retornam400, e token ausente ou incorreto retorna401. - A API não é exposta na LAN e não deve ser colocada atrás de um proxy sem autenticação e controle de origem.
Para problemas, veja troubleshooting.md. Para o fluxo
Ask e o ownership do estado, veja architecture.md.