Harnesses

​

Overview

​

Claude Code

​

OpenCode

kind = "environment"
name = "opencode-coder"
harness = "opencode"

[model]
deployment_id = "1a2b3c4d5e6f"   # any Veri deployment, OR:
# base_url = "https://api.example.com/v1"   # an OpenAI-compatible endpoint
# secret = "EXAMPLE_API_KEY"
# name = "my-model"                          # required with base_url

[permissions]
default = "allow"
rules = [
  { tool = "bash(rm *)", action = "deny" },
  { tool = "web.fetch", action = "deny" },
]

• Each message starts one opencode run --format json with the message on stdin and --session <id> to continue the conversation; the turn ends when OpenCode exits (exit 0 is success). Expect a second or two of start-up per turn. Nothing runs between turns, so pauses and checkpoints are cheap.
• The model is an OpenAI-compatible provider in /workspace/opencode.json at the session’s model base URL (OpenCode appends /chat/completions, which every Veri deployment serves). model.name sets the model it requests; for a Veri deployment it defaults to the deployment id. The key in the config is {env:VERI_MODEL_KEY}, a placeholder: the real key is added at the egress edge and never enters the sandbox. api.anthropic.com is not supported as an OpenCode model endpoint; use claude-code for it.
• The model’s limit is in the config too. context is the deployment’s served context (its --max-model-len), or 32768 when Veri cannot know it (a deployment launched without --max-model-len, or a base_url endpoint). OpenCode asks for at most min(8192, context / 4) output tokens per request, so the rest of the window stays for the conversation.
• MCP servers become remote entries in opencode.json (bearer tokens are placeholders too). Skills are written to /workspace/.opencode/skills/<name>/SKILL.md.
• Permissions become OpenCode’s permission map, in the same last-match-wins order (see the table below). ask is refused when you create the environment: a headless OpenCode run rejects every approval prompt on its own, and there is no way to pause the turn for you.
• Forking runs opencode run --session <checkpoint's session> --fork, so each child continues the conversation as its own session.
• Model-update checks, model catalog downloads, language-server downloads, default plugins and sharing are disabled. The package OpenCode installs into its config directories on start (@opencode-ai/plugin) is preinstalled in the image, in ~/.config/opencode and /workspace/.opencode, so a session start downloads nothing.
• Tool calls arrive when they finish: each produces an agent.tool_use and its tool.result together. Token usage is reported per model step (usage with scope: "step") and per turn (scope: "run").

​

Codex

kind = "environment"
name = "codex-coder"
harness = "codex"

[model]
deployment_id = "1a2b3c4d5e6f"   # any Veri deployment, OR:
# base_url = "https://api.example.com/v1"   # an endpoint that serves {base_url}/responses
# secret = "EXAMPLE_API_KEY"
# name = "my-model"                          # required with base_url

[permissions]
default = "allow"
rules = [
  { tool = "bash(rm *)", action = "deny" },
  { tool = "mcp.github.delete_repo", action = "deny" },
]

• Each message starts one codex exec --json (Codex CLI 0.162.1) with the message on stdin and resume <thread id> to continue the conversation; the turn ends when Codex exits (exit 0 is success). Nothing runs between turns, so pauses and checkpoints are cheap.
• Codex speaks only the OpenAI Responses API. For a Veri deployment it calls the deployment’s /v1/deployments/{id}/responses route, which vLLM serves natively (tool calls go through the deployment’s --tool-call-parser). A base_url endpoint must serve {base_url}/responses, and model.name sets the model Codex requests. The key is VERI_MODEL_KEY, a placeholder: the real key is added at the egress edge and never enters the sandbox. api.anthropic.com is not supported as a Codex model endpoint; use claude-code for it.
• The config is /workspace/.codex/config.toml (Codex’s home directory, CODEX_HOME, which also keeps its session history). It runs with approval_policy = "never" and sandbox_mode = "danger-full-access": the session container is the sandbox, so Codex’s own Linux sandbox is not used. model_context_window is the deployment’s served context (its --max-model-len), or 32768 when Veri cannot know it, and Codex compacts the conversation before less than min(8192, context / 4) tokens are left for the reply. Web search is off (it runs on OpenAI’s servers), and so are plugin sync, Codex’s bundled skills, analytics and update checks, so a session start downloads nothing.
• MCP servers become mcp_servers entries (streamable HTTP). Each server’s credential is a placeholder in an environment variable that Codex reads (bearer_token_env_var, or env_http_headers for a named header such as x-api-key). Skills are written to /workspace/.agents/skills/<name>/SKILL.md.
• Permissions: Codex runs every tool it has unless a rule forbids it, so default must be allow and the rules that take effect are deny rules (see the table below). Command rules become Codex execpolicy prefix rules in /workspace/.codex/rules/veri.rules: Codex matches the leading words of every command it reads out of a shell script, so bash(git push *) and bash(git push) both forbid git push --force. A forbidden command does not run: Codex hands the rejection back to the model, and the command does not appear as a tool call in the transcript. Like every command rule, this guards against mistakes, not against an agent set on getting around it; egress rules and secret scoping are the boundary.
• ask is refused when you create the environment (harness_does_not_support_ask): codex exec cancels every approval request on its own.
• Forking runs codex exec fork <checkpoint's thread>, so each child continues the conversation as its own thread.
• Tool calls arrive as agent.tool_use when they start and tool.result when they finish, with kind command (and the exit_code), file_change, mcp, todo or web_search. Reasoning arrives as agent.thinking. Token usage is reported once per turn (usage with scope: "turn", and scope: "run"); retried model calls are error events with subtype: "api_retry". Codex’s warnings (every model it has no metadata for triggers “Model metadata for <name> not found”) are kept as agent.raw with native_type: "warning".

​

LangGraph and CrewAI

kind = "environment"
name = "support-graph"
harness = "langgraph"            # or "crewai"

[model]
deployment_id = "1a2b3c4d5e6f"   # any Veri deployment, OR:
# base_url = "https://api.example.com/v1"   # an OpenAI-compatible endpoint
# secret = "EXAMPLE_API_KEY"
# name = "my-model"                          # required with base_url

[agent]
repo = { url = "https://github.com/acme/agents", ref = "v1.2.0", subdir = "support" }
entry = "support"                # LangGraph: a graph id from langgraph.json
# entry = "support_crew.crew:SupportCrew"   # CrewAI: package.module:factory
# requirements = "requirements.txt"         # default: requirements.txt when present

[permissions]
default = "allow"
rules = [{ tool = "mcp.github.delete_repo", action = "deny" }]

• The first message starts the mediator. It clones agent.repo at ref into /workspace/agent (the repository’s host is allowed automatically, for git’s requests on that repository’s path only), installs the requirements into a virtualenv at /workspace/.veri/venv (PyPI is reachable under the default coding egress preset), then loads entry. The repository must be public for now: private repositories need GitHub access, which is coming soon. If any of this fails, the session fails with an error event whose source is harness_setup and whose message says what went wrong. A resumed, rolled-back or forked session keeps /workspace, so it does not fetch or install again.
• Each message is one run: a LangGraph astream over the graph’s node updates, or a CrewAI Crew.kickoff. Messages your nodes return become agent.message, tool calls agent.tool_use + tool.result (kind: "mcp" for MCP tools), reasoning content agent.thinking, and each model call’s token usage usage with scope: "message" (plus a scope: "run" total per run). What your code prints goes to the harness log, not the transcript.
• LangGraph: the graph runs with Veri’s checkpointer (SQLite at /workspace/.veri/langgraph.sqlite, replacing any checkpointer your graph was compiled with), and the conversation is the thread named after the session id, so it survives pauses and resumes. A fork copies the checkpoint’s thread into the child’s own. The graph’s input state should have a messages key (MessagesState); each message is added to it as a human message. interrupt() (human-in-the-loop inside the graph) is not supported: the run ends with an error.
• CrewAI: your crew gets inputs = {"message": <the message>, "history": <the earlier turns, as text>}, so task descriptions can use {message} and {history}. A factory entry is called for every message, so each run starts from a fresh crew. A crew has no conversation to fork.
• The model: OPENAI_BASE_URL / OPENAI_API_KEY and VERI_MODEL_BASE_URL / VERI_MODEL_KEY / VERI_MODEL_NAME point at the session’s model, so stock ChatOpenAI(model=os.environ["VERI_MODEL_NAME"]) or crewai.LLM(model="openai/" + os.environ["VERI_MODEL_NAME"]) work unchanged. The key is a placeholder: the real key is added at the egress edge and never enters the sandbox. veri_pyagent.chat_model() and veri_pyagent.crewai_llm() return models already wired up, with an output budget that fits the deployment’s served context.
• MCP servers: await veri_pyagent.mcp_tools() returns them as LangChain tools; veri_pyagent.mcp_servers() returns them for crewai.Agent(mcps=...). CrewAI names an MCP tool after its server’s URL, so for crewai each MCP server must be addressed by hostname, not IP address (400 otherwise).
• Permissions: these frameworks have no built-in shell, file or web tools (the ones your code adds are yours to govern), so the rules Veri enforces are MCP rules: mcp, mcp.<server> and mcp.<server>.<tool> (globs allowed in the tool name), last match wins, and a denied tool is left out of the tools the helpers hand your agent. default must be allow; shell, file, web and git rules are refused when you create the environment. Egress rules and secret scoping are the boundary for everything your code does.
• ask is refused when you create the environment (harness_does_not_support_ask): neither framework can pause a run for a human decision.

​

Custom

kind = "environment"
name = "my-agent"
harness = "custom"

[custom]
# Fetch your code and run it (GitHub, npm and PyPI are reachable by default).
command = ["sh", "-c", "[ -d agent ] || git clone --depth 1 https://github.com/you/agent agent; exec python3 -u agent/agent.py"]
workdir = "/workspace"            # default; must be /workspace or under it

[model]
deployment_id = "1a2b3c4d5e6f"

• Your process starts on the first message and keeps running. If it exits, the next message starts it again, so a command that fetches code should tolerate the checkout already being there (as above). A checkpoint, rollback or resume restarts it too: the files survive, the process does not.
• command is up to 64 arguments of up to 4096 bytes each, so a short script can also be passed inline (["python3", "-c", "..."]).
• Each message arrives as one JSON line on stdin: {"type": "user.message", "text": "..."}.
• Every line you print to stdout that is a JSON object with one of these types is recorded as that event, with the other fields as its payload: agent.message, agent.thinking, agent.tool_use, tool.result, usage, error, agent.raw. Any other JSON line is recorded as agent.raw, and any other text line as agent.message.
• Print {"type": "run.completed"} when you have answered (add "is_error": true or a "stop_reason" if you like). Exiting also ends the turn: exit 0 is success, anything else an error with your stderr attached.
• The model: VERI_MODEL_BASE_URL (OpenAI-compatible for a Veri deployment), VERI_MODEL_KEY (a placeholder that is swapped for the real key on requests to that host only; send it as Authorization: Bearer $VERI_MODEL_KEY) and VERI_MODEL_NAME (model.name, or the deployment id).
• MCP servers are in /workspace/.mcp.json and skills in /workspace/.veri/skills/ for your program to use as it sees fit.

import json, os, subprocess, sys, urllib.request

base = os.environ["VERI_MODEL_BASE_URL"].rstrip("/")
key = os.environ["VERI_MODEL_KEY"]
model = os.environ.get("VERI_MODEL_NAME") or "default"
history = []

def emit(**event):
    print(json.dumps(event), flush=True)

for line in sys.stdin:
    text = json.loads(line)["text"]
    if text.startswith("!sh "):
        emit(type="agent.tool_use", id="sh-1", name="sh", input={"command": text[4:]}, kind="command")
        p = subprocess.run(text[4:], shell=True, capture_output=True, text=True)
        emit(type="tool.result", tool_use_id="sh-1", content=p.stdout + p.stderr,
             is_error=p.returncode != 0, exit_code=p.returncode)
        emit(type="run.completed")
        continue
    history.append({"role": "user", "content": text})
    req = urllib.request.Request(base + "/chat/completions",
        data=json.dumps({"model": model, "messages": history}).encode(),
        headers={"Authorization": "Bearer " + key, "Content-Type": "application/json"})
    reply = json.load(urllib.request.urlopen(req))["choices"][0]["message"]["content"]
    history.append({"role": "assistant", "content": reply})
    emit(type="agent.message", text=reply)
    emit(type="run.completed")

​

Permission names