# Running the toolchain in a sandbox

> Three environment variables that let `osy test`, `osy launch` and `osy validate` run where the process may not write your home folder, has no network and cannot start PostgreSQL itself: a private folder for the machine's local platforms, a read-only package cache, and a PostgreSQL on loopback to use instead of the built-in one.

<!-- id: local-running-in-a-sandbox · area: local · stability: stable · html: https://osysharp.com/reference/local/running-in-a-sandbox/ -->

## Summary        {#summary}

A local platform normally keeps its state under `~/.osy`, fills the package cache under `~/.osy/packages` and starts
its own PostgreSQL. Inside a sandbox — an agent session that may write only its project and one private folder, with
no network — none of that works. These three variables move each part somewhere the sandbox allows.

## Signature      {#signature}

```console
OSY_MACHINE_HOME=<dir> OSY_PACKAGES=<dir> OSY_LOCAL_POSTGRES=postgres://<user>:<password>@127.0.0.1:<port> osy test
```

## Description    {#description}

**`OSY_MACHINE_HOME` — where this machine's local platforms live.** It moves everything a running local platform
writes, all at once: the instances (`instances/`), the record of running databases (`run/`), the downloaded
PostgreSQL (`pg/`, unless `OSY_PG_DIR` says otherwise), the browser for screenshots (`browser/`, unless
`OSY_BROWSER_HOME` says otherwise), a second Studio's folders and the caches a platform keeps. It is a separate
variable from `OSY_HOME` on purpose: `OSY_HOME` moves the toolchain's own files and leaves the machine's one list of
platforms alone, while `OSY_MACHINE_HOME` says "this is a separate machine" — `osy instances`, `osy stop` and the
clean-up of unused platforms then see only the platforms under it.

**`OSY_PACKAGES` — the package cache.** Precedence: `OSY_PACKAGES`, then `OSY_HOME/packages`, then `~/.osy/packages`.
The folder may be **read-only**: fill it once where the network is available (for example `osy lock` run with the same
`OSY_PACKAGES`), and the sandboxed run reads from it without writing anything. A package the cache does not hold is
refused with a sentence naming the folder and the variable, rather than an "access denied".

**`OSY_LOCAL_POSTGRES` — a PostgreSQL to use instead of the built-in one.** For a sandbox that cannot start
PostgreSQL itself, point it at a server running somewhere it can reach — typically a container published on
`127.0.0.1`. Only a server on **this computer** is accepted (`127.0.0.1`, `::1` or `localhost`); any other host is
refused when the platform starts, because a database elsewhere is a production one. The URL names a superuser; the
local platform then signs in as a role of its own, `osy_local_platform`, which owns every database it creates.

- **One local platform per server.** The platform's own databases have fixed names, so a second local platform
  pointed at the same server is refused, naming the first. Give it a server of its own, or stop the first and remove
  its folder — the next start then takes the server over.
- **`--reset` drops only that platform's databases**, then its role. Any other database on the server is never
  touched.
- Nothing is downloaded: with this variable set the built-in PostgreSQL is not needed.

With all three set (and `OSY_HOME` pointing at a private folder too), `osy test` writes nothing under `~/.osy`.

## Examples       {#examples}

```console
docker run -d -p 127.0.0.1:5463:5432 -e POSTGRES_USER=platform -e POSTGRES_PASSWORD=platform pgvector/pgvector:0.8.0-pg17
OSY_PACKAGES=$PWD/.pkgs osy lock                      # once, with the network, to fill the cache
OSY_HOME=$PWD/.osy-home OSY_MACHINE_HOME=$PWD/.osy-machine OSY_PACKAGES=$PWD/.pkgs \
  OSY_LOCAL_POSTGRES=postgres://platform:platform@127.0.0.1:5463 osy test
```

## See also       {#see-also}

[Running a local platform](https://osysharp.com/reference/local/running-a-local-platform/) — what a local platform is, and how the loop starts one per project.

[Listing your local platforms](https://osysharp.com/reference/local/listing-local-instances/) — the platforms this machine (or this `OSY_MACHINE_HOME`) has.

[Reclaiming the disk your local platforms use](https://osysharp.com/reference/local/reclaiming-local-disk/) — deleting the platforms you no longer use.

[Checking your app](https://osysharp.com/reference/local/checking-your-app/) — validate, lint and test in one verdict.
