Skip to main content
When a service runs inside your workspace, it’s only accessible within the VM by default. To make it reachable from the internet, you create an app - a route that maps an internal port to a public URL at {name}.rigbox.dev.

​
How Routing Works

The flow from a running service to a public URL: Each app gets a unique subdomain on rigbox.dev of the form <APP_NAME>.rigbox.dev, where <APP_NAME> is the name you choose when creating the app. HTTPS is handled automatically - your service only needs to listen on HTTP inside the VM.
App subdomains are globally unique across all Rigbox users. If a name is taken, you’ll need to choose a different one.

​
Discover Listening Ports

Before exposing a port, you can check which ports have active listeners inside the workspace.
This scans the workspace for active TCP listeners and returns the port number along with the process name when available. See List Listening Ports for the full response schema.

​
Create an App Manually

If you know the port and want full control over the app name, create it directly. Replace <APP_NAME> with a name of your choice — it will become the public subdomain.
From outside the workspace, add --workspace <WORKSPACE_NAME> to target a specific VM. Pass --kind cli for interactive tools you’ll invoke over SSH rather than expose as a public service. See Create App for the API form.

​
Expose Port Shortcut

rig app expose-port detects the process listening on the specified port and, with --wrap, creates an app route in one call. This is the easiest way to make a service public. Omit --wrap to only detect the process without creating the route.
The command automatically detects the process name and uses it to generate a sensible app name. See Expose Port for details.

​
Reconcile Template Apps

If your workspace was created from a template that defines default apps (like a web server or API), you can ensure those apps exist with a reconcile call.
This checks the template definition and creates any missing apps. It’s idempotent - running it multiple times has no side effects. See Reconcile Apps for details.

​
Check App Health

Before sharing a URL, verify the app is reachable.
If health returns unhealthy, check that your service is actually listening on the correct port inside the VM. Use rig workspace ports to verify.
See App Health for the response schema.

​
App Lifecycle: Start, Stop, Restart

Control the routing for an app without affecting the underlying service:
See Start App, Stop App, and Restart App for the API form.

​
Update an App

You can rename an app or change its port. Renaming an app changes its public subdomain URL. There is no dedicated CLI subcommand for this, so use rig api to send the raw request:
Renaming an app changes its public URL. Any existing links to the old subdomain will stop working immediately.
See Update App for the full schema.

​
Delete an App

Deleting an app removes the public route. The service inside the VM is unaffected.
See Delete App for the API form.

​
Complete Example: Deploy a Python Server

This walkthrough starts a Python HTTP server inside a workspace and exposes it to the internet.

​
Start a service inside the VM

SSH into your workspace and start a simple Python server:

​
Expose the port

From inside the same workspace (or from your laptop with --workspace <NAME>):
rig app new prints the resulting subdomain — https://my-server.rigbox.dev. If you’d rather have Rigbox detect the listening process and pick a name automatically, the Expose Port API endpoint does both in one shot.

​
Verify health

For programmatic health checks via Rigbox’s own probe, see App Health.

​
Share the URL

Once healthy, anyone with the URL can access your service (if visibility is set to public). See App Visibility to control access.

​
Next Steps

  • App Visibility - control who can access your apps
  • Catalog Apps - install VS Code, Jupyter, and more (routing is handled automatically)
  • Workspaces - workspace lifecycle management