REFERENCE

Service

Reference for Box Service names, ports, lifecycle, and limits.

Box Service gives an active exec a private TCP endpoint that other boxes in the same org can reach. Expose Ports walks through the full workflow; this page keeps the exact flag syntax, DNS form, and limits in one place.

Flag

--service name:target_port[:port]

Example:

run9 box exec-bg api --service web:8080:30080 ./serve

DNS name

Other boxes call:

web.svc.run9.internal:30080

The service forwards to 127.0.0.1:8080 inside the target box.

Limits and scope

Same org only.
TCP only.
No public ingress.
No load balancing.
No readiness probe.
Up to 8 services per exec.
Each active service name and chosen port is unique within the org.

If port is omitted, run9 allocates a port in 30000-32767.

Lifecycle

The service is bound to the exec that declared it. When the exec ends, the service is released. If you need the endpoint again later, start another exec that declares the service again.

When a service is declared on an exec, the CLI prints the resolved endpoint as local metadata. For foreground exec streams, that metadata goes to local stderr so remote stdout stays clean.

First checks when a service is unreachable

Use the exec_id from the original box exec-bg output, or find it again with:

run9 box execs ls api

Then inspect that same exec before you change the client:

run9 box exec-bg pull-output <exec-id> --from-start
run9 box execs inspect <exec-id>

If the server process exited, the service is already gone. Start another exec that declares the service again.