Skip to content

Container domain names

Each container in OrbStack has a domain name, container-name.orb.local, or service.project.orb.local for Compose. This makes it easy to access services, especially for large projects, where port forwards can quickly get messy and hard to remember.

It's zero-config: just use the container name and visit the domain in your browser (or another application). Port numbers are not needed for web services — no need to remember localhost:3000 vs. localhost:8080.

You can also add custom domains and wildcards.

Screenshot of OrbStack domains

Compose projects

Within a Compose project, service domains are grouped by project name: service.project.orb.local. The project name is usually the name of the folder that contains docker-compose.yml.

For example, a project named nextbigthing with services api and database would have the following domains:

  • api.nextbigthing.orb.local
  • database.nextbigthing.orb.local

HTTPS

OrbStack provides secure, zero-setup HTTPS for all container domains, complete with dynamic certificate generation, installation, and reverse proxying. Just visit https://orb.local to get started, or change http:// to https:// when connecting to a container.

See HTTPS for containers for more information.

Custom domains

To add custom domains to a container, set its dev.orbstack.domains label to a comma-separated list of domains:

bash
docker run --rm -l dev.orbstack.domains=foo.local,bar.local nginx
docker run --rm -l dev.orbstack.domains=foo.local,bar.local nginx

Or with Compose:

yaml
services:
  nginx:
    image: nginx
    labels:
      - dev.orbstack.domains=foo.local,bar.local
services:
  nginx:
    image: nginx
    labels:
      - dev.orbstack.domains=foo.local,bar.local

Wildcards are also supported: dev.orbstack.domains=*.foo.local,*.bar.local

Custom TLDs

Only domains under the .local TLD are supported at this time.

Mirroring production domains

This makes it possible to replicate the layout of your production environment locally to reduce context switching:

  • orbstack.dev ↔ orbstack.local
  • docs.orbstack.dev ↔ docs.orbstack.local
  • api.orbstack.dev ↔ api.orbstack.local

Wildcards

Default domains are also wildcards, meaning that subdomains such as *.container.orb.local will resolve to container.orb.local. This can be used for reverse proxies, for example.

To add custom wildcard domains, use *.example.local.

Index page

When OrbStack is running, you can visit orb.local in your browser for links to all running containers.

Screenshot of index page

Ports

Unlike localhost, there's no need to use port numbers when connecting to web services by domain. Web server ports are detected automatically.

You can still use ports when referring to other services, e.g. database.stack.orb.local:5432 for Postgres.

Override port

In some cases, if your container has multiple servers, OrbStack may not be able to detect the correct port. To fix this, use a label to specify a port explicitly: dev.orbstack.http-port=8080

This port is also used by the automatic HTTPS proxy to connect to your container.

Kubernetes

OrbStack also supports Kubernetes' standard cluster.local domains, such as service.namespace.svc.cluster.local.

Linux machines

Similar to containers, each Linux machine has a domain name at machine-name.orb.local.

Compatibility

Container domains currently depend on the direct IP access feature, so make sure "Allow access to container domains & IPs" is enabled in Settings → Network.