ParallelSandboxOpen app

Run a published version

A service declared with version runs a published image under its name, with no build: how the box pulls and starts it, extra variables in env, and how to follow and switch it.

A service declared with version runs a published image under its name, with no build and no docker run of yours:

sandbox_start { "name": "web on the refund billing", "goal": "Run the web front end against the published refund billing; done when a refund placed in the browser is recorded by that billing", "environment": "dev", "services": [{ "name": "billing.acme.internal", "port": 8080, "version": "refund-a1b2c3d" }] }
sandbox_wire  { "id": "<id>", "service": "billing.acme.internal", "port": 8080, "version": "refund-a1b2c3d" }
  • version is a label or a versionId from sandbox_versions. A label published for several services picks the version whose service equals the name or its first DNS label (billing for billing.acme.internal); otherwise the call fails with 400 listing service/label → versionId, and you pass the versionId. An unknown one fails with 400 no published version with label or id "…"; sandbox_versions lists them.
  • Control resolves the version when the box starts and picks the targetPort: port itself, unless it is 80 or 9095 or another service of the box uses it, then the first free port from 20000 up. You can also pass targetPort. sandbox_start returns at once; name:port reaches the container from the box's programs and containers once it runs.
  • After the box is ready, one background command (its note is start published <service>@<label>) runs docker pull, then docker run -d --restart unless-stopped --name psbx-svc-<name> -p <targetPort>:<container port> [--env-file /work/.sbx/env/<service>.env] [-e NAME=value …] -e SBX_BOX_ID <image>, and waits up to 120 seconds for the container to listen. <service> is the service the version was published for; its settings file is passed when the box's environment has one. Nothing else is passed in, apart from env (next item). On a box with an externalBaseUrl, the name is switched to box first.
  • env (only with version) is a map of extra environment variables for the container, for example { "SENTRY_ENVIRONMENT": "psbx", "WORKERS_ENABLED": "false" }. They come after the settings file, so a name in both takes the env value, and they are passed exactly as given, quotes and $(…) included. Names follow shell-variable rules (letters, digits and _, not starting with a digit); SBX_BOX_ID cannot be set; at most 64 variables, 4 KB per value and 32 KB in all. The values show in sandbox_status, so put no secrets in them. Wiring the version again replaces the whole env with the one you pass. env without version fails: at sandbox_start with services[<i>] (<name>): env goes with version, the published version to run; for your own process pass -e to docker run (400), in sandbox_wire with the same message without the services[<i>] (<name>): prefix.
  • The container port is containerPort when you pass it, otherwise the image's one EXPOSEd TCP port, otherwise port. An image that EXPOSEs several TCP ports needs containerPort; without it the start fails with the image exposes several TCP ports (…); declare the service with containerPort.
  • sandbox_status → services[].run shows how it went: state (not_started, starting, running, exited, failed, or unknown when the box cannot be asked), image, versionId, label, container, logPath (the start command's log) and error, which carries the end of that log when it failed. Messages include docker pull failed for <image> (the image is missing from the registry: the pull says not found), the container exited before it listened on port N (restarts: M) and the container did not start listening on port N within 120 s, followed by the container's last log lines.
  • The version is started once per box: the container keeps running across a boxd restart, and Docker restarts it if it exits (--restart unless-stopped).
  • To switch a name that runs a version to another one, call sandbox_wire with the same service and port and the new version. This works for a name declared with version at sandbox_start, environment addresses included: the container psbx-svc-<name> is replaced, run starts again from starting, and the name keeps its targetPort. On a box we tried, switching to a version whose container crashed left run.state failed, and switching back brought it to running again.
  • Rules: a service cannot be both a link and a version (400 a link cannot also run a published version; use either fromBox or version); containerPort needs version; on a running box version needs port; on boxes without the take-over feature a name that is a link cannot take a version (409); image and run sent by you are ignored.
  • Every box is logged in to the account's registry; a box that was frozen for 10 hours or more gets a fresh login when it is thawed, so pulls keep working after long freezes.
  • On a box with the take-over feature, sandbox_wire with version also takes over an environment address that was not declared at start, and a link (Taking over a link or an environment address). On older boxes it does not: the version starts and run.state shows running, but the name keeps going to the connector and the container answers only on 127.0.0.1:<targetPort>; declare such names at sandbox_start there.

Every tool and topic is listed in the tool reference.