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

# Sandbox environment and test helpers

> What the sandbox does with an sk_test_ key: mocked character builds in about 30 seconds, force_fail to test failures, test licenses and test webhook events.

The sandbox is a separate environment for building and testing an integration. Use an `sk_test_` key and every call works as it does in production, except that nothing runs on a GPU and nothing is charged.

## What changes in sandbox

* **Characters** are validated exactly as in production: the face count, the 20-file limit, file types, that the uploads are yours, and the description policy check. Neither environment checks that an upload's bytes arrived; in production a missing file fails the build later. After about 30 seconds the character turns `ready` with a sample `.char` you can download. The sample holds a placeholder image and no model, and its manifest marks it as a sandbox file.
* **Runs** (`POST /v1/runs`, with the `runs:write` scope) go through the same character and license checks as production, then render a placeholder about 10 seconds later: a grey PNG for an image workflow, a one-second clip for a video one. The workflow itself is not run.
* **Builds and credits** are never touched.
* **Licenses** are real and signed with a sandbox key. Their keys start with `lic_test_`, and verify always answers `"env": "sandbox"` and `"test": true`.
* **Data** never crosses environments. A sandbox key cannot see production characters or licenses, and a live key cannot see sandbox ones.

## Testing failures

Put `force_fail` anywhere in a character's `description`. The build fails after the usual delay, its status becomes `failed`, and `char.failed` is sent. For a run, put `force_fail` in any input value, such as the prompt, and the run fails instead of rendering.

```json theme={null}
{ "subject_id": "subject-002", "references": { "face": ["..."] }, "description": "force_fail" }
```

## Testing webhooks

Send a sample event of any type to your sandbox endpoints. This needs the `webhooks:write` scope:

```bash theme={null}
curl -s -X POST https://api.omnichar.org/v1/webhooks/test \
  -H "Authorization: Bearer $OMNICHAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"char.ready"}'
```

The sample is signed like a real event and its `data` carries `"test": true`. See [Webhooks](https://docs.omnichar.org/api/webhooks.md).


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