Wire this repository to a Veris environment, once; re-running skips what
still holds. Two transports, one contract each:
- Container (default). The code is never modified and never told —
reroutes its outbound HTTP(S) into a sandbox from outside
the process. Leaves (the exact
invocation), , and only when
deriving an image took real work.
- Direct (). For an application whose own configuration reads
each service's base URL from the environment variable the platform names
(its ) — then pointing those variables at a sandbox IS the
shipped code path, and no proxy or docker is involved.
reference/direct.md carries the contract; step 2
gates entry. Leaves with .
in this skill's directory checks the preconditions and
reports
every one that fails in a single run. Under the direct tier add
, which skips the binary/docker/image checks; without it all three are
required. An environment id given with the command overrides
; service names given with the command seed the step-3
create question.
Where to run it from. On a first run nothing is staged yet, so invoke it from
this skill's own directory: derive that absolute path from the path of the file
you are reading, confirm it with
test -f <that path>/scripts/preflight.sh
, and
run it there. Step 5 then copies it into
, and every later run —
here, and in
and
— uses
sh .veris/bin/preflight.sh
instead.
Pass the version you are running. Add
to every
invocation. A staged copy cannot know which version is loaded, so unless it is
told it cannot notice that it is out of date; without the flag it says
rather than guessing.
1. Credential
(with
first when that tier was
requested) reports the credential first. If
is not
set, say exactly this and end the turn:
Run this in your terminal, then tell me when it's done:
echo 'export VERIS_API_KEY=<your key>' >> ~/.zshrc && source ~/.zshrc
(
when
is bash.) On their reply, run preflight again —
it reads the variable in a fresh shell. Say "VERIS_API_KEY is set"; never
print the value; write it nowhere. The
MCP server read the
environment at session start: say a restart is needed before its tools
work; nothing here needs them.
2. Preflight
It names every missing precondition in one pass, each with its fix on the same
line — binary, docker, environment. Fix them together, then run it again; a
check whose own precondition failed reports that rather than a second, derived
failure. Installing
the binary: ask first, never over a working one. What preflight cannot
satisfy stops setup — no base-URL override, hand-written config, or run
without
; each proves a code path that is not the one that ships.
is not that fallback, and step 2 refuses it unless it holds: every
service base URL the code uses must come from its environment (the exact
variables), with no vendor hostname hardcoded on the tested path.
Check the code, not the claim — a hardcoded host means the proxy tier, full
stop. What
skips is the binary, docker, and the image; credential
and environment checks run unchanged.
3. Environment
set →
GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID
(
; or the
MCP tool) must list the services this code
calls. Not set →
GET ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments
lists the engineer's;
ask which. Create one only after asking, and in the question name the
services you inferred from the code — the reply may add or drop names;
check each against
, the catalogue. Then
{"name":…,"services":[…]}
.
4. Image (container tier)
Skip this step under
. Every container run uses
. Derive one from the repository's own test setup —
anything that runs the tests, nothing Veris-specific;
only if that took real work.
reference/transport.md
only when the smoke run fails on what the proxy hands the workload.
5. Record
Under
: create a sandbox (
, or
POST ${VERIS_API_BASE:-https://svc.api.veris.ai}/v1/environments/$VERIS_ENVIRONMENT_ID/sandboxes
), read
each service's
and
from
, and set those
variables where the application's environment actually comes from — a
platform Secrets pane, an env file, an export. Some panes are human-only
(Replit's is — measured): then name each variable and value and wait for the
engineer to paste. Write
with
,
,
, and the variable names;
reference/direct.md
carries sandbox lifetime and rotation. Skip
.
Container tier: write
and
:
sh
#!/usr/bin/env sh
# Written by /veris-sim:setup. Flags before -- pass through; a command after -- replaces the default.
# VERIS_SANDBOX_ID set: attach to that sandbox (build and fix make one per task). Unset: a fresh one per run.
set -eu
if [ -n "${VERIS_SANDBOX_ID:-}" ]; then target="--sandbox $VERIS_SANDBOX_ID"
else target="--environment ${VERIS_ENVIRONMENT_ID:?}"; fi
run() { exec veris-proxy run $target --image myrepo-veris-tests -v "$PWD:/work" -w /work "$@"; }
for arg in "$@"; do [ "$arg" = "--" ] && run "$@"; done
run "$@" -- make integration
Mounts stay under the repository tree or a known dependency cache. Tell the
engineer both files exist and are worth committing.
Either tier, also carries what later tasks would otherwise
re-derive, each measured here rather than guessed:
- — the version you passed to preflight;
- — where this repository's production source lives;
- and — the repository's own build, and the
directories it writes. Without them a later task cannot tell a fresh build
from a stale one, and says so instead of pretending otherwise;
- — filled in at step 6: the smallest command that produced a
non-empty receipt. Most repositories have vendor-facing tests that cannot
produce one at all; naming the one that can is worth more than a paragraph
about the ones that cannot.
Stage the scripts. Copy
from this skill's directory
and
and
from the reference directory
beside it into
. From here on every command runs them from that one
path, so nothing has to resolve an install location mid-task. Re-running setup
re-stages them, which is how a version mismatch is repaired.
Ignore what is generated, keep what is measured. Append these to
if absent — targeted lines, never a blanket
, which would
take
and
with it:
gitignore
.veris/bin/
.veris/tasks/
Then ask once, and record the answer as
: a task's diagnosis,
ledger and execution record are rendered into the change description
(
, the default), kept on disk only (
), or committed under
(
— say plainly that this merges into the
default branch and accumulates one directory per task). Under
, drop the
line above.
6. Prove it
Container tier:
.veris/run.sh -- <the smallest test that calls the dependency>
. The proxy prints a receipt — requests per service; an empty one
exits 3.
Not done until the receipt names the environment's service with a
count above zero. Write the command that did it into
as
, exactly as run.
Direct tier has no receipt; the twin's trace is the trust anchor. Run the
smallest piece of the application that calls the dependency, then
GET {control_url}/veris/requests
on that service.
Not done until the
trace shows the application's own calls with a count above zero — a green
smoke with an empty trace means the app called the real vendor, not the
sandbox. A certificate error against a mapped host is an SDK bundling its own
CA —
../veris-reference/trust.md; other signals —
../veris-reference/troubleshooting.md.
Either tier: alongside
, write
— what this
session measured about the environment that a later task will need.
and
read it first; a fact left only in this transcript dies with it.
Use these headings, and write measured under each or not measured — never
leave one out, because a heading with nothing under it is itself a finding, and
the next task can decide whether to go and get it:
- What this twin cannot represent. No endpoint lists a service's coverage
(troubleshooting.md), so whatever you
established here is the only record of it.
- Identity and matching. Which fields the service treats as the same record,
and any normalizing, truncating or joining it does on the way.
- Errors and the dedup key. Which failure classes bind to an
idempotency/dedup key and replay on reuse, and which leave the key free. A fix
that retries is built on this answer.
- Credentials and versions. The shape a key must have, the API version
pinned, and anything a made-up value gets away with.
- Where the repo's own tests do not reach the vendor. Suites that mock
in-process produce a green with an empty receipt.
- Anything the twin got wrong.
Report the receipt line; then step 7.
7. Files, when the application works with them
Skip this when the application does not work with files. When it does —
uploads, attachments, documents — set them up once, so every later
sandbox starts with the files instead of each task loading them again:
- Create a sandbox (), or use the direct-tier one.
- Seed the rows the files hang off — an owner, a folder, a repository — in
the shapes names, or pick an owner already in the sandbox.
- Post the files with that owner through where the
manual shows it, or through the vendor's own upload API where files are
attachments — rows first, files second, as
../veris-reference/state.md lays out.
- Read them back and check the SHA-256 in each row against the local file.
- Ask the engineer, then . This is the one place a
command promotes, and only with a yes; and never do.
- Write what is in the sandbox — owners, paths, hashes — into .
Rows-only state is cheap to seed per task and do not need this. Report
and stop:
or
takes the task.
Ask before installing the binary or sending repository code anywhere new.