Board: agent sandbox

The goal is to show a coding agent getting the same toolchain as the human, on a laptop or in a sandbox, with skills that teach it Flox and credentials supplied at activation rather than stored.

This page is drawn from https://flox.dev/deterministic-agents/, https://raw.githubusercontent.com/flox/flox-skills/main/README.md, https://flox.dev/blog/focusing-on-the-code-not-the-cruft/, https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-2/, https://flox.dev/docs/man/flox-activate, https://flox.dev/docs/man/flox-auth, https://flox.dev/docs/concepts/activation and https://flox.dev/docs/concepts/secrets-management.

Whiteboard outcome

When you are done, the board shows an agent harness inside a sandbox, a Flox environment under it, a skills box beside it, and a secrets hook that fills credentials at activation.

Before you draw: three questions

1. Which harness: Claude Code, Codex, Gemini CLI, another?
2. Where does it run: a laptop, a devcontainer, a hosted sandbox?
3. Which secrets and services does it need?

Draw it in 8 steps

1. Draw a tower: harness on top, sandbox, then Flox environment. Say: “The harness is probabilistic by design. The environment under it should not be” (https://flox.dev/deterministic-agents/).
2. Inside the base, draw manifest.toml with python, nodejs, postgresql. Say: Flox “pins one manifest to the same toolchain under every agent harness, on your laptop and in the cloud” (https://flox.dev/deterministic-agents/).
3. Draw the launch line flox activate -- claude. That form execs the command after activation, skipping [profile] scripts (https://flox.dev/docs/man/flox-activate). The vendor page shows this launch (https://flox.dev/deterministic-agents/).
4. Write the non-interactive rules beside it. Agents usually run commands through non-interactive shells. Three things matter: flox activate -c CMD runs a command in the environment; flox activate -- CMD execs it without [profile]; and in-place eval "$(flox activate)" “Produces commands to be sourced by the parent shell” (https://flox.dev/docs/man/flox-activate). Aliases do not help here: “most shells will not (by default) expand aliases when run non-interactively”, and the hook.on-activate script cannot use them (https://flox.dev/docs/concepts/activation).
5. Draw a skills box on the right. Say: the flox-skills plugin has three skills, flox, floxify and flox-debug, for Claude Code, Codex and other agents (https://raw.githubusercontent.com/flox/flox-skills/main/README.md). floxify onboards an existing repo; the README says the skills “activate the environment and exercise its services before calling a setup done” (https://raw.githubusercontent.com/flox/flox-skills/main/README.md).
6. Draw proof under the skills box. In the developer-advocate write-up, floxify turned a Mastodon checkout into a six-service dev stack, and the skills ran on Claude Code (https://flox.dev/blog/focusing-on-the-code-not-the-cruft/). Part 2 shows Claude Code floxifying Node-RED in “just a few minutes” (https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-2/). Both are vendor-authored, so [verify] against your own repo.
7. Draw a safe on the right and a hook arrow into the sandbox. Say: the vendor page describes a hook that fetches credentials when the environment comes up, so nothing is written into a manifest, an image or the repo (https://flox.dev/deterministic-agents/). The docs say secret values are never written to manifest.toml and exist only in the active Flox shell (https://flox.dev/docs/concepts/secrets-management). For headless logins use a token file: login “does not open a browser or prompt for input” (https://flox.dev/docs/man/flox-auth).
8. At the bottom, write the rule: Swap the harness, change the sandbox: the base layer does not move. (https://flox.dev/deterministic-agents/)

flowchart TB
  H[Agent harness<br/>Claude Code or Codex]
  SK[Skills<br/>flox, floxify, flox-debug]
  subgraph SB[Sandbox<br/>devcontainer or hosted]
    E[Flox environment<br/>manifest.toml and lock]
  end
  H -->|flox activate -- agent| E
  SK -.teach the agent.-> H
  SEC[Secrets store] -.activation hook, run scoped.-> E

What can go wrong

• Sandbox and Flox are separate jobs. The vendor page says Flox “does not replace the tools your agents run in” and that “The devcontainer or Docker box stays as the isolation boundary” (https://flox.dev/deterministic-agents/). Flox pins what runs inside; it is not the isolation boundary by itself.
• Secret lookups can fail quietly. An unresolved secret reference prints a warning and leaves the variable unset while activation still succeeds (https://flox.dev/docs/concepts/secrets-management).
• Package counts differ by page. The agents page says “215,000+ packages”, while a Flox blog post says “millions of package-version combinations” [verify which is current] (https://flox.dev/deterministic-agents/, https://flox.dev/blog/reproducible-development-environment-in-any-repo-part-1/).

What they will ask