sandbox_wire

Switches a declared name between your process in the box and externalBaseUrl, declares a new name on a running box, or points a name at another box or a published version.

Only needed when the box has an externalBaseUrl (passed to sandbox_start or inherited from its environment), or to declare a name on a running box.

• mode: "box": name:port reaches your own process on the service's targetPort in the box.
• mode: "external": name:port forwards HTTP to externalBaseUrl again. Fails when the box has no externalBaseUrl: then every declared service already reaches your process in the box and there is nothing to wire; to send names to your dev, start a box with environment (which brings its externalBaseUrl) or externalBaseUrl.
• Names that share a targetPort are one process and switch together.
• Switching only rewrites routing rules; boxd holds no port for it, so your process can already be running. Connections already open stay open, and new ones follow the new mode.
• port, with an optional targetPort: declares service as a new host name on the running box. It gets its own address and resolves from then on like the names given at start, and name:port reaches targetPort (default: port; required when port is 80 or 9095). mode is ignored: the new name takes the mode of the names already on its targetPort, otherwise it starts external on a box with an externalBaseUrl and box on one without. The name is recorded with the box: it appears in sandbox_status.services and survives a boxd restart. Without web it gets no URL; with web: true, a box made from the new image gets a working URL for this service, even if it is not the first one. On older boxes, adding a second web service this way returns 409 with guidance to start a new box. Address ranges cannot be added this way. A name that is now a link or one of the environment's addresses is taken over in place on boxes with the take-over feature (Taking over a link or an environment address); on older boxes an environment address keeps going through the connector and a link name fails with 409. Giving an existing name a different port or targetPort moves it. targetPort without port fails with 400.
• web: true without port: marks a service already declared as web, so that webUrl and the app's Use it button open it. It does not decide what a sandbox_review card opens: that call names it with open (and port for web). mode is optional: omit it to keep the current routing mode, or provide one to switch routing too. On a new box, every web service has a working URL: the first uses sceneUrl, and the others have their own URLs. On an older box, marking a second service web returns 409 with guidance to start a new box.
• port with fromBox, and an optional fromPort: declares a link to another of your boxes, or re-points an existing link (same service and port). The result is then { "links": [...] }, every link of the box. See Links to other boxes.
• port with version, and optional containerPort and env: declares the name on the running box and starts that published version under it, replacing whatever version ran there before. The result is { "service": {...}, "next": "..." }, the service with its run. See Run a published version.
• scenePaths (instead of service): path prefixes on sceneUrl that the box forwards to externalBaseUrl, such as ["/api"], keeping the path. A page loaded from sceneUrl then calls the environment's API same-origin, so the environment needs no CORS entry for the box's URL (allowing *.box.parallelsandbox.com there would let every account's boxes in). Each call replaces the list; [] clears it. Paths start with /, /_sbx is the box's own, and the box needs an externalBaseUrl. The result is the wiring table with the paths.
• Boxes started before targetPort shipped run an older boxd that does not support it: there, a targetPort different from port fails with 409 and a message saying so. Start a new box, or declare the service on the port your process listens on, without targetPort and not on 80 or 9095.
• The return value is the whole wiring table, also in sandbox_status.wiring: externalBaseUrl, entry (the first service, which sceneUrl opens) and every service with its port, targetPort, address (the name's address in the box; address ranges have none), mode and web; plus dns, each name the box answers itself with its address (declared services and the environment's host names).
• Services inside one docker compose project also reach each other through the compose network.

Every tool and topic is listed in the tool reference.