Approvals for apps
Your own app can run your agents through Languid's XRPC API and answer the calls they ask you about, the way the web chat does. This page covers starting a run that asks, showing what's waiting, and answering it.
How approvals work
Some calls need your yes before they run: bash, edit and write on a computer, record writes from a script that your agent's policy says to ask about, and sharing error reports. Your rules for a computer decide first. A call they allow runs without asking, and a call they deny is refused without asking.
When a run asks, Languid writes an ai.languid.approval.request record in the agent's space. Your answer is an ai.languid.tool.approval record, written under the request's own record key, so a request has one answer at most. See Records.
- Approve: the call runs, and the run goes on.
- Deny: the agent gets an error result saying you denied it, and decides what to do next.
- No answer in 5 minutes: the call is denied with "no answer in time", and a later answer is refused.
A tool call that's waiting survives a restart of the service. After a restart, the question comes back under a new run. A script that asks partway through doesn't survive one: the script stops, and its call ends as interrupted.
Sign in
Sign people in with atproto OAuth and call Languid through their PDS. Ask for an rpc scope for each method you call, with Languid as the audience:
rpc:ai.languid.agent.run?aud=did:web:languid.ai%23languid
rpc:ai.languid.agent.getRun?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.list?aud=did:web:languid.ai%23languid
rpc:ai.languid.approval.answer?aud=did:web:languid.ai%23languidSend each call to the person's PDS with this header:
atproto-proxy: did:web:languid.ai#languidTheir PDS forwards the call to Languid with a token for that one call. Apps can call only these four methods, and only on that person's own agents: any other agent's name gets 404 AgentNotFound.
Scripts you run yourself can send Authorization: Bearer with the token from languid login instead:
jq -r .server.token ~/.languid/state.jsonStart a run that asks
POST /xrpc/ai.languid.agent.run
{ "agent": "scout", "prompt": "Tidy the notes folder", "thread": "3n2js7khmj2aq", "approval": "ask" }The response is { run, thread, accepted, since, message }. With accepted: "queued", the thread already had a run: follow that one from since.
approval sets what happens to calls that need your yes:
approval | Calls that need your yes |
|---|---|
"ask" | wait for your answer |
"allow" | run without asking (not sharing error reports, which always asks) |
"auto" | are approved when a classifier model finds them reversible and covered by the owner's latest message, and wait for your answer otherwise (see Auto) |
"deny" | are refused with "no one was asked: this run was started with changes denied" |
Without approval, approveWrites: true means "allow", and anything else means "deny". If you send both, approval wins. A message sent into a thread that already has a run goes by that run's mode.
The other fields are optional: thread (or continue: true for the latest thread; leave both out for a new thread), computer, via (your app's name), and clientMessageId (send it again and the message isn't recorded twice).
Attach images with images: [{ data, mimeType }], where data is base64 (without a data-URL prefix). Send up to four PNG, JPEG, GIF or WebP images, each at most 5 MB. prompt may be empty for an image-only message. Images are saved as private blobs; authenticated agent.getContext returns hydrated image parts for history, including after a service restart.
Follow the run
GET /xrpc/ai.languid.agent.getRun?run=<run>&since=<next>This returns { run, thread, status, events, next, … }. status is running, done or error. Poll with since set to the last next. Two events matter here:
{ "seq": 4, "type": "approval", "id": "toolu_01…", "tool": "bash", "arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}", "computer": "laptop", "always": { "command": "rm" }, "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu" }
{ "seq": 5, "type": "decision", "id": "toolu_01…", "approved": true }approval: a call is waiting. Answer it with itsrequest.argumentsis a JSON string, and itscall_intentionis the agent's own words for what the call is for. For a script's write,toolis the XRPC method (such ascom.atproto.repo.putRecord) and the event has nocomputeroralways.decision: the call was answered.reasonis present when the answer didn't come from a person:"no answer in time","the run was stopped","approved by Auto"(with noapprovalevent before it), or the rule an "Always allow" saved.
List what's waiting
When your page loads, list what's waiting rather than replaying old events:
GET /xrpc/ai.languid.approval.list?agent=scout&thread=3n2js7khmj2aqthread is optional. The response lists open requests that something still waits on, newest first:
{ "approvals": [{
"uri": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu",
"cid": "bafyrei…",
"thread": "3n2js7khmj2aq",
"call": { "uri": "at://…/ai.languid.tool.call/3n2mivcwwy2cu", "cid": "bafyrei…" },
"tool": "bash",
"arguments": "{\"call_intention\":\"Delete old drafts\",\"command\":\"rm drafts/*.md\"}",
"intention": "Delete old drafts",
"computer": "laptop",
"always": { "command": "rm" },
"expiresAt": "2026-11-18T21:35:00.000Z",
"createdAt": "2026-11-18T21:30:00.000Z",
"run": "a04b7288-9a98-43e5-927d-37e65d054fa0"
}] }intention, computer and always are present only when they apply. A script's write also has n (which of the script's asks it is) and method. Follow run with getRun to see what happens after you answer.
Answer
POST /xrpc/ai.languid.approval.answer
{ "agent": "scout", "request": "at://did:plc:…/ai.languid.approval.request/3n2mivd4nlscu", "approved": true, "via": "my-app" }The response is {}, or { "rule": { "computer", "tool", "command"? } } when you sent always: true.
vianames your app in the approval record, in 64 characters at most. It defaults to"xrpc".409 NotWaiting: the request is unknown, already answered, past itsexpiresAt, or nothing waits on it any more. Drop it from your page.400:approvedisn't a boolean,alwaysis sent withapproved: false, oralwaysis sent for a request that has no rule to save.
Always allow
Offer it only when the request has always. always: true approves the call and saves a rule for that computer:
- with
always.command(bash), that command's leading words run there without asking; - without it (
edit,write), the whole tool runs there without asking.
The rule also approves any other call in the same run that is waiting and that the rule now covers. A script's record writes have no always: which writes need no asking is set on the agent's settings page, under Record writes.
A page that answers
- Start runs with
approval: "ask". - On load, call
approval.listfor the thread. While a run goes on, add a card for eachapprovalevent, and remove it on the matchingdecision. - On each card, show the intention as the heading, then the tool, the computer and the command (or the record being written).
- Offer Allow and Deny, plus Always allow when
alwaysis present (for example "Always allowrmon laptop"). Show the time left untilexpiresAt. - Answer from your server, so the token stays there. On a 409, drop the card.