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 testDescription#
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.
--resetdrops 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 testSee 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.