> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a harness for Replay Environments

> Bundle your agent repository with moda harness register so Moda can run your real harness in a sandbox with outbound network denied.

A Replay Environment runs your real agent harness, not a reconstruction of it, in a sandbox where outbound network is denied. Databases and queues run as disposable local services, external APIs are answered by emulators or recorded fixtures, and model calls go to an approved inference lane. To build one, Moda needs your code. `moda harness register` collects it, shows you exactly what it collected, and uploads it.

This is the runnable counterpart to [`moda registry`](/harness/registry), which describes your agents, prompts, and tools. Do both. A registration links to the registry harness version that was current when you registered.

## Preview the bundle

```bash theme={"dark"}
moda harness register --dry-run
```

A dry run uploads nothing and needs no API key. It prints:

* **Included**: file and byte counts by category (source, lockfiles, package manifests, deploy config, containers, migrations, tests, prompts, and so on).
* **Excluded**: every path left out, with the reason. The contents of these paths never leave your machine.
* **Git-ignored but present**: other ignored paths, by name only, in case a build needs them.
* **Environment variables**: every name found in code and example files, with a proposed classification. Values are never read.
* **Runtimes, dependencies, and migrations**: what the harness runs on, the services it calls with the adapter Moda proposes for each, and the migrations it would run.
* **Gaps**, and **what Moda will still need from you**.

The manifest and dependency map are written to a temporary directory named in the report, so you can read exactly what would be sent.

## What is collected

The bundle is the whole git repository the harness lives in, including uncommitted and untracked files. The policy is to take more than a build needs: Moda can shrink a bundle later, but it can't recover files that were never sent.

| Left out | Reason recorded |
| - | - |
| `.env`, `.env.*` (except `.env.example` and similar), `*.pem`, `*.key`, `id_rsa`, `.npmrc`, `.netrc`, service account files | `secret_path`: the file is never opened |
| Files whose contents match a credential rule (cloud keys, private keys, provider API keys) | `secret_content`: the rule name is recorded, never the match |
| `.git`, `.hg`, `.svn` | `vcs_internal` |
| Git-ignored `node_modules`, `.venv`, and other installs a lockfile reproduces | `dependency_install` |
| Git-ignored caches and build output (`dist`, `.next`, `__pycache__`, `.turbo`) | `regenerable_output` |
| Files over the size budget | `size_limit` |
| Symlinks that point outside the repository | `symlink_escape` |
| Paths listed in `.modaignore` (gitignore-style patterns) | `user_exclude` |

## Declare how it runs

Tell Moda how the harness starts and which env vars route its model calls. Pass env var names, never values.

```bash theme={"dark"}
moda harness register support-agent \
  --model-base-url-env=OPENAI_BASE_URL \
  --model-env=OPENAI_MODEL \
  --model-api-key-env=OPENAI_API_KEY \
  --entry -- node dist/server.js
```

`--entry` takes everything after `--` as the command, so put it last. `--entry="node dist/server.js"` also works.

| Flag | Purpose |
| - | - |
| `[name]` | Harness name. Defaults to the `package.json` name, then the directory name. |
| `--root=<dir>` | Directory of the harness inside the repository. Defaults to the current directory. |
| `--mode=source\|sealed` | `source` (default) builds from the uploaded source. `sealed` runs an image you built; pass `--image=<ref>@sha256:<digest>`. |
| `--entry -- <cmd...>` | The command that starts the harness the way production does. |
| `--model-base-url-env`, `--model-env`, `--model-api-key-env` | Env var names for the model base URL, model id, and API key. |
| `--dry-run` | Collect and report only. |
| `--json` | Machine-readable report. |

## Register

Run the same command without `--dry-run`. The CLI uploads the bundle, manifest, and dependency map straight to Moda's object storage on short-lived presigned URLs (your API key is not sent with them). Moda then checks each upload's sha256 and size, analyzes it, and prints the registration id, status, and a dashboard link.

```bash theme={"dark"}
moda harness registration status <id>
moda harness registration list
```

| Status | Meaning |
| - | - |
| `uploading` | Created; uploads not yet verified. |
| `analyzing` | Uploads verified; Moda is computing the checklist. |
| `needs_input` | The checklist has blocking items for you. |
| `ready` | Nothing blocks building the environment. |
| `compiling`, `validating` | Building the environment and smoke-booting it. |
| `failed` | Analysis or the build failed; the reason is shown. |
| `retired` | Deleted. The bundle bytes are removed and only a tombstone remains. |

## The checklist

Open the registration in the dashboard to work through what Moda still needs:

* **Env var classifications**: confirm or correct each proposed classification (`secret`, `config`, `dependency_endpoint`, `model_endpoint`, `model_credential`). Only names Moda could not classify block.
* **Dependency adapters**: approve or reject the adapter proposed for each dependency (a real local engine, a provider emulator, a receipt-compiled simulator, a recorded fixture, or remote staging), or pick another.
* **Migrations**: approve running them against a disposable database.
* **Entrypoint and model routing**: when they were not declared and could not be detected.
* **Gaps**: things the detector knows it could not resolve, and, after a smoke boot, files, env vars, or network calls the harness needed but did not have.

Decisions are kept when Moda re-analyzes the same registration.

## Have your coding agent do it

`moda registry prompt` prints the brief for your coding agent. Its last part runs `moda harness register --dry-run`, reviews the exclusions and gaps with you, declares the entrypoint and model routing, and registers once you approve.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.