Running a local platform

Summary#

Runs a complete platform on your own machine, with a database it starts and manages itself. Nothing outside your computer can reach it, it needs no account and no cloud project, and the only difference from a hosted platform is which address you point at. It is what Running tests locally and Debugging tests locally run against.

Signature#

osyrin dev [--devname <name>] [--port <n>] [--keepalive <minutes>] [--reset]

Description#

Starting it#

Run it from your project directory and leave it running in a terminal:

osyrin dev

The first start downloads a small database bundle once; after that it is up in a few seconds. It binds to your machine only, so nothing on the network can reach it. Your local data persists between runs — stop and restart and it is still there. --reset throws that data away and rebuilds from your source.

One server per project, on a stable address#

Each project gets its own local platform, and it always answers on the same address — the port is derived from the project, so a bookmark keeps working across restarts and two projects (or two checkouts of the same repo) never fight over a port. --port overrides that when you need a specific one. Because the address is derived, the other commands find the running server on their own; you never have to tell them where it is.

Starting osyrin dev again for the same project reclaims the one already running rather than leaving it stranded: there is only ever one server per project, and a restart takes the place of the old one instead of piling up beside it.

--devname <name> gives the server an explicit identity instead of deriving it from the project directory — its data, its address and its one-per-identity reclaim all follow the name. Use it to run a second, separately-named platform from the same directory, or one shared platform from several. Every other command takes the same --devname, so point compile, test, launch or logs at a named server with the flag, or set OSY_DEVNAME once for the whole shell.

A name is the only way to say which platform you mean: a command never takes a data directory, so the path is always derived from the identity. That is deliberate — when two commands name the same identity they cannot reach different platforms, so a compile can never quietly land somewhere other than the app you are looking at.

It stops itself when you walk away#

By default a server that has gone 60 minutes with no requests exits on its own, so an abandoned one does not keep a whole platform and its database running until you notice. When it does, it says so plainly in its output — that it exited because it was idle, and how to change the window — so a server that is gone when you come back is never a mystery. --keepalive <minutes> sets the window; --keepalive 0 turns the behaviour off and the server runs until you stop it. An attached debugger keeps it alive: a paused breakpoint sends no requests, but the server will not be reaped out from under you.

Or let the loop start it for you#

You do not have to start it by hand. When you run Compiling your app, Running tests locally, or Launching your app and no local platform is running for the project, they start one for you in the background, wait for it to be ready, and leave it running so the next command is fast. The whole loop is one command — you never have to remember to start (or restart) a server. When you're done, Stopping the local platform shuts it down; its database stops with it, so nothing is left running.

You are the administrator — no login#

On a machine-only platform the person at the keyboard is the administrator, so the operator commands need no credentials: login, whoami and connect simply report that and continue. This applies only to the platform's own operator commands. Your application's security is unchanged and behaves exactly as it does in production — a test runs as an anonymous, secured caller, your app's own login works, and your access rules are enforced. Local is faster and private; it is never a relaxed rulebook.

An organization is already there#

A local platform comes with a single ready-made organization, so there is no organization-and-user dance before you can create an app. org list shows that one organization and org create reports it (there is nothing to create locally). Apps you create belong to it, and are reachable by their plain name — an app named in your project is served at http://<app>.localhost:<port>/.

What works, and what says so when it can't#

Everything the local loop needs works: validate and build, run and debug tests, create and compile an app, launch it, manage its users, read its logs, and set its secrets. A handful of commands describe operations a machine-only platform cannot perform — taking cloud backups, publishing or deploying a release, and the like. Those fail loudly with a clear reason and a non-zero exit; they never report success for something that did not happen. If a command can't do the thing here, it tells you plainly.

It is for development, not hosting#

A local platform is a fast, private place to build — not a place to run something for real. It has no backups, no sharing, and no durability, and it is deliberately unsuitable for hosting. Durability lives on a hosted platform; keep anything that matters there.

Examples#

The everyday loop — one platform, many runs, all offline:

# terminal 1
osyrin dev

# terminal 2
osy test
osy test --filter Totals

Reset the local data and start fresh:

osyrin dev --reset

Keep a server running with no idle timeout, on a port you choose:

osyrin dev --keepalive 0 --port 8099

Run a second, separately-named platform from the same project, and point the other commands at it:

# terminal 1
osyrin dev --devname scratch

# terminal 2
OSY_DEVNAME=scratch osy compile

See also#

Running tests locally — run your app's tests against this local platform.

Debugging tests locally — debug a single test against it, with breakpoints in your editor.

Launching your app — open your app in a browser on this local platform.

Compiling your app — compile your source into your app on this local platform.

Stopping the local platform — stop the local platform serving your project.