Publish a sandbox port without exposing private work

Publishing changes who can reach the service

Lupin's publish-port route exposes a sandbox port through a public HTTPS URL. That is useful for an authorized preview, but it changes the network audience of the process running there. A service that is acceptable on a private loopback interface may expose debug controls, files or unauthenticated data when published. Decide what the preview should reveal and implement application authentication before requesting the URL. Do not assume that an obscure generated address is an access-control mechanism or that the Lupin API key protects requests made to the published application itself.

Check the service before creating the endpoint

Start the intended application inside the sandbox using an appropriate bounded process-management approach, then verify that it responds on the chosen port from within the environment. Check the correct content, account context and error behavior. A successful process launch does not prove that its initialization or dependency loading finished. The port route accepts an integer from one through 65535 and invokes the provider's host command. It does not start your application automatically. Publishing a valid port number with no listening service can therefore produce an endpoint that cannot serve the expected preview.

Send the command-backed mutation correctly

Port publication requires container_update permission and, in a durable deployment, a preserved Idempotency-Key because it uses the metered command path. Keep the resource identifier, port and operation identity in the task record. A lost response is a reason to inspect the published-port list and provider state before issuing another publication attempt. The returned response contains port and url when the command succeeds. The current list endpoint extracts URLs from provider output and may not include a numeric port for each item, so do not build a mapping that assumes every list item carries that field.

curl -X POST "https://api.lupin.sh/v0/containers/$CONTAINER_ID/ports" \
  -H "Authorization: Bearer $LUPIN_API_KEY" \
  -H "Idempotency-Key: preview-port-3000-001" \
  -H "Content-Type: application/json" \
  -d '{"port":3000}'

Apply access controls in the application

Require the intended user authentication, disable unnecessary debug endpoints and avoid serving the whole task directory as static content. A preview server can accidentally reveal uploaded fixtures, configuration files or source maps containing sensitive material. Verify an unauthenticated request cannot retrieve private data before sharing the URL. Keep API credentials and temporary desktop-shell links out of the page content and logs. The current Lupin container surface does not expose a dedicated port-revocation operation, so a preview design should include a clear service shutdown and resource lifecycle plan instead of promising a revoke button that does not exist.

Treat availability and cleanup separately

A published URL does not turn a finite sandbox into a production hosting guarantee. The runtime lease, provider lifecycle and application process can end independently. If the preview must remain available, confirm the intended hosting product and approved runtime policy rather than quietly keeping a task sandbox running. When review finishes, save the artifact, stop the service as appropriate and stop the sandbox. Verify cleanup and report any unresolved publication or shutdown state. Give the user the working preview URL only after checking its behavior, along with the practical fact that its availability follows the sandbox's lifecycle.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

• docs.boat.dev · long-running-tasks · background-commands ↗Checked 2026-11-05
• docs.boat.dev · security ↗Checked 2026-11-05

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.