# 3D sandbox recipe

URL: https://briq.cloud/cookbook/3d-sandbox

> Blender, FreeCAD, CadQuery and OpenSCAD for creating 3D assets with scripts. Run Blender Python with briq_exec for meshes, materials, GLB and CPU renders; cad-python for dimensioned CAD and STEP/STL; freecad-python for FreeCAD documents; openscad for .scad models. Files stay in /work. CPU only; AutoCAD and native DWG tools are not included.

Tags: sandbox, 3d, cad

Guide:

- [Create 3D assets](https://briq.cloud/docs/guides/create-3d-assets.md): Create meshes, rendered previews and dimensioned CAD parts in a sandbox with Blender, FreeCAD, CadQuery and OpenSCAD.

## Run it

CLI:

```bash
briq run 3d-sandbox
```

MCP:

```ts
briq_run({ recipe: "3d-sandbox", wait: true })
```

REST:

```bash
curl -X POST https://api.briq.cloud/v1/briqs \
  -H "Authorization: Bearer $BRIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipe": "3d-sandbox",
    "wait": true
  }'
# → { "briqs": [{ "id": "bq_…", … }], "outputs": { "SANDBOX_HOST": "…" }, … }

# ... when done, for each briq id
curl -X DELETE https://api.briq.cloud/v1/briqs/<id> \
  -H "Authorization: Bearer $BRIQ_API_KEY"
```

briq.yaml:

```yaml
stack: app
services:
  sandbox:
    recipe: 3d-sandbox
    # its defaults, each a field you can set:
    # image: ghcr.io/briq-cloud/sandbox:3d
    # size: small
    # volume: { gb: 10 }
```

## Fields

Set them beside `recipe`, in briq_run or a briq.yaml service, as a GitHub Actions service.

| Name | Type | Options | Default | What it does |
| --- | --- | --- | --- | --- |
| `image` | string | — | "ghcr.io/briq-cloud/sandbox:3d" | Another 3d tag of ghcr.io/briq-cloud/sandbox, or an image with sh and the tools your scripts need. Use a 3d date tag to keep tool versions |
| `env` | record | { key: string \| { secret, value?, literal?, scope?, hosts?, locations? } } | {} | Added to the sandbox's environment. A credential as { secret: NAME, value }. One only the steps need (a clone, a private registry) as { secret: NAME, value, scope: "boot" }: a variable of the steps, then gone, never in the environment briq_exec runs in. A credential the code calls an API with, as { secret: NAME, value, hosts: ["api.stripe.com"] }: a placeholder here, the real value put in by the team's credential gateway on the way to those hosts only. A team secret (briq_secrets) as { secret: NAME, scope: "team" }: the same, with the value held by the team |
| `steps` | object[] | — | — | Shell commands run in /work at each start, before the sandbox is ready: [{ run: "git clone https://x:$GITHUB_TOKEN@github.com/acme/shop ." }, { run: "npm ci" }]. A failed step fails the start; briq_logs shows why |
| `cmd` | string \| string[] | — | — | The long-lived process, after the steps. Default: none (the sandbox waits for commands). A server here keeps serving on $PORT |
| `size` | enum | pico, micro, nano, small, medium, large, xlarge | "small" | small for simple models and smoke tests; medium or large for CPU rendering, detailed meshes and CAD booleans |
| `volume` | object | { gb? } | {"gb":10} | The volume at /work: { gb } |
| `files` | record | { key: string \| { base64 } } | — | Boot files, written at each start: { "/work/check.py": "…" } |

## Outputs

Returned by `briq_run` once the stack is healthy. Hosts resolve inside your team network; secrets are generated per run.

| Output | Value |
| --- | --- |
| `SANDBOX_HOST` | `sandbox.<stack>.internal` |
| `WORKDIR` | `/work` |
| `PORT` | `8080` |

## What it runs

| Briq | Image | Ports | Size | Volume |
| --- | --- | --- | --- | --- |
| sandbox | `ghcr.io/briq-cloud/sandbox:3d` | 8080 | small | 10 GB at /work |

## When to use it

* Meshes, materials, scenes and CPU renders with Blender Python.
* Dimensioned parts with CadQuery, FreeCAD or OpenSCAD.
* Asset inspection with trimesh, or DXF drawings with ezdxf.

Step by step: [Create 3D assets](https://briq.cloud/docs/guides/create-3d-assets).

## Tips

* **Choose the tool**: Blender for visual assets; CadQuery for precise parts; FreeCAD for `.FCStd`; OpenSCAD for `.scad`.
* **Use the right Python**: Blender runs `bpy`; `cad-python` runs CadQuery, trimesh and ezdxf; `freecad-python` runs FreeCAD.
* **Keep source and exports**: save scripts, `.blend` and `.FCStd` alongside GLB, STEP or STL in `/work`.
* **Render on CPU**: use Cycles with `scene.cycles.device = 'CPU'`. GPU acceleration and a desktop are not included.
* **Check the result**: inspect a PNG, dimensions and mesh topology before delivering the asset.
* **Long jobs**: use `briq_exec` with `async: true`, then read the same exec with `briq_exec_result`.
* **Large exports**: use `briq files-get`; MCP file transfers accept 1 MB per file. See [CLI](https://briq.cloud/docs/cli).
* **AutoCAD**: native AutoCAD and DWG conversion are not included. Use DXF for drawing interchange.
