Skip to content

Host ports leased with the device #162

Closed as not planned
Closed as not planned

Description

@V3RON

Request: #155

Problem

A lease isolates a device but not the host ports the work needs. Two agents on one machine start a dev server, a mock API, or a debug proxy on the same default port. The second start fails, or it talks to the first agent's server without noticing. Each agent picks ports on its own, so nothing stops the race. Today teams hand out port ranges by hand.

Who it is for

Parallel coding agents that build and run apps against Simlock devices on one machine: several agents on a local worker, or several CI jobs sharing one. Any app type: native iOS and Android, cross-platform frameworks, anything with a local backend.

Outcome

  • A lease request can ask for a number of host ports. The grant lists them. A request that asks for none gets none, and nothing changes for existing callers.
  • Every port in a grant comes from a configured range. No two live leases hold the same port. A port Simlock itself listens on, or hands to an emulator, is never in a grant.
  • A port was not in use on the host when it was picked. What the holder runs on it afterwards is the holder's business.
  • --export-env exports the ports as shell variables next to the existing ones, so a script gets its ports with no parsing.
  • The same request field and grant field work over the unix socket, the HTTP API, and MCP.
  • An Android emulator leased with ports can reach them on the host without the agent doing anything beyond starting its server. iOS simulators share the host's network, so localhost:<port> already works there.
  • The ports are freed when the lease ends, however it ends: release, expiry, release --all, nuke, or a lost device. They stay with the lease across a daemon restart, as the lease does.
  • simlock status and lease listings show each lease's ports.
  • Through a gateway, the ports are on the worker that owns the device, the same as the rest of the grant's environment. The grant says so. Renew and release need no change.

Non-goals

  • Knowing what runs on a port. Simlock does not start, stop, watch, or name the process. No bundler, framework, or tool is named in config, flags, output, or code.
  • Forwarding a port between machines. Through a gateway or over HTTP the ports are reported, not tunnelled. That is the data plane the gateway design leaves out.
  • Reaching a port on the device from the host (the other direction).
  • Adding or changing ports after the grant. Ports are fixed for the life of the lease.
  • Ports without a device. A port is only ever part of a device lease.
  • Routing a fleet request by port availability. Routing is unchanged.

Completion conditions

  • simlock lease --platform android --device 'Pixel 8' --detach --ports 2 prints a grant with two distinct ports inside the configured range. The same holds for --platform ios.
  • lease_simulator over MCP and POST /v1/lease-requests accept the same field and return the same ports on the lease.
  • Two leases granted at the same time never share a port. A port freed by one lease can be granted to the next.
  • --export-env prints one export line per port next to the existing variables.
  • A request that asks for no ports gets a grant that names none. simlock lease without the flag behaves exactly as on main.
  • A port that another process was listening on when the lease was granted is not in the grant.
  • With a server listening on a leased port on the host, a client inside the leased emulator reaches it. How it is addressed is open question 2.
  • After simlock release, lease expiry, simlock release --all, simlock nuke, and a device lost mid-lease, every port of that lease is free for the next grant, and a server the holder left listening on it is still running.
  • The ports are still on the lease after simlock daemon stop and simlock daemon start.
  • simlock status and simlock lease list show each lease's ports.
  • A configured range that overlaps http.port, drivers.android.adbServerPort, or the emulator console and adb ports is refused, naming the key. See open question 5.
  • A request that asks for more ports than the range can give right now gets the answer in open question 3, never a partial grant.
  • Through a gateway, a lease with ports is granted, renewed, and released, and the ports are freed on the worker when it ends.
  • docs/CLI.md, docs/CONFIGURATION.md, docs/HTTP-API.md, docs/CLIENT.md, and both EVENTS.md files describe the field, the variables, the config keys, and any event change.

Open questions

  1. Ask by count or by name? Recommended: a count (--ports <n>, ports: n), exported as SIMLOCK_PORT_1 to SIMLOCK_PORT_n. Names can be added later without breaking this.
  2. How does the emulator reach a host port? (a) localhost:<port> inside the emulator reaches the host's port, set up by Simlock at grant and again when it reboots the emulator during crash recovery. (b) The grant names the emulator-side address (10.0.2.2:<port>) and the app has to use it. Recommended: (a). It is the only reading of "no extra steps", and the port number is the same on both sides.
  3. When the range cannot serve the request: fail at once with a closed error code, or wait in the queue like device capacity? Recommended: fail at once. With the default range, exhaustion means misconfiguration, and waiting would need the gateway to track port availability per worker.
  4. Defaults for the range and the per-lease cap? Recommended: 20000-20999 and at most 16 per lease, both configurable. That sits below the OS ephemeral range and above every port Simlock uses.
  5. A range that overlaps Simlock's own ports: refuse at daemon start naming the key, or skip those ports at grant time? Recommended: refuse at start, as the other contradictory config pairs do.
  6. Should the pick check the host for a listener, or only Simlock's own bookkeeping? Recommended: check the host, best effort. A server left behind by a previous holder is the common failure.
  7. Through a gateway the ports are reported and not forwarded, as Non-goals say. Confirm.

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    on Sep 28, 2026
  2. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Closing: this is not going to happen soon. We may come back to it when a user asks for it.

    Written by an agent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:specSpec in progress, business and technical together.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions