# 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](/product/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](/docs/api/controls). To have STACK decide from a policy instead, see [Policies](/docs/controls/policies).
