Osy#betaRun it on Osyrin: osyrin.com

Reference / Local

Running the toolchain in a sandbox

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

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.

stablelocalcli

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#

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

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#

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:[email protected]:5463 osy test

See also#

Running a local platform — what a local platform is, and how the loop starts one per project.

Listing your local platforms — the platforms this machine (or this OSY_MACHINE_HOME) has.

Reclaiming the disk your local platforms use — deleting the platforms you no longer use.

Checking your app — validate, lint and test in one verdict.

Related

Running a local platform

Runs a full platform on your own machine — its own database, no account, no cloud, reachable only from your computer…

Listing your local platforms

Lists every local platform on this machine and says which are still running. The build-and-test loop starts one per…

Reclaiming the disk your local platforms use

Each local platform carries its own database, so they add up fast. This deletes the ones you are no longer using —…

Checking your app

Checks your app against production best-practice rules and reports where it falls short — the maturity signal, beside…