Sandboxed Scripting for Agents

Readable Scripts

ClankTalk is designed for your agent to write and you to read. It is optimized for human understanding, while allowing agents to get work done efficiently.

for f in ./config/*.json; do
  v=$(jq -r '.version' "$f")
  if [ "$v" -lt 2 ]; then
    jq '.version = 2' "$f" > "$f.tmp" \
      && mv "$f.tmp" "$f"
  fi
done

for file in ./config/*.json
  set config to the file's text as json
  if config's version is less than 2
    set config's version to 2
    write config as json to the file
  end
end

A Controlled, Observable Runtime

Giving an agent a shell is pretty crazy when you think about it. ClankTalk gives it a controlled & observable runtime instead:

• File access stays inside the project root
• Secrets and config that runs code, like .env and .git/, are off limits
• You can lock down fetch with your own rules
• Step budgets control run away loops

write 'hello' to ../../etc/hosts
# error: outside the project root

Define Your Agent's Tools

You can define new tools in AGENTS.talk for your agents that allow you to minimize the surface area needed to get work done. Agents aren't allowed to touch .talk files or hidden files by default.

tool site_server
  start 'npm run dev' as 'site' in a sandbox
end

OS Sandboxes for Programs

When available (MacOS, Linux) and needed, tools can run programs in OS level sandboxes.

tool run_tests
  run 'npm test' in a sandbox with local network
end

Secret Secrets

Allow your agents to use secrets without seeing them in a controlled manner.

Secrets come from .env, which scripts cannot read, and can only be used in places defined in your AGENTS.talk.

set auth to 'Bearer ' + secret GITHUB_TOKEN
fetch https://api.github.com/user with headers: { Authorization: auth }

print auth
# Bearer <secret GITHUB_TOKEN>

print auth contains 'ghp'
# error: a secret cannot go into 'contains'

Coherent Security Policy

You can define a sophisticated security policy for your project (or company!)

In AGENTS.talk, allow lines say what your agent can reach, and hooks run logic before and after every agent action.

allow env PATH, HOME
allow changes to @/.github/
allow fetch from 'api.github.com', 'registry.npmjs.org'
allow secret NPM_TOKEN for run

before git
  if the git's operation is 'commit'
    ask 'Commit ' + the git's files + '?' with 'yes' or 'no'
    if the result is not 'yes'
      reject 'The human said no'
    end
  end
end

Audit Logs

ClankTalk adds observability to your agent's sessions by keeping a log (default of three days) of every action your agent takes.

== 10:42:01  script 12 (main)  done  4 steps ==
  replace
  | total = price * qty
  with
  | total = price * qty * (1 - off)
  in @/src/cart.js

  run_tests
--
10:42:01  read     src/cart.js
10:42:01  replace  src/cart.js  undo saved
10:42:01  tool     run_tests
10:42:09  run      npm test     code 0, 7.9 s, from run_tests

Undo

The ClankTalk runtime makes an undo stack available to allow you or the agent to back out any changes made on disk easily, even if you aren't using git.

undo 2
undo changes to ./src/config.js

Hardened Git

Git tools come built in, with the parts that run programs turned off. This allows you to use the 80% of git that matters without the 20% of git that can be used to compromise you.

git switch to new branch 'fix-retries'
git commit [./src/config.js] with 'More retries'
git push

Taint Tracking

Taint tracking allows you to follow when outside, untrusted and "tainted" text has entered into the agent's environment, and to control how things work after that happens.

fetch https://example.com/issues/42
git push
# asks you: Push to origin? 1 untrusted input
#   is not approved: https://example.com/issues/42

ClankTalk taints the whole session, not just the text, and keeps a copy of each untrusted input your agent read. You can review and approve them from your terminal, with npx clank-talk taint, or right in your harness, with taint review.