STACK
MENU
DOCS / CONTROLS / YOUR OWN DECISION SERVER

Your own decision server

How you have a server of your own decide each action of your agents: setting the address, what STACK sends, what your server answers, and what happens when it does not. What this is and what it costs is on Controls.

Before you start

  • You need a server with a public https address. It needs no controls subscription.
  • Only the owner or an admin sets this up. An agent cannot.

Set the address

bash
npx @getstackrun/cli control-socket set-decision https://decide.example.com/stack
  • The address must be https on a public host, with no login in it and no query. STACK follows no redirects.
  • The first set prints a signing secret once. Store it. It cannot be read back from the terminal or the SDK.
  • In an AI client the secret is never shown in the chat. The tool returns a link that opens it once in the Console.
  • A new address decides nothing until it is verified.
  • The tool is stack_set_control_decision_address. From code: stack.controlSocket.setDecisionAddress({ url }).

Write the server

STACK sends a signed request for each action and waits for a signed answer. The SDK has the two helpers:

typescript
import { createServer } from 'node:http';
import { verifyControlSocketRequest, signControlSocketAnswer } from '@getstackrun/sdk';

const secrets = [process.env.STACK_DECISION_SECRET!];

createServer(async (req, res) => {
  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk as Buffer);
  const body = Buffer.concat(chunks).toString('utf8'); // the body exactly as received

  const check = verifyControlSocketRequest({ headers: req.headers, body, secret: secrets });
  if (!check.ok) {
    res.statusCode = 401;
    return res.end();
  }
  const r = check.request;

  // Your rule. Here: email may go only to example.com.
  const recipients = (r.target['recipients'] as Array<{ domain?: string }> | undefined) ?? [];
  const outside = r.action.type === 'email.send' && recipients.some((x) => x.domain !== 'example.com');
  const deny = !r.test && outside; // always allow a test request

  const answer = signControlSocketAnswer({
    decisionId: r.decision_id,
    requestDigest: r.request_digest,
    verdict: deny ? 'deny' : 'allow',
    ...(deny ? { reason: { code: 'external_recipient', message: 'Only example.com recipients' } } : {}),
    secrets,
  });
  res.writeHead(200, { 'content-type': 'application/json', ...answer.headers });
  res.end(answer.body); // the body exactly as signed
}).listen(8080);

What STACK sends

  • action.type - the kind of action, for example email.send, sms.send, card.checkout, wallet.payment, model.call, proxy.call or tool.run.
  • agent, account and actor - which agent, in which account, and whether an agent, the owner or a team member is acting.
  • target - the facts of the action. For an email: every recipient with its domain. For a payment: the payee and the amount. For a model call: the provider and the model.
  • amount - the most the action can cost, when it costs money.
  • purpose.agent_stated - what the agent says it is doing. Treat it as a claim, not a fact.
  • test - true for a check you started yourself.

The request never carries message text, subjects, prompts, model output, commands, page text, card numbers or logins.

What your server answers

  • HTTP 200, signed with the same secret. signControlSocketAnswer builds the body and the headers.
  • verdict is allow or deny.
  • reason is optional: a short code, and a message of up to 200 characters that the agent sees.
  • retry is optional: a ref, and how many seconds to wait. A deny with retry means "ask me again later", for example while a person approves. The agent sends the ref back when it tries again.
  • The answer must arrive within the time limit: 1.5 seconds unless you set another, from 0.3 to 2 seconds (--timeout-ms).

Switch it on

bash
npx @getstackrun/cli control-socket verify decision

Verify sends one real signed request marked as a test. Your server must answer allow. From that moment your server decides. If hosted controls were deciding before, this replaces them and needs your approval in a browser. control-socket test decision sends the same request at any time and changes nothing.

When your server does not answer

  • By default the action is refused. The agent gets 403 CONTROL_SOCKET_UNAVAILABLE and is not charged for the action.
  • You can change that to allow: control-socket on-unavailable allow. It counts as loosening and needs your approval in a browser. Changing back to refuse applies at once.
  • Only an answer that never came follows that setting. A forged or unreadable answer is always refused.
  • After five failures in a row, or when more than half of the last 20 requests failed, STACK stops asking for 15 seconds, then tries one request.
  • After 50 answers in a row with a bad signature the address is paused. Verify it again to resume.

Choose what is asked

bash
# Ask only about email, texts and payments.
npx @getstackrun/cli control-socket checked-types email.send sms.send card.checkout wallet.payment

# Ask about everything again.
npx @getstackrun/cli control-socket checked-types --all

Every kind is asked by default. Taking a kind off the list counts as loosening and needs your approval in a browser.

See what was decided

bash
npx @getstackrun/cli control-socket decisions --verdict deny

The tools are stack_list_control_decisions and stack_get_control_decision. Each decision shows the action, the verdict, the reason, how long your server took, and whether it was charged. Decisions are kept 90 days, and the request behind a refused or unanswered one 30 days.

Replace the secret

control-socket rotate-secret decision gives a new secret. The old one keeps working for 24 hours, so give your server both during the change.

What is charged

Each answer your server gives, allow or deny, is charged at the own-server price. A request your server did not answer is not charged, and neither are tests. An action your server refuses is not counted as an action.

When setup is refused

  • 400 CONTROL_SOCKET_ADDRESS_REFUSED - the address is not https on a public host, or carries a query.
  • 403 GOVERNANCE_APPROVAL_REQUIRED - the change needs your approval in a browser. The answer carries the link.
  • 404 NOT_FOUND - there is no address to verify, test or clear.
  • 400 VALIDATION_ERROR - the time limit is outside 300 to 2,000 milliseconds, or a kind is not one STACK asks about.

Reference

Every field of the request and the answer is on Controls. To have STACK decide from a policy instead, see Policies.

Your own decision server | Docs