Taking over a link or an environment address

On newer boxes, sandbox_wire puts your own process or a published version under a name that went out through a link or the connector, in place, keeping the box's URLs.

On a box whose sandbox_status → health.features includes take-over, which every box started from 2026-09-25 12:40 UTC has (image box-202609251946; a box keeps the boxd it started with, across freezes), sandbox_wire can put a service of the box under a name that now goes out of the box, through a link or through the connector:

sandbox_wire { "id": "<id>", "service": "billing.acme.internal", "port": 8080, "targetPort": 8081 }
sandbox_wire { "id": "<id>", "service": "billing.acme.internal", "port": 8080, "version": "refund-a1b2c3d", "env": { "WORKERS_ENABLED": "false" } }

• The first form is your own process on targetPort; the second a published version (with env and containerPort as usual). Either one, on a name:port that is a link or one of the environment's addresses, takes that name over in place.
• The name keeps its address in the box, so programs that cached its DNS answer keep working; from then on it reaches targetPort in the box.
• Connections open through the link or the connector are closed; programs reconnect, now to the box's copy.
• A link stops being a link: fromBox and fromPort leave sandbox_status.services, and the other box's linkedFrom no longer lists this box. The box keeps its URLs.
• The name must be taken over on the port it goes out on; on another port the call fails with <name> is reached through the connector or a link on port [<port>]; a name cannot be a service in the box on port <n> and go out on another. A name that goes out on several ports (an environment listing db.internal:5432 and db.internal:6432, say) cannot be taken over on one of them either: <name> is also reached through the connector or a link on port [<port>]; a name cannot be a service in the box on one port and go out on another. A name cannot be a service in the box on one port and go out on another. Declare such a name at sandbox_start instead, where it points at the box on every port.
• A mode switch on a link name always fails with 409: <name> is a link in this box, which has no box or external mode. Wire it again with fromBox or fromPort to change where it goes, or pass port (and targetPort) to run the service in the box instead.

On older boxes, without take-over in health.features:

• a link name with port fails with 409 <name> is a link in this box, and box <id> runs boxd <version>, which cannot turn a link into a service in the box. Wire it again with fromBox or fromPort to change where it goes, or start a new box that declares the service, and with version: <name> is a link in this box, and box <id> runs boxd <version>, which cannot turn a link into a published version. Start a new box that declares the version, or wire the link again with fromBox or fromPort;
• a name added with port or version that is one of the environment's addresses keeps going to the connector; declare such names at sandbox_start instead.

Every tool and topic is listed in the tool reference.