Rules

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /sandboxes/rules.md.

A sandbox’s rules are one JSON document you sign. They decide which programs the agent may use, which of their instructions, how much it may spend through each, and where funds may go. The same programs define what the agent can read; see Read scope.

Build and sign

The rules builder on the sandbox’s page in the dashboard lists the supported programs. Turn on the ones the agent needs, set options for each, add any extra destinations and sign once with your wallet.

Change the rules the same way: edit, then sign again. An agent whose sandbox has no signed rules is refused with sandbox-rules-missing or sandbox-rules-unsigned. The CLI and the MCP server only show and check rules; they never build or sign them.

Rules v3

Version 3 is the only rules format.

{
  "version": 3,
  "programs": [
    {
      "programId": "6EF8rrecthR5Dkzon8Nwu78hRvfCKubJ14M5uBEwF6P",
      "name": "Pump.fun",
      "enabled": true,
      "instructions": ["buy", "sell"],
      "spendLimit": { "lamports": "1000000000", "windowSeconds": 86400 }
    }
  ],
  "transferAllowlist": ["<an address you control>"]
}

Field	Meaning
version	3
programs[]	The supported programs, each turned on or off with enabled
programId	The program’s base58 address
name	The program’s name, as the registry lists it
instructions	Optional. The instructions allowed for that program; left out, the registry’s safe set for it
spendLimit	Optional. The most SOL, in lamports (a decimal string), the sandbox may spend through that program per windowSeconds
transferAllowlist	Addresses funds may be sent to besides your own wallet (always allowed) and the sandbox’s own accounts

Instructions

Leaving instructions out allows the registry’s safe set for that program. Listing instructions narrows the program to exactly those.

Every sandbox also has a small baseline of plumbing, such as creating an associated token account, that it needs to hold tokens at all. sandbox_rules lists the baseline with the programs you enabled.

Spend limits

A spend limit caps the SOL that may leave the sandbox through one program in each window of windowSeconds. In the example, the agent may spend at most 1 SOL per day through Pump.fun. An action over the limit is refused with what remains in the window, so the agent can retry with a smaller amount.

There are no sandbox-wide per-action or per-window caps; set a spend limit on each program instead.

Destinations

SOL and tokens may leave the enabled programs only to your wallet, an address on transferAllowlist, or the sandbox’s own accounts. A transfer anywhere else is refused.

An address on the allowlist can receive any amount. Allow only addresses you control.

Exits and rent

Opening a position can create accounts that the sandbox’s wallet pays rent for. Some of that rent comes back when the agent exits the position. Some of it never does.

Program	Account	Rent	Comes back?
Kamino Lending	Obligation (initObligation)	About 0.0176 SOL (17,637,760 lamports)	Yes. A withdraw that leaves the obligation with no deposits and no borrows closes it, and the rent goes back to the wallet. There is no separate close instruction
Kamino Lending	User metadata (initUserMetadata)	About 0.0059 SOL (5,892,800 lamports)	No. Kamino Lending has no instruction that closes user metadata
Pump.fun	Volume tracker (user_volume_accumulator)	Set by the account’s size	Yes. close_user_volume_accumulator closes it and sends the rent back to the wallet

Rent is the network’s rent-exempt minimum for the account’s size. The amounts above are for the obligation’s 3,344 bytes and user metadata’s 1,032 bytes and can change if the network’s rent rate changes.

Treat Kamino’s user-metadata rent as a one-time cost of using Kamino Lending from the sandbox. A wallet has one user-metadata account, made by its first deposit. Later deposits reuse it, including after the obligation has closed. An agent should not plan to get that rent back.

Allow the way out

Exiting a position takes the program’s own exit instruction:

Program	Way in	Way out
Kamino Lending	Deposit (the first one also needs initUserMetadata and initObligation)	Withdraw: withdrawObligationCollateralAndRedeemReserveCollateral or withdrawObligationCollateralAndRedeemReserveCollateralV2
Pump.fun	buy (the first one opens the volume tracker)	sell for the tokens, then close_user_volume_accumulator for the tracker’s rent

The rules builder turns each program’s way out on with its way in. If you list a program’s instructions yourself, list the way out as well. An instruction left off the list is refused with sandbox-instruction-not-allowlisted, so the agent cannot unwind the position or get its rent back until you sign new rules.

Validate before you sign

a4 sandbox rules validate checks a rules file locally. Nothing is sent anywhere:

a4 sandbox rules validate rules.json
a4 sandbox rules validate - < rules.json   # from stdin

rules.json: valid Rules v3 (enabled: Pump.fun)

Misspelt keys are errors (spend_limit would otherwise be signed and ignored), as are program ids and addresses that are not base58 Solana addresses and limits of zero. Passing locally does not guarantee the API accepts every program: it must also be one the registry supports.

A document in an earlier format is refused with one line, by rules validate and by rules show / sandbox_rules (sandbox-rules-version-unsupported):

rules.json: Rules version 2 is no longer supported. Build and sign v3 rules in the dashboard (Sandboxes → Rules).

How the agent sees the rules

sandbox_rules (or a4 sandbox rules show) returns the rules as the agent uses them: each allowed program, its instructions with their argument types and accounts, the spend limits, the allowlist and the baseline. An account with a fill (fixed, wallet or derived) can be left out of an action: Arete fills it in.

That answer is the agent’s view ("view": "agent"), not the document the owner signed. Two numbers in it are easy to mix up:

• rulesFormat: the rules format, always 3.
• revision: which signing of the sandbox’s rules is active (1 after the first signing, 2 after the owner changes them once, and so on).

The guard pipeline a preview, an action result, a sandbox_action lookup or a history item names (guardPipeline, for example execute-v1; null or absent on older actions and on actions that never reached the guard) is neither: it is how Arete simulates and checks the transaction. The view carries the signed document as signedRules, so a4 sandbox rules show --json | a4 sandbox rules validate - checks the signed rules. A view without signedRules is refused rather than checked as a document. The only spend limits are the per-program spendLimits: a sandbox has no global caps.